Saved templates

Create and manage editable templates, start one from an AI chat message, preview changes, and publish fixed versions for repeat renders.

See all API resources or read the PDF generation API guide.

Endpoints

createTemplate

POST /v1/templates

Create a saved template

Create a template. Without message, source is required and the answer is the new template. With message, the request also starts the AI template chat of the template with its first message, and Idempotency-Key is required. Without source, version 1 is a blank design: one white A4 page for a PDF, or one white canvas of the requested image size (default 1080 by 1080). A replay with the same key returns the same template and message and creates nothing. If the message is refused, for example with 402 insufficient_credits, the new template is removed. A words or HTML message costs 25 credits. A source image costs 50 credits. The first message of a new blank template costs 50 credits. A source message makes no model call and costs 0 credits. A failed message keeps the previous draft and releases its reservation. All available credits, including free monthly credits, can pay for AI work. An account without enough available credits answers 402 insufficient_credits and holds nothing. Read message.progress for elapsed time, the current stages, and recent successful timing estimates. Estimates use the last 48 hours for the same model route and task when enough samples exist; completion time varies.

Authentication: bearer API key. See authentication.

Request body: application/json, TemplateWriteRequest.

listTemplates

GET /v1/templates

List saved templates

List the account's active and archived templates newest first. Source and schema are omitted. Pass next_cursor to continue with a stable keyset page.

Authentication: bearer API key. See authentication.

getTemplateSchemas

GET /v1/templates/schemas

Get template data schemas

Read the data schemas of up to 50 saved templates of the account. Use them to build forms, check data without code, or ask an AI model for data in the right shape. Choose templates with repeated template_id values, or with one tag. A tag selects active templates newest first. Each item names the exact version it uses. With form=saved, each schema is exactly as published, and a template without a schema has a null schema. With form=strict, each schema is converted to the subset that AI structured output accepts: every object has additionalProperties false and requires all its properties, an optional property also accepts null, oneOf becomes anyOf, and only type, properties, required, additionalProperties, items, enum, const, anyOf, description, $defs, and $ref stay. Length, item count, number range, pattern, format, and default rules become sentences in description. Remove null values of optional properties before you render with that data. With combine=one_of, combined is one schema with an object root. Its template property is any one of the templates, and each branch names template_id, version, and data. The $defs keys of each template get a prefix such as t0_. A template without a schema fails a strict or combined request with 422 template_schema_missing. A strict form with allOf, not, if, then, else, patternProperties, dependentSchemas, prefixItems, a map of additional properties, a non-object root, or a reference other than #/$defs/name fails with 422 template_schema_unsupported. A combined saved form fails the same way for a reference other than #/$defs/name. Unknown parameters and other combinations are 400 invalid_request.

Authentication: bearer API key. See authentication.

previewTemplate

POST /v1/templates/preview

Preview template data as HTML

Expand source and a JSON data object through the bounded template engine. Optional schema validation uses the saved-template rules. This does not save a template, create a render, or spend credits. The response is untrusted customer HTML for an isolated preview. Browser sessions need the current CSRF token.

Authentication: bearer API key. See authentication.

Request body: application/json, TemplatePreviewRequest.

adaptTemplate

POST /v1/templates/adapt

Adapt one HTML source to many canvas sizes

Deterministically adapt one canonical HTML source to up to 20 target canvas sizes. This is free, needs a session or key, and uses the preview rate limit. It does not save a template, create a render, or spend credits. The response gives the adapted source per size, or a safe error code for that size.

Authentication: bearer API key. See authentication.

Request body: application/json, TemplateAdaptRequest.

getTemplate

GET /v1/templates/{template_id}

Get a saved template

Without include, chat is a small summary with no messages, and message is the live message of the chat, if any. Poll this read while a message runs. With include=chat, chat also has its newest 100 messages.

Authentication: bearer API key. See authentication.

renameTemplate

PATCH /v1/templates/{template_id}

Rename a saved template

Set or clear the name of one owned template. The name is trimmed and can have 1 to 120 characters. A null or blank name clears it.

Authentication: bearer API key. See authentication.

Request body: application/json, TemplateRename.

archiveTemplate

DELETE /v1/templates/{template_id}

Archive a saved template

Archive one owned template. The operation is idempotent. Archived templates and versions remain readable, but they cannot receive another version or create another render.

Authentication: bearer API key. See authentication.

createTemplateVersion

POST /v1/templates/{template_id}/versions

Create a template version

Edit a template by publishing one complete new immutable source and optional schema. Existing versions never change. Archived templates cannot receive another version.

Authentication: bearer API key. See authentication.

Request body: application/json, TemplateVersionWriteRequest.

listTemplateVersions

GET /v1/templates/{template_id}/versions

List template versions

List immutable versions newest first. Source and schema are omitted. Archived template versions remain readable.

Authentication: bearer API key. See authentication.

getTemplateVersion

GET /v1/templates/{template_id}/versions/{version}

Get a template version

Read one saved, immutable version of a template.

Authentication: bearer API key. See authentication.

Schemas

TemplateFirstMessage

Schema rules: {"type":"object","additionalProperties":false}.

TemplateTags

Trimmed tags. Each tag is nonblank. Case is preserved.

Schema rules: {"type":"array","maxItems":20,"uniqueItems":true,"items":{"type":"string","minLength":1,"maxLength":40}}.

TemplateName

The customer's own name for a template. It is trimmed and can have 1 to 120 characters. Null or blank means no name.

Schema rules: {"type":["string","null"],"maxLength":120}.

TemplateWriteRequest

Schema rules: {"type":"object","anyOf":[{"required":["source"]},{"required":["message"]}],"additionalProperties":false}.

TemplateVersionWriteRequest

Schema rules: {"type":"object","additionalProperties":false}.

TemplatePreviewRequest

Schema rules: {"type":"object","additionalProperties":false}.

TemplatePreview

Schema rules: {"type":"object","additionalProperties":false}.

TemplateRename

Omitted fields keep their current values. Set name to null to clear it, tags to an empty array to clear them, or archived_at to null to restore the template.

Schema rules: {"type":"object","additionalProperties":false}.

TemplateSummary

Schema rules: {"type":"object","additionalProperties":false}.

TemplateDetail

Schema rules: {"type":"object","additionalProperties":false}.

TemplatePage

Schema rules: {"type":"object","additionalProperties":false}.

TemplateVersionSummary

Schema rules: {"type":"object","additionalProperties":false}.

TemplateVersionPage

Schema rules: {"type":"object","additionalProperties":false}.

TemplateSchemaItem

Schema rules: {"type":"object","additionalProperties":false}.

TemplateSchemaSet

Schema rules: {"type":"object","additionalProperties":false}.

TemplateAdaptRequest

Adapt one HTML source to many target canvas sizes with the deterministic layout algorithm. This is free and does not save anything.

Schema rules: {"type":"object","additionalProperties":false}.

TemplateAdaptResponse

Schema rules: {"type":"object","additionalProperties":false}.

Shared errors, headers, and authentication schemes are in shared types and security.