Docs

API reference

Two ways to get a card: let Cardstock read a page for you, or send the fields yourself.

Site token (recommended)

Create a token for your domain on the account page. It only works for URLs on that domain, so it's safe in public HTML.

GET https://cardstockapi.com/a/TOKEN.png?url=https://yoursite.com/posts/hello

Optional overrides on the same URL: tpl, size, theme, accent, title, subtitle.

Next.js (App Router)

export async function generateMetadata({ params }) {
  const url = `https://yoursite.com/posts/${params.slug}`;
  return { openGraph: { images: [`https://cardstockapi.com/a/TOKEN.png?url=${encodeURIComponent(url)}`] } };
}

Astro

<meta property="og:image" content={`https://cardstockapi.com/a/TOKEN.png?url=${encodeURIComponent(Astro.url.href)}`} />

WordPress

add_action('wp_head', function () {
  $u = urlencode(get_permalink());
  echo '<meta property="og:image" content="https://cardstockapi.com/a/TOKEN.png?url=' . $u . '">';
});

Plain HTML / any template engine

<meta property="og:image" content="https://cardstockapi.com/a/TOKEN.png?url=https%3A%2F%2Fyoursite.com%2Fpage">
<meta name="twitter:card" content="summary_large_image">

Explicit cards

GET https://cardstockapi.com/v1/card.png?tpl=editorial&title=Hello&author=You

Param	Values
tpl	editorial, terminal, ticket, stat, quote
size	og (default), tw, li, sq, story
theme	paper (default), ink
accent	6-digit hex, no #
title	Up to 180 characters
subtitle, kicker, author, meta	Secondary text. meta is the date, price or label on the right.
stat	The big figure for the stat template, e.g. 38s
label	Ticket stub label, default "Admit one"
logo	URL of a PNG/SVG, paid plans only

Authentication

Server-side calls: Authorization: Bearer cs_…. Never put your key in HTML. For browsers, use a site token, or sign a specific card:

curl -X POST https://cardstockapi.com/v1/sign \
  -H "Authorization: Bearer $CARDSTOCK_KEY" \
  -H "content-type: application/json" \
  -d '{"tpl":"quote","title":"Make it boring to ship","author":"Dana"}'
# → { "url": "https://cardstockapi.com/v1/card.png?...&c=cus_…&sig=…" }

Link checker API

GET https://cardstockapi.com/v1/inspect?url=https://example.com
# → { title, description, image, score, issues: [...] }

Free, rate-limited per IP.

Errors and limits

401	Invalid key.
402	Plan limit reached (explicit cards). Site-token requests return a plain fallback card instead.
403	Bad signature, or URL not on the token's domain.
429	Free-tier rate limit.

Cards are cached for a day at the edge. Changing the page's title changes the card URL's content only after the cache expires, add &v=2 to force a fresh draw.