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

Limits apply per account, not per API key: every key on the account (and teammates working in it) shares them, so creating more keys doesn’t raise them. There’s a per-minute request rate (fixed one-minute windows), a cap on renders in flight at once, and a monthly render quota. On the Free plan the quota resets on the 1st of each month (UTC); on paid plans it resets on your billing-period anniversary — subscribe on the 18th and it resets on the 18th.

Identical requests are cached — screenshots and videos for 1 hour, OG cards for 24 hours. Cache hits return in milliseconds with "cached": true and the same URL, and do not consume monthly renders (they still count toward the per-minute rate, except repeat views of a signed URL). After that, the same request renders afresh and gets a new URL, so you always get the page as it is now.

Errors

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

{
  "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…-3f9a1c2b.mp4",
    "width": 1280, "height": 720, "seconds": 6, "format": "mp4",
    "cached": false, "render_ms": 7100, "credits": 3 }

Smooth video (async)

On the Starter and Pro plans, add "async": true to a /v1/video request and the video is captured frame by frame in the background. Every frame is fully drawn before the next one, so the result stays smooth even on heavy pages — big blur, glass or animated effects — that stutter when recorded in real time, and CSS animations play at their real speed. You get a job_id back immediately (202); poll it, or listen for the render.completed webhook.

POST https://api.screenmint.dev/v1/video
{ "url": "https://stripe.com", "seconds": 15, "scroll": true,
  "block_cookies": true, "async": true }

→ 202  { "job_id": "7c1e…", "status": "queued", "credits": 8,
         "poll": "/v1/video/jobs/7c1e…" }

{
  "job_id": "7c1e…", "status": "completed",
  "url": "https://cdn.example/videos/9b2f….mp4",
  "width": 1280, "height": 720, "seconds": 15, "format": "mp4",
  "credits": 8, "render_ms": 96000
}

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://…" }
  ]
}

Webhooks

Add an HTTPS endpoint under Webhooks in the dashboard and Screenmint POSTs a JSON event to it as renders finish — so you don’t have to poll async jobs. Each endpoint gets its own signing secret (whsec_…), shown once when you add it.

Every delivery has the same envelope — { event, data, created_at } — with the event name repeated in the X-Screenmint-Event header:

POST /webhooks/screenmint HTTP/1.1
Content-Type: application/json
User-Agent: Screenmint-Webhooks/1
X-Screenmint-Event: render.completed
X-Screenmint-Signature: sha256=3b5f0c9e41d7…

{
  "event": "render.completed",
  "data": {
    "endpoint": "video",
    "job_id": "7c1e…",
    "url": "https://cdn.example/videos/9b2f….mp4",
    "width": 1280, "height": 720, "seconds": 15, "format": "mp4",
    "credits": 8
  },
  "created_at": "2026-09-29T14:03:11.482Z"
}

X-Screenmint-Signature is sha256=<hex>: the HMAC-SHA256 of the raw request body, keyed with the endpoint’s full signing secret — including the whsec_ prefix. Compute it over the exact bytes you received, before parsing the JSON, and compare in constant time:

import crypto from 'node:crypto';

// rawBody: the request body exactly as received (Buffer or string). Verify it
// before parsing — JSON that has been parsed and re-serialized won't match.
// secret: the endpoint's full signing secret, "whsec_" prefix included.
function verifyScreenmintSignature(rawBody, signatureHeader, secret) {
  const expected =
    'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  const given = Buffer.from(String(signatureHeader || ''));
  const want = Buffer.from(expected);
  return given.length === want.length && crypto.timingSafeEqual(given, want);
}

// Express: take this route's body raw, verify, then parse.
app.post('/webhooks/screenmint', express.raw({ type: 'application/json' }), (req, res) => {
  const ok = verifyScreenmintSignature(
    req.body,
    req.get('X-Screenmint-Signature'),
    process.env.SCREENMINT_WEBHOOK_SECRET, // whsec_...
  );
  if (!ok) return res.sendStatus(401);
  const { event, data } = JSON.parse(req.body);
  // event: 'render.completed' | 'render.failed' | 'batch.completed'
  res.sendStatus(200);
});

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-18T09:12:44.000Z",
  "period_end": "2026-08-18T09:12:44.000Z"
}