Templates

Built-in templates first, then the caller's own, most recently updated first, a page at a time. Each row is the current version without its html and css — read one with GET /api/v1/templates/{id}, which is also the document POST /api/v1/templates/import takes back.

FILTER: omit for both, builtin for the shipped ones only, user for your own only.

One page of templates; meta says whether there is another

Creates version 1 and answers 201 with it. name, html, width and height are required. html ≤ 256 KB and css ≤ 128 KB (UTF-8 bytes), width / height 1–4096 px; anything outside is 400 invalid_param naming the field. variables defaults to the {{ … }} names found in the html and css. Each account may own at most 200 templates (422 resource_limit_exceeded).

Rendering is POST /api/v1/jobs {"op": "render_template", "templateId": …, "items": [...]}, or one row now with POST /api/v1/images/render.

The template, at version 1

Takes a list of template documents — what GET /api/v1/templates/{id} returns, one per template — and creates each as a new template at version 1: history and slug are not carried over (the slug is made from the name, with a numeric suffix when it is taken). The list rows of GET /api/v1/templates carry no html, so they are not an export.

Each entry is checked like a create; one that fails is reported in errors and the rest still land, so a 201 can carry refusals — read errors. The whole import is refused (422 resource_limit_exceeded) if it would take the account past 200 templates.

What landed, and one line per entry that did not

{id} is a template id (or your own slug) for the current version, or {id}@{version} for one specific version — the same spelling render_template accepts as templateId, so what a job rendered with can always be read back. Built-ins have exactly one version.

An earlier version comes back as a document whose id is {id}@{version}, without slug, description or updatedAt — those belong to the template, not to a version of it.

The template document

Send only what changes: the body is merged over the current version, and a field it leaves out keeps its value ({"width": 1080, "height": 1080} is a whole update); "" empties css or description. variables, when not sent, stay as they are unless html or css changes, and are then derived from the new markup. Same limits as create. Never edits in place: the template moves to version + 1 — every PUT does, a rename included — and the previous bytes stay readable as {id}@{version}, so a job or automation that pinned a version keeps rendering exactly that. Built-in ids are 403; to start from one, create your own with its html.

The template, at its new version

Deletes the template and every version of it. A render job already rendering keeps the bytes it was handed; one still queued behind the account's other jobs fails unstarted (invalid_state). Built-in ids are 403.

Deleted; no body

Every version ever saved, newest first, each as a full document — html and css included — whose id is {id}@{version} and which has no slug, description or updatedAt. Not paged: a template's history is one answer. A built-in answers with its one current document.

Every version, newest first