API Reference

Authentication

Pass your API key in the Authorization header or as X-Api-Key.

# Bearer token (recommended)
curl -H "Authorization: Bearer sk_your_key" ...

# Header alternative
curl -H "X-Api-Key: sk_your_key" ...

Create account and get first API key

Creates a new account for the given email address and returns an API key. If the account already exists, a new key is issued.

{
  "userId": "clx...",
  "apiKey": "sk_...",
  "plan": "FREE",
  "message": "Account created — save your API key, it will not be shown again"
}

Capture a webpage screenshot

Renders a URL in a headless browser and returns it as a PNG or JPEG image.

# Returns image/png or image/jpeg binary
# Response headers:
X-Usage: 42/1000

curl "https://api.snapcard.dev/v1/screenshot?url=https://example.com&fullPage=true" \
  -H "Authorization: Bearer sk_your_key" \
  --output screenshot.png

Convert a webpage to PDF

Renders a URL in a headless browser and returns a PDF document.

# Returns application/pdf binary
# Response headers:
X-Usage: 5/1000

curl "https://api.snapcard.dev/v1/pdf?url=https://example.com&pageFormat=Letter" \
  -H "Authorization: Bearer sk_your_key" \
  --output document.pdf

Generate a dynamic OG social card

Renders a branded social card image at 1200×630px, suitable for Open Graph / Twitter Card metadata.

# Returns image/png (1200×630)
# Response headers:
Cache-Control: public, max-age=3600
X-Usage: 12/1000

curl "https://api.snapcard.dev/v1/card?title=Hello+World&description=My+subtitle&brand=SnapCard" \
  -H "Authorization: Bearer sk_your_key" \
  --output card.png

Retrieve monthly usage

Returns the current month's request counts per endpoint along with your plan limits.

{
  "usage": [
    { "endpoint": "screenshot", "month": "2026-03", "count": 42 },
    { "endpoint": "pdf", "month": "2026-03", "count": 5 },
    { "endpoint": "card", "month": "2026-03", "count": 12 }
  ],
  "plan": "STARTER",
  "limits": {
    "FREE": 100,
    "STARTER": 1000,
    "GROWTH": 10000,
    "SCALE": 100000
  }
}

curl "https://api.snapcard.dev/v1/usage" \
  -H "Authorization: Bearer sk_your_key"

List active API keys

Returns all active (non-revoked) API keys for the authenticated user's account.

{
  "keys": [
    {
      "id": "clx...",
      "name": "Default",
      "lastUsed": "2026-03-28T12:00:00.000Z",
      "createdAt": "2026-03-01T00:00:00.000Z"
    }
  ]
}

Create a new API key

Creates a new API key. Maximum 10 active keys per account. The full key is returned only once.

{
  "id": "clx...",
  "name": "Production",
  "key": "sk_...",
  "createdAt": "2026-03-29T00:00:00.000Z",
  "message": "Save this key — it will not be shown again"
}

Revoke an API key

Permanently revokes an API key by ID. Revoked keys are rejected immediately.

{ "message": "API key revoked" }

Error codes

All errors return JSON with error and code fields.

{ "error": "Monthly limit reached: 100/100 requests used", "code": "QUOTA_EXCEEDED" }