API Documentation

Render a card — cURL

curl "https://getcardforge.dev/api/v1/card?template=og-gradient&title=Launch%20day&subtitle=We%20are%20live&accent=%23ff5533"   -H "X-API-Key: cfg_your_key_here"   -o card.png

Render a card — JavaScript (fetch)

Works in Node 18+ and the browser. Build the query, send your key in the X-API-Key header, and read the response as a Blob/Buffer.

const params = new URLSearchParams({
  template: "og-gradient",
  title: "Launch day",
  subtitle: "We are live",
  accent: "#ff5533",
  format: "webp",   // png (default) | jpeg | webp
  size: "twitter",  // og | twitter | linkedin | instagram | square
});

const res = await fetch(
  `https://getcardforge.dev/api/v1/card?${params}`,
  { headers: { "X-API-Key": "cfg_your_key_here" } },
);
if (!res.ok) throw new Error(await res.text());

const bytes = Buffer.from(await res.arrayBuffer());
await require("node:fs/promises").writeFile("card.webp", bytes);

Render a card — Python (requests)

import requests

params = {
    "template": "stat-card",
    "title": "Monthly active users",
    "value": "+128%",
    "trend": "up",
    "format": "jpeg",   # png (default) | jpeg | webp
    "size": "linkedin", # og | twitter | linkedin | instagram | square
}
res = requests.get(
    "https://getcardforge.dev/api/v1/card",
    params=params,
    headers={"X-API-Key": "cfg_your_key_here"},
    timeout=20,
)
res.raise_for_status()
with open("card.jpg", "wb") as f:
    f.write(res.content)

Embed the public demo (watermarked)

The /api/demo endpoint needs no key, works in any img tag and adds a small cardforge.dev watermark. Great for trying templates before you redeem.

<img
  src="https://getcardforge.dev/api/demo?template=quote-card&title=Stay%20hungry&author=Steve"
  width="540" alt="Quote card" />

Templates & sizes

Size presets

Add size= to force a platform dimension on any template — handy for the same card at Twitter, LinkedIn and square sizes.

curl "https://getcardforge.dev/api/v1/card?template=og-minimal&title=We%20are%20hiring&size=linkedin&logo=https%3A%2F%2Fcdn.example.com%2Flogo.png"   -H "X-API-Key: cfg_your_key_here" -o linkedin.png

Output formats

Add format= to choose the encoding. PNG is the lossless default; JPEG and WebP are smaller and ideal for crawler-facing images.

Signed URLs (key-less, edge-cached)

Social crawlers fetch an og:image URL many times and cannot send headers. A signed URL carries an HMAC-SHA256 sig that proves it was minted by your account, so it renders withoutan API key and is always served from Vercel's edge CDN on repeat hits — the first render is metered once, every crawler re-fetch is free. Tampering with any parameter invalidates the signature.

// Mint a signed URL server-side (Node) with your signing secret.
import { createHmac } from "node:crypto";

function signCardUrl(params, secret) {
  const sp = new URLSearchParams(params);
  sp.delete("sig");
  // Canonical string: path + params sorted by key, URL-encoded.
  const sorted = [...sp.entries()].sort(([a],[b]) => a < b ? -1 : a > b ? 1 : 0);
  const query = sorted.map(([k,v]) =>
    `${encodeURIComponent(k)}=${encodeURIComponent(v)}`).join("&");
  const sig = createHmac("sha256", secret)
    .update(`/api/v1/card?${query}`).digest("hex");
  sp.set("sig", sig);
  return `https://getcardforge.dev/api/v1/card?${sp}`;
}

// <meta property="og:image" content={signCardUrl({ template:"og-gradient",
//   title:"Launch day" }, process.env.CARDFORGE_SIGNING_SECRET)} />

Bulk generate (paid plans)

POST /api/v1/cards/bulk takes an array of card configs (max 50) and returns a ready-to-use signed URL for each — perfect for pre-generating OG images across a catalogue. Generation is bounded (5 in parallel) to stay within the request timeout; each returned URL is metered when it is first fetched.

curl -X POST "https://getcardforge.dev/api/v1/cards/bulk"   -H "X-API-Key: cfg_your_key_here"   -H "Content-Type: application/json"   -d '{ "cards": [
    { "template": "og-gradient", "title": "Post one", "format": "webp" },
    { "template": "quote-card", "title": "Post two", "author": "Ada" }
  ] }'

# → { "count": 2, "cards": [
#      { "index": 0, "url": "https://getcardforge.dev/api/v1/card?...&sig=...",
#        "width": 1200, "height": 630, "format": "webp" }, ... ] }

Export request history

Pull your recent API requests as CSV or JSON for reporting — the same data the dashboard shows, downloadable with the format query.

curl "https://getcardforge.dev/api/dashboard/requests?format=csv"   -H "X-API-Key: cfg_your_key_here" -o requests.csv

Parameters

All parameters are query-string values. Unknown values never error — they fall back to safe defaults.

Response

Success returns image/png. Errors return JSON:

{
  "error": {
    "code": "UNAUTHORIZED | QUOTA_EXCEEDED | RATE_LIMITED | RENDER_FAILED",
    "message": "Human-readable explanation"
  }
}

Every response carries an X-Request-Id header — include it when contacting support so we can find your exact request in the logs.

Idempotent retries

Mutating endpoints (signup, redeem, checkout) accept an optional Idempotency-Key header. Retrying with the same key replays the original result instead of acting twice — safe for network retries and double-submits.

curl -X POST "https://getcardforge.dev/api/redeem"   -H "Content-Type: application/json"   -H "Idempotency-Key: redeem-9f2c14a8"   -d '{ "code": "CFG-DM-XXXX", "email": "you@company.com" }'

Health check

GET /api/health is a public, secret-free liveness probe for uptime monitors. It returns 200 with the running version and commit.

curl "https://getcardforge.dev/api/health"
# → { "status": "ok", "service": "cardforge", "apiVersion": "v1", "commit": "…" }