Template drafts

Agents can create, update, validate and preview template drafts over MCP. Publishing is not available through MCP: a person publishes from the dashboard.

Generation always uses a template's published version. Draft edits never reach generated PDFs until someone clicks Publish in the dashboard, so agents can iterate on drafts safely. These tools need the template:write scope (create, update) and template:read (validate, preview).

Draft lifecycle

create_template_draft

Creates a new unpublished template from a name, HTML, JSON schema and sampleJson. Returns the template; its ID is structuredContent.template.id. Use that ID as templateId in every later call.

update_template_draft

Send templateId plus the fields to change. If you send html, schema or sampleJson, send non-empty schema and sampleJson too, so they stay in step with the HTML.

validate_template_draft, then preview

validate_template_draft reports Handlebars, helper and schema issues. preview_template_draft returns the rendered HTML inline with any validationErrors; preview_template_pdf returns a PDF as an embedded resource. Both use the draft sample JSON unless you pass data.

Publish in the dashboard

A person opens the template in the editor and clicks Publish. The new version is then used by generate_pdf, generate_pdf_and_wait and POST /v1/generate.

Parameters — create_template_draft

Parameter	Type	Required	Description
`name`	string	required	Display name, 1–200 chars
`html`	string	required	Handlebars HTML template
`schema`	object	required	Non-empty JSON Schema describing the data object
`sampleJson`	object	required	Non-empty example data covering every Handlebars variable in the HTML
`description`	string	optional	Max 1000 chars
`mode`	string	optional	`code` (default), `visual` or `pdfox-builder`
`css`	string	optional	CSS for the template
`bindings`	object	optional	Editor field bindings
`metadata`	object	optional	Template metadata, such as `pdfSettings`

A missing or empty schema or sampleJson fails with TEMPLATE_SCHEMA_REQUIRED or TEMPLATE_SAMPLE_JSON_REQUIRED. See MCP tools for the update_template_draft parameters.

// 1. create_template_draft
{
  "name": "Monthly Report",
  "html": "<h1>{{title}}</h1><p>{{body}}</p>",
  "css": "h1 { font-size: 24pt; color: #1a1a1a; }",
  "schema": {
    "type": "object",
    "properties": {
      "title": { "type": "string" },
      "body": { "type": "string" }
    },
    "required": ["title", "body"]
  },
  "sampleJson": { "title": "Q2 Report", "body": "Revenue up 12%." }
}
// → structuredContent.template.id = "3fa85f64-5717-4562-b3fc-2c963f66afa6"

// 2. validate_template_draft
{ "templateId": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }
// → structuredContent.valid = true

// 3. preview_template_draft (data is optional; defaults to sampleJson)
{
  "templateId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "data": { "title": "Q3 Report", "body": "Revenue up 15%." }
}
// → structuredContent.html (the rendered HTML)
//   structuredContent.validationErrors = []

// 4. Publish from the PDFox dashboard