API Reference

The Screenmint base URL is https://api.screenmint.dev. Every endpoint accepts and returns JSON. Render a page in one call: you get back a hosted image URL, ready to drop into an <img> tag or a meta tag.

curl -X POST https://api.screenmint.dev/v1/screenshot \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

{
  "url": "https://cdn.example/screenshots/9f2c….jpeg",
  "width": 1280,
  "height": 720,
  "cached": false,
  "render_ms": 1240
}

Authentication

Authenticate every request with an X-API-Key header. Keys are created and revoked in the dashboard; the plaintext key is shown exactly once at creation, so store it somewhere safe.

X-API-Key: sk_live_...

Rate limits & caching

Two limits apply: a per-minute request rate (per API key, fixed one-minute windows) and a monthly render quota (per account, resets on the 1st, UTC).

Identical requests are cached — screenshots for 1 hour, OG cards for 24 hours. Cache hits return in milliseconds with "cached": true and do not consume monthly renders (they still count toward the per-minute rate).

Errors

Errors return a JSON envelope with a stable error code, an optional human-readable message, and reset_at on 429s.

{
  "error": "rate_limit_exceeded",
  "reset_at": "2026-07-22T18:04:00.000Z"
}

POST/v1/screenshot

Capture a screenshot of any public URL. The page gets a fresh, isolated browser context, waits for the load event (up to 15 seconds), then captures, optimizes, and hosts the image for you.

curl -X POST https://api.screenmint.dev/v1/screenshot \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "width": 1280,
    "height": 720,
    "full_page": false,
    "format": "jpeg",
    "quality": 85,
    "delay": 0,
    "dark_mode": false
  }'

{
  "url": "https://cdn.example/screenshots/9f2c….jpeg",
  "width": 1280,
  "height": 720,
  "cached": false,
  "render_ms": 1240
}

POST/v1/og

Generate a branded 1200×630 Open Graph card from text and colors — no design tools, no templates to host. Output is an optimized JPEG, cached for 24 hours.

curl -X POST https://api.screenmint.dev/v1/og \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "How we scaled to 1M renders",
    "description": "Lessons from running headless Chromium in production.",
    "site_name": "Engineering Blog",
    "bg_color": "#0F0F11",
    "accent_color": "#8B5CF6",
    "text_color": "#ffffff"
  }'

{
  "url": "https://cdn.example/og/def4….jpeg",
  "cached": false,
  "render_ms": 380
}

POST/v1/video

Record a page as a short video — great for capturing animations or a scroll-through of a long page. Output is mp4 (default), webm, or an animated gif.

POST https://api.screenmint.dev/v1/video
{ "url": "https://stripe.com", "seconds": 6, "scroll": true, "format": "mp4" }

→ { "url": "https://cdn.example/videos/e46e….mp4",
    "width": 1280, "height": 720, "seconds": 6, "render_ms": 7100 }

POST/v1/batch

Queue up to 50 renders in one call. Each item is a screenshot (default) or an OG card ("kind": "og") and takes the same params as the single endpoints — including template. You get a job_id back immediately (202); poll it or listen for the batch.completed webhook.

POST https://api.screenmint.dev/v1/batch
{
  "items": [
    { "url": "https://a.com", "full_page": true },
    { "url": "https://b.com", "format": "pdf" },
    { "kind": "og", "template": "e7c1…", "title": "Hello" }
  ]
}

→ 202  { "job_id": "a3d6…", "status": "processing", "total": 3,
         "poll": "/v1/batch/a3d6…" }

{
  "status": "completed", "total": 3, "completed": 3, "failed": 0,
  "items": [
    { "idx": 0, "kind": "screenshot", "status": "done", "result_url": "https://…" },
    { "idx": 1, "kind": "screenshot", "status": "done", "result_url": "https://…" },
    { "idx": 2, "kind": "og",         "status": "done", "result_url": "https://…" }
  ]
}

Templates

Save a reusable set of defaults in the dashboard (an OG-card design or a screenshot config), then reference it by id with template. Any fields you also pass in the request override the template — so you design once and vary only what changes per render.

POST https://api.screenmint.dev/v1/og
{
  "template": "e7c1…",         // your saved OG template
  "title": "This week's post"  // overrides the template's title
}

Signed URLs

Render by hitting a URL directly — perfect for an <img src> or an og:image meta tag, with no API key header and no server round-trip. Pass your render options as query params plus a token (your key’s signing token) and a sig (an HMAC over the params). On success it 302-redirects to the hosted image, so browsers and CDNs cache it normally.

Build the signature server-side (the signing secret must never ship to the browser): take every param except sig, sort by key, join as encodeURIComponent(k)=encodeURIComponent(v) with &, and HMAC-SHA256 it with your signing secret (hex).

import crypto from 'node:crypto';

const TOKEN  = '2b9f…';           // key's signing token (public)
const SECRET = 'a1b2c3…';         // signing secret (server-side only)

function signedUrl(params) {
  const q = { token: TOKEN, ...params };
  const canonical = Object.keys(q).sort()
    .map(k => encodeURIComponent(k) + '=' + encodeURIComponent(q[k]))
    .join('&');
  const sig = crypto.createHmac('sha256', SECRET).update(canonical).digest('hex');
  return `https://api.screenmint.dev/v1/screenshot?${canonical}&sig=${sig}`;
}

// Drop straight into HTML:
// <img src={signedUrl({ url: 'https://stripe.com', width: 1200, full_page: true })} />

GET/v1/usage

Check your current billing period programmatically — handy for alerting before you hit the quota.

curl https://api.screenmint.dev/v1/usage \
  -H "X-API-Key: sk_live_..."

{
  "plan": "starter",
  "renders_used": 487,
  "renders_limit": 2000,
  "period_start": "2026-07-01T00:00:00.000Z",
  "period_end": "2026-08-01T00:00:00.000Z"
}