Skip to main content

​
Rendering is asynchronous — there is no sync mode

The render request schema defines options.sync, but the render endpoint does not honor it. Every render is enqueued and the endpoint returns 202 with status: "queued" and downloadUrl: null. Do not wait on the create response for a finished PDF — poll the render, or use a webhook. 
// POST /v1/templates/:slug/render  → 202
{ "id": "…", "status": "queued", "pollUrl": "…/v1/renders/…", "downloadUrl": null, "errorMessage": null }
Poll with exponential backoff (250ms → 500ms → 1s → 2s → cap 5s) against a 30s deadline. See the loop in the Quickstart.

​
Status enum

The authoritative render status values are:
StatusMeaning
queuedaccepted, waiting for a worker
renderinga worker is producing the PDF
succeededterminal — downloadUrl is populated
failedterminal — errorMessage explains why
cancelleddefined in the enum but never produced today (no cancellation path)
Branch on succeeded and failed. There is no processing status — if you saw it in an older doc, the real intermediate state is rendering. You can treat cancelled defensively, but it will not occur.

​
downloadUrl durability

When a render succeeds, downloadUrl is the rendered PDF’s object-storage URL:
  • It is a permanent, public, non-presigned URL (the project’s public bucket base + the asset key). It does not expire on a TTL, and the path is unguessable (keyed by the render’s UUID).
  • It is null until the render succeeds, and also null if the deployment has no public bucket configured.
downloadUrl is not a time-limited link. If you need expiry or a private (non-public-bucket) download, use the partner-key private download stream or mint a revokable share link. Presigned/expiring downloadUrl support is on the roadmap.

​
Re-fetch later (offline replay)

GET /v1/renders/:id remains valid for your project key indefinitely after completion. This is the durable record for offline-first flows: the render may fire only on reconnect, and you can re-fetch its result by id at any later time. 
// GET /v1/renders/:id
{
  "id": "…",
  "status": "succeeded",
  "pollUrl": "…",
  "downloadUrl": "https://…/renders/…/….pdf",
  "errorMessage": null,
  "createdAt": "2026-06-05T10:00:00.000Z",
  "completedAt": "2026-06-05T10:00:03.120Z",
  "durationMs": 3120
}