Authentication
Send an ApiKey header for a project key with template:render. This is not a browser session.
POST /v1/pdf/render
| JSON field | Meaning |
|---|---|
template_id |
Required template UUID, not a slug |
version |
Version number; omitted selects the template’s current version |
variant |
Optional variant name |
parameters |
Input object matching the template |
The target must be published. Rendering uses committed content, not unsaved browser edits. Acceptance is HTTP 202 with render_id, status: queued and status_url, not PDF bytes or a success guarantee.
GET /v1/renders/{render_id}
Use the same key. The response includes render_id, status and optional result fields such as error_message, duration_ms and download_url. Processing is pending; terminal states are success, failed and quota_exceeded.
Immediately after a 202 response, the status endpoint can briefly return 404 while the workflow creates its history row. Retry that newly accepted render ID with a short delay and a bounded deadline. A persistent 404, an unknown ID, or a project/key mismatch needs investigation; do not resubmit POST just because the first status lookup returned 404.
GET /v1/renders/{render_id}/download
Use an appropriate project key. Successful output returns PDF bytes while available. It is not a permanent public URL.
Errors and retries
Authentication, ownership and missing/unpublished versions can fail before acceptance. Later processing failures appear through status. Correct 4xx requests/permissions before retrying, and do not assume public POST idempotency support.
Error response
Errors use code, description, and optional details. Read the code to decide what to fix; an accepted render can fail later and report error_message through status.
{"code":"PDF_TEMPLATE_VERSION_NOT_PUBLISHED","description":"template version is not published","details":[]}A successful status response can include:
{"render_id":"<render-uuid>","status":"success","duration_ms":1200,"download_url":"/v1/renders/<render-uuid>/download"}A processing failure is a status result, for example:
{"render_id":"<render-uuid>","status":"failed","error_message":"Failed to compile template"}Scope
This reference covers public rendering endpoints, not every session-only management API used by the app. Poll with delays and a bounded deadline; retain the render ID after acceptance.