API reference
Everything the Calotype API does, its limits and its errors. The machine-readable version is at /openapi.json.
- Basics
- Authentication
- Create a key
- Take a screenshot
- Parameters
- The response
- What Calotype will not fetch
- Errors
- Quotas and rate limits
- Usage, plans and health
- MCP server
- Billing endpoints
Basics
The API lives at https://calotype.dev. A successful screenshot returns the image itself. Everything else returns JSON. Errors always have the same shape:
{"error": {"code": "quota_exceeded", "message": "...", ...}}
The code is stable and meant for programs; the message is meant for people. Some errors add fields, listed under Errors. Every response carries an X-Request-Id header; quote it when you write to support.
Authentication
Every call except key creation, /v1/plans, /health and Stripe's webhook needs an API key. Send it in one of two ways:
- a header:
Authorization: Bearer cal_...(preferred); - a query parameter:
?access_key=cal_....
Prefer the header. A key in the query string is part of the request address, which travels through more systems than a header does. Calotype drops the hosting platform's request records before they are stored (see Privacy), but the header is still the safer habit. Calotype's own logs never contain the key. An Authorization header that is not a bearer token is refused, even if access_key is also set.
The key is the account. Calotype stores only its SHA-256 hash, so a lost key cannot be shown again.
Create a key
POST /v1/keys makes a free-plan key. It takes no body and no authentication, and asks for nothing about you. The button on the home page calls it.
curl -X POST https://calotype.dev/v1/keys
It answers 201:
{
"key": "cal_...",
"plan": "free",
"monthly_quota": 100,
"message": "This is the only time the key is shown. Calotype stores only its hash and cannot recover it."
}
Key creation is rate limited; see Quotas and rate limits.
Take a screenshot
GET /v1/screenshot with the parameters in the query string:
curl -H "Authorization: Bearer $CALOTYPE_KEY" \
"https://calotype.dev/v1/screenshot?url=https://example.com&width=1280&height=800" \
-o example.png
Or POST /v1/screenshot with a JSON object as the body:
curl -X POST "https://calotype.dev/v1/screenshot" \
-H "Authorization: Bearer $CALOTYPE_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com", "full_page": true, "format": "webp"}' \
-o example.webp
POST keeps the target address out of the request line. With POST, send the key in the header (or as ?access_key=); an access_key field in the JSON body is ignored.
Parameters
The same names work in the query string and in the JSON body. A parameter Calotype does not know is refused with invalid_parameters, so typos do not pass silently. In the query string, write booleans as true or false.
| Name | Default | What it does |
|---|---|---|
url | required | The page to capture. http or https only, on a public address, at most 2,048 characters. Ports 80, 443 and 1024 and up. No user:password@ in the address. |
width | 1280 | Viewport width in CSS pixels, 100 to 3840. |
height | 800 | Viewport height in CSS pixels, 100 to 2160. |
full_page | false | Capture the whole scrolling page instead of the viewport. See the height cap below. |
format | png | png, jpeg or webp. jpg is accepted as jpeg. |
quality | 80 | 1 to 100, for jpeg and webp only. Sending it with png is an error. |
device_scale_factor | 1 | 1 to 3, decimals allowed. Use 2 for sharp images on high-density screens. |
delay_ms | 0 | Extra wait after the page loads, 0 to 10,000 ms. |
wait_until | load | When the page counts as loaded: load, domcontentloaded, networkidle or commit. |
block_ads | false | Block requests to a list of common ad and tracking domains. |
dark_mode | false | Ask the page for its dark colour scheme (prefers-color-scheme: dark). |
Size limits
width×height×device_scale_factor² may be at most 80,000,000 pixels.- A full-page capture is at most 20,000 CSS pixels tall, and less where the 80,000,000-pixel limit bites first (wide viewports, high scale factors). WebP images cannot be taller than 16,383 pixels, so for
webpthe cap is 16,383 divided by the scale factor. A page taller than the cap is cut off at the cap; that is not an error.
The response
A successful call answers 200 with the image as the body and its type in Content-Type (image/png, image/jpeg or image/webp). Headers:
| Header | Meaning |
|---|---|
X-Calotype-Usage | Screenshots this key has used this month, and its limit, for example 12/100. |
X-Calotype-Duration-Ms | How long the capture took. |
X-Calotype-Target-Status | The HTTP status the page answered with. A page that answers 404 or 500 is still captured, and still counts; check this header if that matters to you. |
X-Calotype-Truncated | 1 when the page passed the 50 MB download limit and the image shows what had loaded by then. |
X-Request-Id | On every response. Quote it to support. |
Images are sent with Cache-Control: no-store. Calotype keeps no copy: the image exists only in the response.
What Calotype will not fetch
Calotype only captures public web pages. It refuses private, loopback, link-local, carrier-grade NAT, multicast, reserved and cloud-metadata addresses, and host names such as localhost or names ending in .internal or .local. A host name must resolve to public addresses only; if any address it resolves to is private, the request is refused.
The check covers more than the first address. Every request the page makes goes through the same rule: redirects, images, scripts, frames, fetch calls and WebSockets. The browser's only route to the network is a proxy that resolves each host itself and connects to the exact address it checked, so a DNS answer cannot change in between. Non-web schemes such as file:, ftp: and chrome: are refused, as the address to capture and inside the page.
Each capture runs in a fresh browser context that is thrown away afterwards, with service workers and downloads off; nothing from one capture is visible to the next. Pages with an invalid HTTPS certificate fail to load. A page may download at most 50 MB in total. Each capture has 30 seconds from start to finish.
Please capture only pages you are allowed to view. The acceptable use policy has the rules.
Errors
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_parameters | A parameter is missing, unknown, out of range, or in a combination that is not allowed. details lists each problem field when there is one. |
| 400 | invalid_json | The POST body is not a JSON object. |
| 400 | invalid_url | The address cannot be parsed, is too long, has no host, has credentials in it, contains spaces, control characters or backslashes, or has a port outside 1 to 65535. |
| 400 | invalid_scheme | The address is not http or https. |
| 400 | blocked_target | The host is private, local or reserved, or the port is not allowed. |
| 400 | dns_error | The host name did not resolve, or not in time. |
| 401 | missing_key | No key was sent. |
| 401 | invalid_key | The key is wrong or revoked, or the Authorization header is not a bearer token. |
| 403 | plan_unavailable | The key's plan no longer exists. Write to support. |
| 403 | self_serve_disabled | Self-serve key creation is switched off. |
| 422 | target_unreachable | The page could not be loaded: connection refused, certificate error and so on. The message may name the browser's error, such as net::ERR_NAME_NOT_RESOLVED. |
| 422 | blocked_target | The page, a redirect or the final address pointed to a private address or a non-web scheme. |
| 422 | page_too_large | The page passed the 50 MB download limit before anything could be captured. |
| 429 | quota_exceeded | The key has used its screenshots for the month. Adds plan, limit, used and resets_at. |
| 429 | rate_limited | Too many keys were created recently. Adds retry_after_s, and the Retry-After header. |
| 500 | internal_error | Something failed on Calotype's side. |
| 503 | busy | Every renderer stayed busy for 10 seconds. Retry after the Retry-After header (5 seconds). |
| 504 | timeout | The page did not load, or the capture did not finish, within 30 seconds. |
A screenshot that fails, for any of these reasons, is not counted against your quota. The billing endpoints have errors of their own, listed under Billing endpoints.
Quotas and rate limits
- Monthly quota. Each key may take as many successful screenshots a month as its plan allows: Free 100, Starter 5,000, Pro 25,000. Months are calendar months in UTC; counts reset at 00:00 UTC on the first day of each month. Unused screenshots do not carry over.
- What counts. Only a capture that returns an image. Rejected requests (bad parameters, bad key, refused address, over quota) and failed captures (unreachable page, timeout, busy, internal error) are not counted.
- Over the limit. Calls answer
429 quota_exceededuntil the reset. There are no overage charges. - Key creation. At most 3 keys an hour from one IP address, and at most 200 an hour across the whole service. Over either limit,
POST /v1/keysanswers429 rate_limitedwithRetry-After. - Concurrency. Each server renders a few pages at a time. A request that waits more than 10 seconds for a free renderer answers
503 busy. - Time. 30 seconds per capture, from start to encoded image.
Usage, plans and health
GET /v1/usage
Your key's plan and this month's count. It needs the key and does not count as a screenshot.
{"plan": "free", "month": "2026-11", "used": 12, "limit": 100, "resets_at": "2026-12-01T00:00:00Z"}
GET /v1/plans
The plans, their monthly quotas and prices in US dollars. No key needed. provisional: true means the prices may still change before paid plans open.
{"provisional": true, "plans": [{"name": "free", "title": "Free", "monthly_quota": 100, "price_usd": 0.0}, ...]}
GET /health
Answers 200 with {"status": "ok", "version": "...", "browser": true}, or 503 with "status": "degraded" when the renderer's browser is down.
MCP server
Calotype ships an MCP server with one tool, screenshot, so coding assistants and agents can look at a page. It runs on your machine over stdio, needs the calotype Python package installed there, and calls the API with your key. Add it to your client's MCP configuration:
{
"mcpServers": {
"calotype": {
"command": "python",
"args": ["-m", "calotype.mcp_server"],
"env": {
"CALOTYPE_API_KEY": "cal_...",
"CALOTYPE_API_URL": "https://calotype.dev"
}
}
}
}
Set CALOTYPE_API_URL: without it the tool calls http://127.0.0.1:8080. The tool takes url, width, height, full_page, format, dark_mode, block_ads and delay_ms. Its defaults differ from the API's in two places: format is jpeg and block_ads is true, which keeps images small for a model. Each tool call is one API call and counts like one.
Billing endpoints Coming soon
Paid plans are not on sale yet. Until checkout opens, these endpoints answer 503 billing_unavailable. They are documented so you know what to expect; the upgrade form on the pricing page will use them.
POST /v1/billing/checkout
With a free key and a body of {"plan": "starter"} or {"plan": "pro"}, answers {"url": "https://checkout.stripe.com/...", "plan": "starter"}. Send the buyer to that address. When Stripe confirms the payment, the same key moves to the new plan; nothing in your code changes. Stripe is given the key's internal number, never the key.
GET /v1/billing/portal
With a key that has paid before, answers {"url": "https://billing.stripe.com/..."}: a Stripe customer-portal page to change the card or plan, see invoices, or cancel.
POST /v1/billing/webhook
For Stripe only. It checks Stripe's signature and takes no API key.
Billing errors
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_plan | The plan is not one that can be bought. Adds plans, the ones that can. |
| 400 | invalid_json | The body is not a JSON object. |
| 404 | no_billing_account | The portal was asked for a key that has never paid. |
| 409 | already_subscribed | The key is already on a paid plan. Use the portal to change it. |
| 502 | billing_error | Stripe could not be reached or refused. Try again shortly. |
| 503 | billing_unavailable | Card checkout is not set up on this server. This is the answer today. |