Automette

POST /api/v1/renders creates one render from a template and the data you supply. Returns immediately in async mode (default) or waits for the file in sync mode.

POST /api/v1/renders
Authorization: Bearer dg_your_api_key
Content-Type:  application/json

Request body

Field	Type	Required	Description
`template_id`	string	yes	ID of the template to render. Find it in the dashboard or via `GET /api/v1/templates`.
`data`	object	no	Field values for the template. Non-string values (numbers, booleans, arrays, objects) are auto-serialized to JSON strings before being passed to the renderer.
`visibility`	string	no	`"public"` (CloudFront-cached, shareable URL) or `"secure"` (presigned URL only). Defaults to `"public"`.
`async`	boolean	no	`true` (default) — returns 202 immediately. `false` — waits up to 30 seconds for the rendered file; if the render takes longer, the request returns 202 with `status: "pending"` and the render continues in the background — fall back to polling, exactly like async mode.
`webhook_url`	string	no	HTTPS URL to POST when the render completes (or fails). Independent of any global webhook subscriptions.
`formats`	array	no	DOCX templates only — `["pdf"]`, `["docx"]`, or both. Ignored for Typst and Canvas engines.
`filename_pattern`	string	no	Pattern for the output filename, e.g. `"invoice-{date}-{customer_name}"`. Overrides the template's default pattern. Tokens: `{template}`, `{date}`, `{time}`, `{datetime}`, `{random}`, and any `{field_key}` from `data`. Defaults to `{template}-{datetime}-{random}`.

Response

Async (default) — 202

{
  "id": "cm4rnd7qh0001jx04w8e2t5va",
  "self": "https://automette.com/api/v1/renders/cm4rnd7qh0001jx04w8e2t5va",
  "status": "pending",
  "url": null,
  "format": "pdf",
  "template_id": "cm4tpl8e20001js04xq2v9k3m",
  "template_name": "Invoice",
  "data": { "name": "Alice" },
  "created_at": "2026-04-22T12:00:00.000Z"
}

Poll GET /api/v1/renders/{id} — or set webhook_url and skip polling entirely.

Sync — 200

{
  "id": "cm4rnd7qh0001jx04w8e2t5va",
  "self": "https://automette.com/api/v1/renders/cm4rnd7qh0001jx04w8e2t5va",
  "status": "completed",
  "url": "https://cdn.automette.com/renders/cm4rnd7qh0001jx04w8e2t5va.pdf",
  "format": "pdf",
  "template_id": "cm4tpl8e20001js04xq2v9k3m",
  "template_name": "Invoice",
  "data": { "name": "Alice" },
  "created_at": "2026-04-22T12:00:00.000Z"
}

DOCX templates

When the template's engine is docx, the response additionally includes a files array — one entry per requested format:

"files": [
  { "format": "pdf",  "url": "https://..." },
  { "format": "docx", "url": "https://..." }
]

In async responses the URLs are null until the render completes; poll GET /api/v1/renders/{id} for the final values.

Errors

Code	When
`400`	Missing `template_id` or invalid JSON body
`401`	Missing or invalid API key
`402`	Insufficient credits — body includes `required_credits` and `available_credits`
`404`	Template not found (or not in your team)
`422`	Render failed (Typst compile error, missing assets, etc.) — see `error` field

A sync request that exceeds the 30-second timeout is not an error: it returns 202 with status: "pending" and the render finishes in the background.

Example

curl -X POST https://automette.com/api/v1/renders \
  -H "Authorization: Bearer dg_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "cm4tpl8e20001js04xq2v9k3m",
    "data": {
      "name": "Alice",
      "items": [{ "desc": "Design", "qty": 1, "price": 3000 }]
    },
    "async": false
  }'

Visibility

public — File is served from CloudFront. The url in the response is the final, cacheable share URL. Best for embedding in emails, social posts, or public web pages.
secure — File is served via a short-lived presigned URL. The url in the response points to /api/v1/renders/{id}?download=true, which redirects to a fresh presigned URL on each hit. Best for sensitive documents (invoices, contracts).

Render a document