Templates

Templates are reusable HTML documents with variable placeholders. Instead of sending raw HTML with every render request, you create a template once and pass only the dynamic data at render time. This keeps your API calls small, your designs consistent, and your content easy to update.

Variable Syntax

Templates use double curly braces for variables:

<h1>{{title}}</h1>
<p>By {{author}} on {{date}}</p>

When you create or update a template, PixDoc automatically detects all {{variableName}} patterns in your HTML and stores them as the template's variable list. Variable names must contain only letters, numbers, and underscores.

Default Values

You can set default values for any variable. If a variable is not provided at render time, the default is used instead:

{
  "defaults": {
    "title": "Untitled",
    "author": "Anonymous",
    "date": "2026"
  }
}

If a variable has no default and is not provided at render time, the request fails with a MISSING_VARIABLES error listing which variables are missing.

Creating Templates

Via the Dashboard (Recommended)

Go to Dashboard > Templates to create and manage templates. The dashboard provides a live preview, variable detection, and API usage snippets for each template.

Via the API

curl -X POST https://pixdoc.dev/api/v1/templates \
-H "Authorization: Bearer pd_live_a3b2c4d5..." \
-H "Content-Type: application/json" \
-d '{
  "name": "monthly-report",
  "display_name": "Monthly Report",
  "html": "<div style=\"padding:40px;font-family:system-ui;\"><h1>{{title}}</h1><p>Prepared by {{author}}</p><p>{{summary}}</p></div>",
  "defaults": {
    "title": "Monthly Report",
    "author": "Team Lead"
  }
}'

Required fields:

Optional fields:

Versioning

Templates have an auto-incrementing version number. The version increments each time you update the template's HTML content. Other changes (like updating display_name or defaults) do not trigger a version bump.

Versioning is useful for cache busting with OG images. Pass ?v=2 in the OG URL to ensure users see the latest version of your template after an update.

Version Pinning

API consumers can pin a specific template version to prevent template edits from breaking production integrations. When you update a template's HTML, the version number increments automatically, but existing renders that specify a pinned version continue to use the exact HTML from that version.

To pin a version, include template_version in your render request:

{
  "template_id": "550e8400-e29b-41d4-a716-446655440000",
  "template_version": 3,
  "variables": { "title": "Q1 Report" }
}

For OG images, use the v query parameter:

GET /api/v1/og/blog-card?key=pd_live_...&v=3&title=Hello+World

Key behaviors:

• If template_version (or v for OG images) is omitted, the latest version is always used
• Versions are preserved indefinitely — old versions remain available even after new updates
• Pinning a version that does not exist returns a 400 validation error
• This is especially useful for production systems (invoicing, receipts, compliance documents) where template consistency matters

Pre-built Templates

PixDoc includes twenty-three public templates available to all accounts:

Pre-built templates are public and read-only. You can use them directly or duplicate them via the dashboard to customize.

Auto-Save

Your work is saved automatically after a few seconds of inactivity. You can also press Cmd+S (or Ctrl+S) to save immediately. If you try to leave the page with unsaved changes, you will see a confirmation prompt.

API Reference

List Templates

GET /api/v1/templates

Returns your templates and all public templates, sorted by most recently updated.

Create Template

POST /api/v1/templates

Creates a new template. Returns 201 on success, 409 if the name is already taken.

Get Template

GET /api/v1/templates/{id}

Returns a single template by its UUID. You can access templates you own and public templates.

Update Template

PUT /api/v1/templates/{id}

Updates a template you own. Only include the fields you want to change. Updating html re-detects variables and increments the version number.

curl -X PUT https://pixdoc.dev/api/v1/templates/550e8400-e29b-41d4-a716-446655440000 \
-H "Authorization: Bearer pd_live_a3b2c4d5..." \
-H "Content-Type: application/json" \
-d '{
  "html": "<div style=\"padding:40px;\"><h1>{{title}}</h1><h2>{{subtitle}}</h2><p>By {{author}}</p></div>",
  "defaults": { "subtitle": "" }
}'

Delete Template

DELETE /api/v1/templates/{id}

Deletes a template you own. Public templates cannot be deleted. Returns 403 if you attempt to delete a public template.

Using Templates with the PDF Endpoint

Pass template_id instead of html to the PDF render endpoint, along with a variables object containing your variable values:

curl -X POST https://pixdoc.dev/api/v1/pdf \
-H "Authorization: Bearer pd_live_a3b2c4d5..." \
-H "Content-Type: application/json" \
-d '{
  "template_id": "550e8400-e29b-41d4-a716-446655440000",
  "variables": {
    "title": "Q1 2026 Report",
    "author": "Jane Doe",
    "summary": "Revenue grew 45% quarter over quarter."
  }
}' \
--output report.pdf