Calotype

API reference

Everything the Calotype API does, its limits and its errors. The machine-readable version is at /openapi.json.

  1. Basics
  2. Authentication
  3. Create a key
  4. Take a screenshot
  5. Parameters
  6. The response
  7. What Calotype will not fetch
  8. Errors
  9. Quotas and rate limits
  10. Usage, plans and health
  11. MCP server
  12. 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:

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.

NameDefaultWhat it does
urlrequiredThe 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.
width1280Viewport width in CSS pixels, 100 to 3840.
height800Viewport height in CSS pixels, 100 to 2160.
full_pagefalseCapture the whole scrolling page instead of the viewport. See the height cap below.
formatpngpng, jpeg or webp. jpg is accepted as jpeg.
quality801 to 100, for jpeg and webp only. Sending it with png is an error.
device_scale_factor11 to 3, decimals allowed. Use 2 for sharp images on high-density screens.
delay_ms0Extra wait after the page loads, 0 to 10,000 ms.
wait_untilloadWhen the page counts as loaded: load, domcontentloaded, networkidle or commit.
block_adsfalseBlock requests to a list of common ad and tracking domains.
dark_modefalseAsk the page for its dark colour scheme (prefers-color-scheme: dark).

Size limits

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:

HeaderMeaning
X-Calotype-UsageScreenshots this key has used this month, and its limit, for example 12/100.
X-Calotype-Duration-MsHow long the capture took.
X-Calotype-Target-StatusThe 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-Truncated1 when the page passed the 50 MB download limit and the image shows what had loaded by then.
X-Request-IdOn 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

StatusCodeMeaning
400invalid_parametersA parameter is missing, unknown, out of range, or in a combination that is not allowed. details lists each problem field when there is one.
400invalid_jsonThe POST body is not a JSON object.
400invalid_urlThe 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.
400invalid_schemeThe address is not http or https.
400blocked_targetThe host is private, local or reserved, or the port is not allowed.
400dns_errorThe host name did not resolve, or not in time.
401missing_keyNo key was sent.
401invalid_keyThe key is wrong or revoked, or the Authorization header is not a bearer token.
403plan_unavailableThe key's plan no longer exists. Write to support.
403self_serve_disabledSelf-serve key creation is switched off.
422target_unreachableThe 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.
422blocked_targetThe page, a redirect or the final address pointed to a private address or a non-web scheme.
422page_too_largeThe page passed the 50 MB download limit before anything could be captured.
429quota_exceededThe key has used its screenshots for the month. Adds plan, limit, used and resets_at.
429rate_limitedToo many keys were created recently. Adds retry_after_s, and the Retry-After header.
500internal_errorSomething failed on Calotype's side.
503busyEvery renderer stayed busy for 10 seconds. Retry after the Retry-After header (5 seconds).
504timeoutThe 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

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

StatusCodeMeaning
400invalid_planThe plan is not one that can be bought. Adds plans, the ones that can.
400invalid_jsonThe body is not a JSON object.
404no_billing_accountThe portal was asked for a key that has never paid.
409already_subscribedThe key is already on a paid plan. Use the portal to change it.
502billing_errorStripe could not be reached or refused. Try again shortly.
503billing_unavailableCard checkout is not set up on this server. This is the answer today.