API reference

GET /healthz

Health check

Answers

• 200 The API is up

GET /v1/templates

List templates

Answers

• 200 The workspace's templates, newest first
• 401 No API key, or the key is not valid
• 429 Too many requests; see Retry-After
• 451 The workspace is frozen (`frozen`), or a reviewer workspace has ended (`expired`)

POST /v1/templates

Create a template from a scene

Body

Answers

• 201 The new template (a draft; publish it to render it)
• 400 The request is not valid; `field` names the problem
• 401 No API key, or the key is not valid
• 402 A plan limit is reached: `no_credits` (no credits left in this period) or `plan_limit` (templates, members or stored files)
• 413 Too large
• 429 Too many requests; see Retry-After
• 451 The workspace is frozen (`frozen`), or a reviewer workspace has ended (`expired`)

POST /v1/templates/generate

Make a draft template from a description (AI). The AI template maker (spec 11.3). The result is a draft that the validator accepts; it is never published by itself. Limits: the plan's AI templates a month, and a daily cap for the whole service.

Body

Answers

• 201 The new draft template
• 400 The request is not valid; `field` names the problem
• 401 No API key, or the key is not valid
• 402 A plan limit is reached: `no_credits` (no credits left in this period) or `plan_limit` (templates, members or stored files)
• 422 The request cannot be done; `code` says why (for example an Idempotency-Key used with a different body)
• 429 Too many requests; see Retry-After
• 451 The workspace is frozen (`frozen`), or a reviewer workspace has ended (`expired`)
• 502 A service we use failed; try again
• 503 Not available now: a set-up step is missing, or a daily limit is reached; `code` says which
• 504 A service we use took too long; try again

GET /v1/templates/{id}

Get a template, its params and versions

Answers

• 200 The template
• 401 No API key, or the key is not valid
• 404 Not found
• 429 Too many requests; see Retry-After
• 451 The workspace is frozen (`frozen`), or a reviewer workspace has ended (`expired`)

DELETE /v1/templates/{id}

Delete a template. Signed links and renders of it stop at once (404). Files already made stay until they expire. The template no longer counts toward the plan's limit.

Answers

• 200 Deleted
• 401 No API key, or the key is not valid
• 404 Not found
• 429 Too many requests; see Retry-After
• 451 The workspace is frozen (`frozen`), or a reviewer workspace has ended (`expired`)

PUT /v1/templates/{id}/draft

Save the draft scene

Body

Answers

• 200 The template with the new draft
• 400 The request is not valid; `field` names the problem
• 401 No API key, or the key is not valid
• 404 Not found
• 413 Too large
• 429 Too many requests; see Retry-After
• 451 The workspace is frozen (`frozen`), or a reviewer workspace has ended (`expired`)

POST /v1/templates/{id}/publish

Publish the draft as a new version. Signed links and renders without a `version` use the newest published version.

Answers

• 200 The new version
• 400 The request is not valid; `field` names the problem
• 401 No API key, or the key is not valid
• 404 Not found
• 409 Conflict
• 429 Too many requests; see Retry-After
• 451 The workspace is frozen (`frozen`), or a reviewer workspace has ended (`expired`)

POST /v1/templates/{id}/duplicate

Copy a template (its draft)

Body

Answers

• 201 The copy
• 401 No API key, or the key is not valid
• 402 A plan limit is reached: `no_credits` (no credits left in this period) or `plan_limit` (templates, members or stored files)
• 404 Not found
• 429 Too many requests; see Retry-After
• 451 The workspace is frozen (`frozen`), or a reviewer workspace has ended (`expired`)

POST /v1/assets

Upload an image or CSV. Send `multipart/form-data` with a `file` (and an optional `name`), or JSON `{"url": "https://…"}` to fetch it. Images: PNG, JPEG, GIF, WebP, SVG up to 20 MB and 16 megapixels (bigger ones are refused with `image_too_large`; the editor makes them smaller before it uploads them). CSV: UTF-8 up to 5 MB. A workspace stores up to 500 MB of files on Free and 10 GB on paid plans.

Body

Answers

• 201 The stored asset
• 400 The request is not valid; `field` names the problem
• 401 No API key, or the key is not valid
• 402 A plan limit is reached: `no_credits` (no credits left in this period) or `plan_limit` (templates, members or stored files)
• 413 Too large
• 429 Too many requests; see Retry-After
• 451 The workspace is frozen (`frozen`), or a reviewer workspace has ended (`expired`)

GET /v1/assets

List assets

Answers

• 200 Newest first, at most 500
• 401 No API key, or the key is not valid
• 429 Too many requests; see Retry-After
• 451 The workspace is frozen (`frozen`), or a reviewer workspace has ended (`expired`)

GET /v1/assets/{id}/uses

Templates that use an asset. For a confirm step before a delete: the templates whose draft or a saved version uses the asset. A delete is refused (409) while a saved version uses it.

Answers

• 200 At most 100
• 401 No API key, or the key is not valid
• 404 Not found
• 429 Too many requests; see Retry-After
• 451 The workspace is frozen (`frozen`), or a reviewer workspace has ended (`expired`)

DELETE /v1/assets/{id}

Delete an asset. Refused (409 `in_use`) while a saved version of a template that is not deleted uses it. GET /v1/assets/{id}/uses lists the templates.

Answers

• 200 Deleted
• 401 No API key, or the key is not valid
• 404 Not found
• 409 Conflict
• 429 Too many requests; see Retry-After
• 451 The workspace is frozen (`frozen`), or a reviewer workspace has ended (`expired`)

GET /v1/assets/{id}/file

Download an asset's file. The uploaded file itself, with its own type (a cleaned SVG for SVG uploads).

Answers

• 200 The file
• 401 No API key, or the key is not valid
• 404 Not found
• 429 Too many requests; see Retry-After
• 451 The workspace is frozen (`frozen`), or a reviewer workspace has ended (`expired`)

POST /v1/render

Render a template. Renders each size as one file. 1 image or 1 PDF page = 1 credit; files that already exist for the same input answer at once (`cached: true`) and cost nothing. `mode: async` (or a PDF over 10 pages, or more than 5 sizes) answers 202 with a job to poll. `?inline=1` (one output) streams the bytes.

Body

Answers

• 200 The finished render (with ?inline=1: the file itself)
• 202 Queued as a job
• 400 The request is not valid; `field` names the problem
• 401 No API key, or the key is not valid
• 402 A plan limit is reached: `no_credits` (no credits left in this period) or `plan_limit` (templates, members or stored files)
• 404 Not found
• 409 Conflict
• 413 Too large
• 422 The request cannot be done; `code` says why (for example an Idempotency-Key used with a different body)
• 429 Too many requests; see Retry-After
• 451 The workspace is frozen (`frozen`), or a reviewer workspace has ended (`expired`)

DELETE /v1/renders/{id}

Cancel a queued job. Only a job that has not started can be canceled; its credits come back.

Answers

• 200 The canceled job
• 401 No API key, or the key is not valid
• 404 Not found
• 409 Conflict
• 429 Too many requests; see Retry-After
• 451 The workspace is frozen (`frozen`), or a reviewer workspace has ended (`expired`)

GET /v1/renders/{id}

Get a render or job

Answers

• 200 The render
• 401 No API key, or the key is not valid
• 404 Not found
• 429 Too many requests; see Retry-After
• 451 The workspace is frozen (`frozen`), or a reviewer workspace has ended (`expired`)

POST /v1/preview

A free low-res preview with a watermark. Send a `scene` (no key needed; free tools and the docs use this) or, with an API key, a `template`. The answer is the image itself, at most 600 px on its long side. 30 a minute.

Body

Answers

• 200 The image
• 400 The request is not valid; `field` names the problem
• 401 No API key, or the key is not valid
• 403 Not allowed
• 404 Not found
• 413 Too large
• 429 Too many requests; see Retry-After
• 451 The workspace is frozen (`frozen`), or a reviewer workspace has ended (`expired`)

POST /v1/links

Make a signed link. A link that renders the template when it is opened (spec 7.2). Data values are strings; at most 2,048 characters each.

Body

Answers

• 200 The link
• 400 The request is not valid; `field` names the problem
• 401 No API key, or the key is not valid
• 404 Not found
• 429 Too many requests; see Retry-After
• 451 The workspace is frozen (`frozen`), or a reviewer workspace has ended (`expired`)
• 503 Not available now: a set-up step is missing, or a daily limit is reached; `code` says which

POST /v1/batch

Render many rows. Up to 10,000 rows of data (from `rows`, an uploaded CSV or a CSV link). Credits for every row are reserved at once; failed rows give theirs back. Poll GET /v1/batch/{id}, or give a webhook_url.

Body

Answers

• 202 Queued
• 400 The request is not valid; `field` names the problem
• 401 No API key, or the key is not valid
• 402 A plan limit is reached: `no_credits` (no credits left in this period) or `plan_limit` (templates, members or stored files)
• 404 Not found
• 409 Conflict
• 413 Too large
• 422 The request cannot be done; `code` says why (for example an Idempotency-Key used with a different body)
• 429 Too many requests; see Retry-After
• 451 The workspace is frozen (`frozen`), or a reviewer workspace has ended (`expired`)

GET /v1/batch/{id}

Get a batch: counts and each row's render

Answers

• 200 The batch
• 401 No API key, or the key is not valid
• 404 Not found
• 429 Too many requests; see Retry-After
• 451 The workspace is frozen (`frozen`), or a reviewer workspace has ended (`expired`)

GET /v1/batch/{id}/zip

Download a batch's ZIP. The ZIP of a batch sent with `zip: true`, once the batch shows a `zip_url`. 404 while it is not ready, and after it expires with the batch's files (the last of its renders): `zip_url` is then null again.

Answers

• 200 The ZIP file
• 401 No API key, or the key is not valid
• 404 Not found
• 429 Too many requests; see Retry-After
• 451 The workspace is frozen (`frozen`), or a reviewer workspace has ended (`expired`)

POST /v1/webhooks

Add a webhook. Events are POSTed as JSON with `MR-Signature: t={unix},v1={hex HMAC-SHA256(secret, t + "." + body)}`. The secret is shown only in this answer.

Body

Answers

• 201 The webhook and its secret
• 400 The request is not valid; `field` names the problem
• 401 No API key, or the key is not valid
• 429 Too many requests; see Retry-After
• 451 The workspace is frozen (`frozen`), or a reviewer workspace has ended (`expired`)

GET /v1/webhooks

List webhooks

Answers

• 200 Webhooks
• 401 No API key, or the key is not valid
• 429 Too many requests; see Retry-After
• 451 The workspace is frozen (`frozen`), or a reviewer workspace has ended (`expired`)

DELETE /v1/webhooks/{id}

Delete a webhook

Answers

• 200 Deleted
• 401 No API key, or the key is not valid
• 404 Not found
• 429 Too many requests; see Retry-After
• 451 The workspace is frozen (`frozen`), or a reviewer workspace has ended (`expired`)

GET /v1/deliveries

Recent webhook deliveries (every try)

Answers

• 200 Newest first
• 401 No API key, or the key is not valid
• 429 Too many requests; see Retry-After
• 451 The workspace is frozen (`frozen`), or a reviewer workspace has ended (`expired`)

POST /v1/deliveries/{id}/resend

Send a delivery again

Answers

• 200 The new delivery (tried now; retried like any other)
• 401 No API key, or the key is not valid
• 404 Not found
• 429 Too many requests; see Retry-After
• 451 The workspace is frozen (`frozen`), or a reviewer workspace has ended (`expired`)

GET /v1/usage

Credits and renders this period

Answers

• 200 Usage
• 401 No API key, or the key is not valid
• 429 Too many requests; see Retry-After
• 451 The workspace is frozen (`frozen`), or a reviewer workspace has ended (`expired`)