Automette docs
API Reference

List renders

GET
/api/v1/renders

Authorization

ApiKeyAuth
AuthorizationBearer <token>

API key from Settings → API Keys.

In: header

Query Parameters

status?string

Value in

  • "pending"
  • "running"
  • "completed"
  • "failed"
template_id?string
limit?integer
Rangevalue <= 100
Default20
cursor?string

Render ID from a previous response's next_cursor.

Response Body

application/json

application/json

curl -X GET "https://example.com/api/v1/renders"
{  "renders": [    {      "id": "cm4rnd7qh0001jx04w8e2t5va",      "self": "https://automette.com/api/v1/renders/cm4rnd7qh0001jx04w8e2t5va",      "status": "completed",      "url": "https://cdn.automette.com/p/cm4rnd7qh0001jx04w8e2t5va/document.pdf",      "format": "pdf",      "template_id": "cm4tpl8e20001js04xq2v9k3m",      "template_name": "Invoice",      "error": null,      "created_at": "2026-04-22T12:00:00.000Z"    }  ],  "next_cursor": null}

Preview a library template POST

Renders a library design **with your own data**, before you copy it. Returns a signed URL valid for one hour. The `preview_url` on the detail endpoint shows the design with the library's sample data. This shows it with yours, which is the question someone choosing between two certificates actually has. Fields you do not supply keep the sample values, so an empty body still returns a filled page — except on a Word template, whose fields carry no sample values and fall back to their own names. Free, like every other preview: no render record, no credit, and **no template created** — so it works on a plan already at its template limit, which is precisely when you most want to look before copying. To keep the design, POST to `/api/v1/templates` with `{ "from_library": "<slug>" }`.

Generate a document POST

Generates a PDF or image from a template and your data. **Async (default)** — returns `202 Accepted` immediately with `status: "pending"`. Poll `GET /api/v1/renders/{id}` until `status` is `completed`, or set `webhook_url` to receive a callback and skip polling entirely. **Sync** — set `async: false`. Returns `200 OK` with a completed render if it finishes within 30 seconds. If the render takes longer, the request returns `202` with `status: "pending"` and the render finishes in the background — fall back to polling exactly like async mode. A sync timeout is **not** an error. **Visibility** — in both cases the `url` in the response is a link you can hand to anyone; the difference is how long it lasts and who else could find it. - `public` — file is served from CloudFront. `url` is permanent, cacheable, and readable by anyone who has it. Best for embedding in emails, social posts, or public web pages. - `secure` (default) — file is stored privately and `url` is a signed link valid for 1 hour. Fetch the render again via `self` at any time for a fresh one. Best for sensitive documents (invoices, contracts). **Output formats** — all engines support multiple output formats in one request. Use `format` (single string) or `formats` (array) to specify. Allowed values by engine: Typst `pdf`, `png`, `jpg`; Canvas `png`, `jpg`, `webp`, `pdf`; DOCX `pdf`, `docx`. Defaults to `pdf` for Typst/DOCX and `png` for Canvas. The response always includes a `files` array — one entry per output file. **Filename patterns** — the `filename_pattern` field accepts `{field_key}` placeholders and built-in tokens: `{template}`, `{date}`, `{time}`, `{datetime}`, `{random}`. Defaults to `{template}-{datetime}-{random}`. **Non-string data values** (numbers, booleans, arrays, objects) are auto-serialized to JSON strings before being passed to the renderer.