List document templates
Lists every document template the caller's organization has authored - printed layouts (invoice, credit note, quote) AND email templates, which are a document type of their own. An email row carries anchor_key and the anchor's human name in the request locale; printed rows carry neither. Filter with document_type when you are filling a printed-document picker, because preview-as-PDF and make-this-the-default are meaningless on an email. Filter with status to narrow the lifecycle (printed templates are active or archived, emails are draft, published or archived); omit it to include archived ones. Ask for counts=document_type to get the per-kind tallies a filter-chip bar renders, taken in the same read. The first page prepends built-in system defaults so a picker always has a baseline.
query Parameters
limitPage size. Values above the server-side cap are clamped (standard default 50, cap 200; a few document-heavy lists use larger windows). Invalid values fall back to the default.
cursorOpaque continuation token from the previous response's pagination.cursor. Omit for the first page. Cursors are stateless and do not expire, but are only valid for the list and filters that produced them.
sortOrdering: updated_at, with an optional :asc/:desc suffix (default updated_at:desc, most recently edited first). An unknown value is rejected. Cursors are bound to the ordering that issued them, so changing sort mid-walk needs a fresh first page.
document_typeFilter to templates supporting one document type (invoice, credit_note, quote or email); omit for all kinds, email included.
statusFilter to one lifecycle status. Omit to include every status, archived ones included. Printed templates are active or archived; email templates are draft, published or archived.
anchor_keyFilter to the email templates written for one mail kind, e.g. "invoice.finalized". Implies email: a printed template has no anchor.
countsComma-separated facet fields to tally for filter chips. Only "document_type" is supported; it returns counts.document_type.{all,invoice,credit_note,quote,email}.
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
List document templates › Responses
OK
Create a document template
Creates a new document template owned by the caller's organization. TemplateJSON is validated against the current schema and stamped with the current schema version on write.
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Create a document template › Request Body
descriptionFree-text description of the template.
nameTemplate name (required).
The template document: ordered blocks plus theme, branding, and footer.
document_typesDocument types this template can render (subset of {invoice, credit_note, quote, email}); defaults to [invoice] when omitted.
Create a document template › Responses
Created
Get a document template
Returns a single template. Built-in system defaults are resolved from in-memory definitions; custom templates come from the org's repository.
path Parameters
idDocument template ID
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Get a document template › Responses
OK
Delete a document template
Soft-deletes an org-owned document template. System defaults cannot be deleted.
path Parameters
idDocument template ID
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Delete a document template › Responses
No Content
Update a document template
Updates an org-owned document template. Requires expected_version for optimistic locking.
path Parameters
idDocument template ID
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Update a document template › Request Body
expected_versionOptimistic-concurrency token: the version you last read. REQUIRED on this resource; a stale value answers 409 CONFLICT.
descriptionNew description; omit to leave unchanged.
document_typesNew set of renderable document types; omit to leave unchanged.
nameNew template name; omit to leave unchanged.
statusNew status (active or archived); omit to leave unchanged.
Replacement template document; omit to leave unchanged.
Update a document template › Responses
OK
Copy a document template
Creates a writable copy of the given template under the caller's organization. System defaults are copied by snapshotting the in-memory baseline.
path Parameters
idDocument template ID
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Copy a document template › Responses
Created
Mark a document template as the org default for a document type
Marks the given template as the organization's favorite for the document type in the path (invoice, credit_note or quote). The favorite is per kind, so setting the credit-note favorite leaves the invoice and quote favorites alone. System templates are valid targets.
path Parameters
idDocument template ID
documentTypeWhich kind this template is the default for (invoice, credit_note or quote)
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Mark a document template as the org default for a document type › Responses
OK
Clear the org default for a document type
Clears this template's favorite slot for the document type in the path. Rendering for that kind falls back to the system default - never to nothing. Only succeeds if this template currently holds the slot. Returns the template with its updated default memberships.
path Parameters
idDocument template ID
documentTypeWhich kind this template is the default for (invoice, credit_note or quote)
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Clear the org default for a document type › Responses
OK
Render a document template preview PDF
Renders a sample PDF using the stored template, or - if a template_json body is supplied - using that unsaved draft. Rendered output is short-TTL cached so repeated calls return identical bytes. Rate-limited per organization.
path Parameters
idDocument template ID
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Render a document template preview PDF › Request Body
document_typeSingle document type to render; defaults to INVOICE.
document_typesDocument types to render (e.g. INVOICE, CREDIT_NOTE); defaults to the template's.
Unsaved template draft to preview instead of the stored template.
Render a document template preview PDF › Responses
PDF file
Get a document-template thumbnail SVG
A lightweight SVG schematic of the template (block layout in theme colors) suitable for picker cards. Strongly cached with an ETag keyed on updated_at - clients should send If-None-Match.
path Parameters
idDocument template ID
Headers
If-None-MatchConditional request: prior ETag
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Get a document-template thumbnail SVG › Responses
SVG thumbnail