The engine exposes an HTTP API on port 3000 by default. Except for liveness and readiness, every endpoint requires either Authorization: Bearer <token> or X-Prerender-Token: <token>. Keep the token server-side.
GET /health returns process liveness and build identity:
{"ok":true,"service":"@prerenderbuddy/engine","version":"0.1.3"}GET /ready returns 200 {"ready":true} when Chromium is connected, or 503 {"ready":false}. These endpoints intentionally require no token so container orchestrators can call them.
All non-probe API requests share a per-process budget configured by REQUESTS_PER_MINUTE (default 600 per minute). Authentication failures also consume it. A rejected request returns 429 {"error":"Request rate limit exceeded"} and a Retry-After header. RateLimit and RateLimit-Policy describe the shared budget. Liveness/readiness are exempt. This control is in the maintenance branch and is not included in published v0.1.3.
Use either GET /render?url=<encoded-url> or:
POST /render
Authorization: Bearer <token>
Content-Type: application/json
{"url":"https://example.com/path","ttlSeconds":1800}ttlSeconds may instead be sent as the X-Prerender-Cache-Ttl-Seconds header or GET query parameter. A successful response body is the rendered HTML and its status is the rendered document status. The engine also preserves durable 404 and 410 responses.
Response headers:
| Header | Meaning |
|---|---|
X-Prerender-Cache |
MISS for a fresh render or HIT for cached/coalesced output |
X-Prerender-Cache-Ttl |
Effective TTL in seconds |
X-Prerender-Time |
Fresh render duration in milliseconds |
X-Prerender-Final-Url |
Final validated document URL |
X-Prerender-Coordination |
COALESCED when the response joined an active render |
GET /cache/read?url=<encoded-url>reads a cached document without rendering. AddincludeExpired=trueonly for an intentional stale-read workflow.POST /cache/clearwith{"url":"https://example.com/"}removes one cache entry.GET /internal/metricsreturns uptime, active render capacity, active coalesced flights, cache usage, and process RSS memory. Treat this as an internal endpoint even though it is token-protected.
JSON errors use {"error":"message"}. Stable statuses are:
| Status | Meaning |
|---|---|
400 |
Missing/invalid URL or invalid JSON |
401 |
Missing or incorrect token |
403 |
Destination, redirect, CORS preflight, or navigation rejected by policy |
404 |
Unknown endpoint or cache miss; a render may also preserve an origin 404 as HTML |
413 |
Request body exceeds 16 KB, or rendered HTML exceeds the configured limit |
422 |
Per-render browser request budget exhausted |
429 |
Protected API request budget exhausted (unreleased) |
500 |
Browser or unexpected render failure |
503 |
Chromium not ready, render capacity reached, or coalescing wait exceeded |
504 |
Render timed out |
Honor Retry-After on 429 before retrying. Capacity responses may include Retry-After. Clients should retry 503 and 504 only with bounded exponential backoff and jitter. Do not retry policy 403, size 413, or request-budget 422 responses without changing the request or configuration.