Skip to main content

Templates

Tag: Templates · Version: v1 · Stability: 🟢 Stable

A template is the reusable document blueprint: a name, HTML-ish content with {{token}} placeholders, and (optionally) an uploaded base PDF to design over. All endpoints are JWT-only and workspace-scoped — a template from another workspace returns 404.

Rendering a template lives on its own page: Rendering.

List templates​

GET /api/templates · JWT

QueryTypeNotes
namestringOptional filter by name.

Create a template​

POST /api/templates · JWT

Request — CreateTemplateBody
{
  "name": "Invoice",
  "content": "<h1>Invoice {{invoiceNumber}}</h1><p>Total: {{total}}</p>"
}

Both name and content are required. Returns the new template, including its id (UUID).

Get a template​

GET /api/templates/{id} · JWT — {id} is a UUID.

Update a template​

PUT /api/templates/{id} · JWT

Request — UpdateTemplateBody
{
  "name": "Invoice (2026)",
  "content": "<h1>Invoice {{invoiceNumber}}</h1>",
  "expectedUpdatedAt": "2026-06-07T10:00:00Z"
}

content is required; name and expectedUpdatedAt are optional.

:::warning Optimistic concurrency Pass the expectedUpdatedAt you last read. If a teammate saved in the meantime, the server returns 409 Conflict instead of silently overwriting their change. Re-fetch, reconcile, and retry. :::

Delete a template​

DELETE /api/templates/{id} · JWT

Base-PDF overlay​

Attach an uploaded PDF as a template's background layer, then position elements on top of it. The server rasterises each page to a PNG so the designer canvas and the rendered output share a byte-identical base (true WYSIWYG). JWT-only — this is a design-time feature, not part of the render API.

Upload a base PDF​

POST /api/templates/{id}/base-pdf · JWT · multipart/form-data

PartTypeRequired
filebinary (IFormFile)✅

Uploads and rasterises the PDF. Rejected: encrypted/password-protected, XFA/ dynamic forms, oversized, corrupt, or (MVP) mixed-page-size files — each with a clear error.

Get base-PDF metadata​

GET /api/templates/{id}/base-pdf · JWT — page count and per-page dimensions.

Get a rendered page image​

GET /api/templates/{id}/base-pdf/pages/{index} · JWT

{index} is an integer (0-based) page index. Returns the page raster (PNG) used as the canvas/render background.

Remove the base PDF​

DELETE /api/templates/{id}/base-pdf · JWT