API reference

Contents: Basics | Routes and prices | Parameters | How pages are rendered | Limits | Rate limits | Responses | Errors | Payment | L402 | Cashu | Failures after payment | Rules

Basics

• Base URL: https://api.jittator.com
• No account, no API key, no prepaid balance, no subscription. Every paid request carries its own payment.
• URL routes (/v1/screenshot, /v1/screenshot/full, /v1/pdf) accept GET with query parameters or POST with a JSON object body (Content-Type: application/json). Not both at once.
• Render routes (/v1/render/...) accept POST with a JSON object body only.
• Unknown parameters are rejected with 400 unknown_parameter, so a typo never silently falls back to a default.
• Every request is checked for free before payment is asked for (parameters, URL, DNS, public address, robots.txt, queue). An invalid request gets its error straight away and no invoice. POST bodies are checked too.
• In a GET query, percent-encode the target URL if it has its own query string, for example curl -G --data-urlencode "url=https://example.com/a?b=c" https://api.jittator.com/v1/screenshot.
• Machine-readable prices and accepted mints: GET https://api.jittator.com/.well-known/l402-services (free JSON).

Routes and prices

Prices are per call, fixed in sats. Cashu tokens from coinos or macadamia also cover that mint's swap fee (Cashu). Lightning routing fees are paid by the payer's wallet.

/healthz returns {"status": "ok", "queue": {"running": 0, "waiting": 0}}: the number of renders running and waiting right now.

Parameters

Target (URL routes)

Content (render routes)

Send exactly one of these.

Screenshot options

For /v1/screenshot, /v1/screenshot/full, /v1/render/screenshot and /v1/render/screenshot/full.

PDF options

For /v1/pdf and /v1/render/pdf.

In a GET query, booleans are true/false (also 1/0, yes/no). In a JSON body, use JSON booleans and numbers. Choice values (format, paper, media) are not case-sensitive.

How pages are rendered

• All screenshots (URL, HTML and Markdown) are taken with headless Chromium driven by Playwright. All PDFs are made with Chromium's print path (Gotenberg).
• A page counts as loaded at its load event; wait_ms adds time after that.
• A browser error page is never returned as a result. If the target cannot be reached, answers with an HTTP error, or redirects to a non-public address, you get a JSON error instead (Errors).
• Full-page screenshots grow the viewport to the page's height (at most 8000 pixels) and capture that. Elements sized in vh units grow with it, so a 100vh banner can fill the image.
• WebGL is turned off for screenshots, so WebGL canvases (some maps, 3D views) come out blank.
• Every request the browser makes, including images, styles, fonts, frames, scripts and redirects, is checked against the same public-address rules. Private, loopback and internal addresses are refused, and screenshots also load nothing from ports other than 80 and 443, so such resources are simply missing from the result.
• HTML you send may load public http and https resources. file: URLs are blocked. In screenshots, data: and blob: URLs also work, and a script that navigates the page itself away fails the call with 422 content_navigation_blocked.
• Markdown screenshots and Markdown PDFs use different converters. They look the same, except that ~~strikethrough~~ and bare URLs (not written as links) are not converted in screenshots.

Limits

Rate limits

Applied by the gateway, per client IP address unless noted. These are the current values and may change.

Over a limit, the answer is 429 with a Retry-After header in seconds, usually with the body {"error":{"code":"rate_limited","message":"...","retry_after_s":10}}. Wait that long before trying again.

Responses

A successful call returns 200 with the file as the body:

• Content-Type: image/png, image/jpeg, image/webp or application/pdf
• Content-Disposition: inline; filename="screenshot.png" (with the format's extension) or filename="document.pdf"
• Cache-Control: no-store
• X-Jittator-Render-Ms: time spent on the request, in milliseconds
• X-Jittator-Truncated: true: only on full-page screenshots cut at 8000 pixels

Results are sent only to the caller and are not stored. Save the body; it cannot be fetched again.

Errors

Errors from the renderer are JSON:

{"error": {"code": "robots_disallowed", "message": "robots.txt on 'example.com' disallows JittatorBot for this path", "status": 403}}

busy errors also carry "retry_after_s" and a Retry-After header. The same codes are returned by the free check before payment and, for anything that only shows up while rendering, after payment.

Errors from the payment gateway

These come from the gateway in front of the renderer. Their JSON bodies have code and message but no status field, and some (such as 401) are not JSON, so always read the status code and headers.

Payment

Payment is handled by a gateway in front of the renderer. It first runs the free check: an invalid request gets its error and no invoice, and a proof sent with an invalid request is not used. A valid request with no payment gets 402 Payment Required offering both rails at once. Pick one, pay, and send the same request again with the proof of payment. Every call needs its own payment.

HTTP/2 402
www-authenticate: L402 macaroon="AGIAJEem...", invoice="lnbc200n1..."
x-cashu: creqA...
content-type: application/json

{"error":{"code":"payment_required","message":"Pay the Lightning invoice in WWW-Authenticate (L402) and retry with Authorization: L402 <macaroon>:<preimage>, or retry with a Cashu token in X-Cashu (NUT-24)","price_sat":20}}

L402

1. Send the request. Read the WWW-Authenticate header of the 402: L402 macaroon="<base64 macaroon>", invoice="<BOLT11 invoice>".
2. Check the invoice amount matches the route's price (20 or 30 sats), then pay it with any Lightning wallet. The wallet returns the payment preimage (64 hex characters).
3. Send the same request again with Authorization: L402 <macaroon>:<preimage>.

• The invoice and the macaroon expire 1 hour (3600 seconds) after the 402.
• The macaroon is bound to the route and method it was issued for: a credential bought for GET /v1/screenshot does not open /v1/pdf or POST /v1/screenshot.
• A credential pays for one call. Using it again gets 401, except for the one retry after a failed call described under Failures after payment.

$ curl -si "https://api.jittator.com/v1/screenshot?url=https://example.com" | grep -i www-authenticate
www-authenticate: L402 macaroon="AGIAJEem...", invoice="lnbc200n1..."

# pay lnbc200n1... with your wallet; it returns the preimage

$ curl -o shot.png \
    -H "Authorization: L402 AGIAJEem...:6f1c...preimage-hex" \
    "https://api.jittator.com/v1/screenshot?url=https://example.com"

With Lightning Labs' lnget, which pays from your own node and retries automatically:

lnget --max-cost 30 -o shot.png "https://api.jittator.com/v1/screenshot/full?url=https://example.com"
lnget --max-cost 30 -X POST -H "Content-Type: application/json" \
  -d '{"html": "<h1>Invoice 42</h1>", "paper": "a4"}' \
  -o invoice.pdf https://api.jittator.com/v1/render/pdf

Cashu (NUT-24)

1. Send the request. The 402 carries an X-Cashu header with a NUT-18 payment request (creqA...). Decoded, it gives the amount a (the route's list price), the unit u (sat) and the accepted mint URLs m. That list is the authoritative one.
2. Make a cashuB token in sats from one of the listed mints, worth the amount due (see fees below).
3. Send the same request again with the token in the X-Cashu request header.

$ curl -si "https://api.jittator.com/v1/pdf?url=https://example.com" | grep -i x-cashu
x-cashu: creqA...

$ curl -o page.pdf -H "X-Cashu: cashuB..." "https://api.jittator.com/v1/pdf?url=https://example.com"

The gateway swaps the token at its mint before rendering, so an accepted token is spent and cannot be used again (401). Overpayment is kept; no change is returned.

Accepted mints and what a token must be worth:

The swap fee is set by the mint (NUT-02): the sum of the token's per-proof input fees in ppk, divided by 1000 and rounded up, in sats. It depends on the number of proofs: 21 and 31 sat tokens made of the fewest proofs carry a 1 sat fee, while a 20 sat call paid with many small proofs can need 22 sats. A token is accepted when its value minus the fee covers the price. The payment request's a is the list price, because NUT-18 has no field for a fee; wallets that send with "include fees" (for example cashu send -f in Nutshell, or includeFees in cashu-ts) add it themselves.

A token that falls short is refused with 400 and an X-Cashu-Error header that says by how much, for example:

X-Cashu-Error: Cashu token amount insufficient after the mint's 1000 msat input fee: 19000 msat (required: 20000 msat)

The token is not spent; send a larger one. The m list in the 402 and /.well-known/l402-services (which also lists each mint's input_fee_ppk) are always current.

Failures after payment

There are no balances, so nothing is credited to an account. Instead, when a call whose payment was accepted fails in the renderer with 422 or any 5xx (for example render_timeout, target_unreachable, target_http_error, engine_error, busy, content_navigation_blocked), the gateway gives back what you paid, once per payment:

L402: one retry with the same proof

The failed response carries X-L402-Retry:

Cashu: a refund token

The failed response carries X-Cashu-Refund: cashuB..., a token from the same mint worth the route's price (not the swap fee you added). Treat it as money: redeem it into your own wallet straight away (for example cashu receive <token>), because until you do, anyone who sees it can take it. Do not log it. You can also pay the retry with it directly in X-Cashu; at coinos or macadamia, add the swap fee again. If no refund can be made, the response has X-Cashu-Refund-Error instead:

Other cases

• Errors from the free check (any 4xx or 503 busy before a 402) cost nothing and use up no proof. Fix the request; do not pay first.
• A 4xx other than 422 after payment, such as 403 target_not_public when a page redirects to a private address while being captured, gets no retry or refund.
• 401 on a retry means the proof was not accepted; do not pay again without finding out why.
• 503 payment_backend_error means the payment step itself failed; wait 5 seconds and try again. Check a Cashu token in your wallet before reusing it.

Rules

• Public http and https pages only. Private, internal and reserved addresses are refused, including via DNS names or redirects that lead to them.
• No logins, cookies or credentials, and no way to pass them.
• robots.txt is checked for the requested URL before the page is loaded, under the token JittatorBot. Pages are fetched with the user agent JittatorBot/0.1 (+https://jittator.com/bot). See the bot page.
• No CAPTCHA solving or anti-bot bypass. A page that blocks the bot comes back as 502 target_http_error if the site answers with an error status, or as whatever the site shows the bot.
• Results go back only to the caller and are not stored.
• Payment records (Lightning payment hash or a fingerprint of the Cashu proofs, amount, rail, mint, route and time) are kept for tax purposes; see privacy.

See also: terms, acceptable use, contact and abuse reports.