API documentation

Base URL: https://shotmint.creasework.com. Authenticate with the X-API-Key header, Authorization: Bearer KEY, or the access_key query parameter.

Get a free key

GET/POST /v1/screenshot

Returns image/png, image/jpeg or image/webp. Parameters as query string (GET) or JSON body (POST):

Param	Default	Description
`url`		Page to capture (http/https). Or pass `html` instead.
`html`		Raw HTML to render (POST, up to 2MB).
`width` / `height`	1280 / 800	Viewport size in px.
`full_page`	false	Capture the full scrollable page (up to 16,000px tall).
`selector`		CSS selector: capture only this element.
`format`	png	`png`, `jpeg` or `webp`. `quality` 10–100 for jpeg/webp (default 80).
`omit_background`	false	Transparent background where the page doesn't paint one (png/webp).
`block_ads`	false	Block common ad, tracker and consent-manager requests and hide typical cookie banners.
`device_scale_factor`	1	1–3 (2 = retina).
`dark_mode`	false	Emulate `prefers-color-scheme: dark`.
`delay`	0	Extra wait in ms after load (max 10000).
`wait_until`	load	`load`, `domcontentloaded` or `networkidle`.
`hide_selectors`		Comma-separated CSS selectors to hide (cookie banners, chat widgets).
`user_agent`		Custom User-Agent string.
`mobile`	false	Emulate a touch phone (honours the meta viewport). Combine with `width=390&height=844&device_scale_factor=3` and a mobile `user_agent`.

GET/POST /v1/pdf

Returns application/pdf. Accepts url or html, plus wait_until, delay, hide_selectors and:

Param	Default	Description
`format`	A4	A3, A4, A5, Letter, Legal, Tabloid.
`landscape`	false	Landscape orientation.
`margin`	10mm	e.g. `0mm`, `1in`, `20px`.
`print_background`	true	Include CSS backgrounds.
`scale`	1	0.1–2.
`screen_media`	false	Use screen CSS instead of print CSS.

GET /v1/account

Returns {"credits": 1234} for your key. Every render response also carries an X-Credits-Remaining header.

Examples

curl "https://shotmint.creasework.com/v1/screenshot?url=https://example.com&full_page=true" \
  -H "X-API-Key: YOUR_KEY" -o shot.png

curl -X POST https://shotmint.creasework.com/v1/pdf -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"html":"<h1>Invoice #42</h1>","format":"A4"}' -o invoice.pdf

Node.js

const res = await fetch("https://shotmint.creasework.com/v1/screenshot?url=" + encodeURIComponent("https://example.com"), {
  headers: { "X-API-Key": process.env.SHOTMINT_KEY },
});
await fs.promises.writeFile("shot.png", Buffer.from(await res.arrayBuffer()));

Python

import requests
r = requests.post("https://shotmint.creasework.com/v1/pdf", headers={"X-API-Key": KEY},
                  json={"url": "https://example.com", "format": "Letter"})
open("page.pdf", "wb").write(r.content)

HTML embed

<img src="https://shotmint.creasework.com/v1/screenshot?url=https://example.com&access_key=YOUR_KEY">

OG images: GET /v1/og

A ready-made 1200×630 social card. Parameters: title, subtitle, site, theme (indigo, dark, light, sunset, mint). It costs 1 credit per new card. The same request repeated with the same key within 24h is served from cache for free (X-Cache: HIT). Try it.

curl "https://shotmint.creasework.com/v1/og?title=Hello%20world&theme=dark" -H "X-API-Key: YOUR_KEY" -o card.png

Signed public URLs (use directly as og:image)

Put a card URL straight into your <meta property="og:image"> without exposing your key. GET /v1/og/url takes the same parameters, is free, and returns a signed URL like https://shotmint.creasework.com/og/KEY_ID.png?title=…&sig=…. Anyone can fetch it, but changing any parameter invalidates the signature, so nobody can render other text on your credits. Billing is the same as /v1/og: 1 credit per new card, repeats are cached.

curl "https://shotmint.creasework.com/v1/og/url?title=Hello%20world&theme=dark" -H "X-API-Key: YOUR_KEY"

To sign without a request (e.g. in your page template): sig is the first 32 hex characters of HMAC-SHA256 with your API key as the secret, over title + " " + subtitle + " " + site + " " + theme (missing fields are empty strings, theme defaults to indigo). Your KEY_ID is returned by GET /v1/account.

const sig = crypto.createHmac('sha256', API_KEY)
  .update([title, subtitle, site, theme].join('\n')).digest('hex').slice(0, 32);
const ogImage = `https://shotmint.creasework.com/og/${KEY_ID}.png?title=${encodeURIComponent(title)}&subtitle=${encodeURIComponent(subtitle)}&site=${encodeURIComponent(site)}&theme=${theme}&sig=${sig}`;

Errors

400	Bad parameters or unreachable URL (no credit used)
401	Missing or invalid key
402	Out of credits. The JSON includes `topup_url`, which tops up the same key so your code keeps working. Pricing
429 / 503	Rate limited or busy, retry with backoff

Limits: 25s render timeout; internal/private network addresses are blocked.