# Render API reference

Render API endpoints, authentication headers, and request fields.

## 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.

```json
{"code":"PDF_TEMPLATE_VERSION_NOT_PUBLISHED","description":"template version is not published","details":[]}
```

A successful status response can include:

```json
{"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:

```json
{"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.