API reference

Authentication

Every /v1/* endpoint requires an API key, accepted two ways:

# header (recommended for server-side code)
curl "https://backshot.dev/v1/screenshot?url=https://example.com" \
  -H "Authorization: Bearer $BACKSHOT_KEY"

# query param (what makes <img src> embeds possible)
<img src="https://backshot.dev/v1/screenshot?url=https://example.com&key=YOUR_KEY">

Query-param keys are visible to anyone who can read the URL: treat a key you embed publicly as spendable by the public, and use a low-credit key for embeds. Keys are created with the server-side CLI (node bin/backshot.js keys:create); there is no self-serve signup yet.

The landing-page playground uses a shared demo key: 50 credits, refilling to 50 every hour, 10 requests/minute. It is deliberately too small to build on; get a real key for real use.

Screenshot

Renders a URL and returns the image bytes with the matching Content-Type. POST accepts the same parameters as a JSON body (body values win over query values).

Booleans accept 1/true/yes/on (anything else is false). Out-of-range numbers are clamped, not rejected.

PDF

Renders a URL or raw HTML to PDF. Send exactly one of url / html (both is a 400). Body limit is 2 MB.

curl -X POST "https://backshot.dev/v1/pdf" \
  -H "Authorization: Bearer $BACKSHOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"html": "<h1>Invoice #42</h1><p>Total: $90</p>", "format": "A4", "margin": "1cm"}' \
  -o invoice.pdf

Account

Returns the calling key's plan, live credit balance, rate limit, lifetime render count, and its 20 most recent requests:

{
  "plan": "free",
  "label": "my-project",
  "credits": 1961,
  "rate_limit_per_min": 60,
  "total_renders": 39,
  "created_at": 1787810000,
  "recent_usage": [ { "endpoint": "screenshot", "cached": false, "ms": 1412, … } ]
}

Stored files

Every render is stored under a content hash of its full parameter set; response=json returns this path. Files are served without auth: the hash is only derivable from the exact parameters, and only public http/https content is ever stored. Files expire with the cache (24h) and then 404.

Caching & billing

One credit buys one fresh render. The cache key is a SHA-256 of the normalized parameter set, TTL 24 hours. A cache hit returns in about a millisecond, costs zero credits, and is marked in the response:

Failed renders (navigation errors, blocked URLs, timeouts) are never billed. Any parameter change, even width by one pixel, is a different cache entry and a fresh render. There is no cache-bypass parameter yet; to force a fresh render within the TTL, vary a parameter.

Rate limits

Each key has a fixed-window per-minute limit (set at key creation; 10/min on the demo key). Exceeding it returns 429 with a Retry-After header in seconds. The render queue itself is also bounded: when the box is saturated far beyond its concurrency, requests return 503 immediately rather than piling up.

URL security

backshot refuses to be a proxy into private networks. For every URL (the one you submit, every redirect hop it takes, and every subresource the page loads):

Blocked URLs return 400 url_blocked with a reason, and are never billed.

Errors

Errors are JSON: {"error": {"code", "message"}}.

Health

No auth. Live process state; the landing page's status pill reads from it:

{ "status": "ok", "browser": "up", "queue_depth": 0, "active_renders": 0, "uptime_s": 4210, "version": "0.1.0" }

What's deliberately not here yet: self-serve signup and checkout, webhooks, storage/S3 export, signed URLs, multi-region rendering. The docs describe the build that exists, not the one that's planned.