Shotkiln API documentation

The Shotkiln API has three render endpoints: /v1/screenshot, /v1/pdf and /v1/og. Each accepts GET with query parameters or POST with a JSON body, and returns the file with the matching Content-Type. Base URL: https://shotkiln.com. The machine-readable spec is at /openapi.json.

Quickstart

# 1. Create a free key (shown once)
curl -X POST https://shotkiln.com/v1/keys

# 2. Screenshot a page
curl "https://shotkiln.com/v1/screenshot?url=https://example.com&width=1440&height=900" \
  -H "x-api-key: $SHOTKILN_KEY" -o shot.png

const res = await fetch("https://shotkiln.com/v1/screenshot", {
  method: "POST",
  headers: { "x-api-key": process.env.SHOTKILN_KEY, "content-type": "application/json" },
  body: JSON.stringify({ url: "https://example.com", width: 1440, height: 900, format: "png" }),
});
if (!res.ok) throw new Error((await res.json()).error.message);
const png = Buffer.from(await res.arrayBuffer());
console.log("quota left:", res.headers.get("x-quota-remaining"));

import os, requests

r = requests.post("https://shotkiln.com/v1/screenshot",
    headers={"x-api-key": os.environ["SHOTKILN_KEY"]},
    json={"url": "https://example.com", "full_page": True, "format": "webp"})
r.raise_for_status()
open("shot.webp", "wb").write(r.content)
print(r.headers["x-cache"], r.headers.get("x-quota-remaining"))

Authentication

Send the key as x-api-key: shk_live_… or Authorization: Bearer shk_live_…. Test-mode keys start with shk_test_. Without a key, requests run as an anonymous demo: 3 per minute, 10 per day per network, watermarked.

You may pass api_key= in the query string for quick tests, but a key in a public page or <img src> can be copied and used against your quota. In production, call the API from your server or build step and serve the file yourself.

Screenshot

Returns image/png, image/jpeg or image/webp.

PDF

Returns application/pdf. Raw HTML is cached per key, never shared.

curl -X POST https://shotkiln.com/v1/pdf -H "x-api-key: $SHOTKILN_KEY" -H "content-type: application/json" \
  -d '{"html":"<h1>Invoice 42</h1>","format":"A4","margin":"15mm"}' -o invoice.pdf

OG image

Returns a 1200 × 630 image/png. Without a key the card carries a small label; with a paid key it does not. To link the endpoint from an og:image tag, use a signed URL so your key stays private, or generate cards at build time and host the PNG.

Signed OG URLs

A signed URL lets you put /v1/og straight into an og:image tag without exposing your API key. The URL carries your key's public id (kid) and an HMAC-SHA256 signature (sig) of its parameters, made with the key's signing secret. Changing any parameter breaks the signature, so nobody can reuse the URL to draw other cards on your quota. Renders count against the key's plan; free keys produce watermarked cards.

1. Get the signing secret once: POST /v1/keys/signing-secret with your key returns kid and signing_secret. Keep the secret on your server.
2. Build the query string with the card parameters plus kid (and optionally exp, a Unix time in seconds after which the URL stops working).
3. Sort the parameters by name, then value. Percent-encode each name and value with encodeURIComponent rules, join them as name=value with &, and prefix /v1/og?.
4. Append sig: the lowercase hex HMAC-SHA256 of that string.

import { createHmac } from "node:crypto";
const enc = encodeURIComponent;
function signedOg(params, kid, secret) {
  const pairs = Object.entries({ ...params, kid }).map(([k, v]) => [k, String(v)]);
  pairs.sort(([a, x], [b, y]) => (a < b ? -1 : a > b ? 1 : x < y ? -1 : x > y ? 1 : 0));
  const qs = pairs.map(([k, v]) => enc(k) + "=" + enc(v)).join("&");
  const sig = createHmac("sha256", secret).update("/v1/og?" + qs).digest("hex");
  return "https://shotkiln.com/v1/og?" + qs + "&sig=" + sig;
}

import hmac, hashlib
from urllib.parse import quote

def signed_og(params, kid, secret):
    enc = lambda s: quote(str(s), safe="-_.!~*'()")
    pairs = sorted((k, str(v)) for k, v in {**params, "kid": kid}.items())
    qs = "&".join(enc(k) + "=" + enc(v) for k, v in pairs)
    sig = hmac.new(secret.encode(), ("/v1/og?" + qs).encode(), hashlib.sha256).hexdigest()
    return "https://shotkiln.com/v1/og?" + qs + "&sig=" + sig

To skip the code, POST /v1/og/sign with your key and the card parameters as JSON returns the signed url. POST /v1/keys/signing-secret/rotate issues a new secret and invalidates every URL signed with the old one; rotating the API key does the same. A wrong signature returns 403 invalid_signature, an expired one 403 signature_expired. Cache hits use no quota but count toward the per-minute limit.

Limits & headers

Every render response carries these headers, so a client can back off without calling a separate usage endpoint. GET /v1/usage returns the same numbers as JSON, plus resets_at (start of next month, UTC) and billing (whether the key has a Stripe billing portal). The usage dashboard shows them for any key.

Pages may load at most 25 MB of resources and 300 requests. The render budget is 15 s anonymous, 20 s free and 30 s on paid plans.

Caching

Speed reference: median 2.5 s for uncached 1280 × 800 screenshots of 10 public sites (18 October 2026); cache hits 0.2–0.6 s.

Identical requests (same parameters, same watermark state) are served from cache for cache_ttl seconds and do not use quota. Set cache_ttl=0 for a fresh render every time. Public URLs and OG cards share a global cache; HTML you POST to /v1/pdf is cached only for your key.

Errors

Errors are JSON: {"error":{"code":"url_blocked","message":"…"}}. Failed renders are not charged.

MCP

Setup for specific clients is on the MCP screenshot server page. Remote MCP server over Streamable HTTP at https://shotkiln.com/mcp, with tools take_screenshot, render_pdf and generate_og_image. Images come back as MCP image content; PDFs as embedded resources.

{
  "mcpServers": {
    "shotkiln": {
      "url": "https://shotkiln.com/mcp",
      "headers": { "x-api-key": "YOUR_KEY" }
    }
  }
}

The machine-readable spec is at /openapi.json (OpenAPI 3.1), and a short summary for LLMs at /llms.txt.