Skip to main content

Template API

The Template API provides REST endpoints for managing reusable PDF templates from internal tools, CI workflows, or AI coding agents without opening the Dashboard Designer.

The Template API and Conversion API use different credentials: use a Personal Access Token to manage templates and a Conversion API key to generate PDFs from published templates.

APIAuthentication headerPurpose
Conversion APIAPI-KEYGenerate PDFs from HTML, URLs, or published templates.
Template APIPERSONAL-ACCESS-TOKENCreate, list, retrieve, update, validate, preview, compare, and publish templates.

Base URL​

Send Template API requests to:

https://api.pdfbolt.com/v1/templates

Authentication​

All Template API endpoints except GET /v1/templates/contract require a Personal Access Token. Create one on the API Credentials page in the Dashboard, under Personal Access Tokens.

Send the token in the PERSONAL-ACCESS-TOKEN header with every protected request:

PERSONAL-ACCESS-TOKEN: <YOUR_PERSONAL_ACCESS_TOKEN>

Each Personal Access Token belongs to the user who created it, not to a team. Requests authenticate as that user and can access the same templates the user sees in the Dashboard. In a shared team, this can include templates created by other members.

Keep your token secure

Anyone with the token can access, modify, and publish your templates. Deactivate it immediately if it may have been compromised.

Personal Access Tokens cannot be restricted to specific templates or operations and do not expire automatically. Preview and diff requests consume conversion credits.

Store tokens in an environment variable or secret manager. Never expose them in client-side code, logs, or source control.

You can have up to five Personal Access Tokens. Deactivation takes effect immediately. Blocked tokens cannot be used or reactivated in the Dashboard, but they still count toward the limit. Contact support to restore access.

How the Template API works​

You can complete the full template creation and publishing workflow through the Template API without opening the Dashboard Designer. Start with GET /v1/templates/contract to retrieve the current template rules and supported fields.

Create and publish a template:

  1. Prepare the template. Create the HTML, add representative sample data, and configure the PDF parameters.
  2. Validate the template. Check the payload and template syntax before using credits to render a PDF.
  3. Preview and review. Render the candidate as a PDF and inspect the visual result. Revise and repeat until it is ready.
  4. Save the draft. Store the reviewed template without changing the version used for production conversions.
  5. Publish the draft. Make it the active version used by the Conversion API.
  6. Generate production PDFs. Send the templateId and document-specific templateData to the Conversion API.

When updating a published template, use diff during the preview step to compare the candidate with the current production version.

Endpoints overview​

The following endpoints cover the complete template management lifecycle:

MethodEndpointPurpose
GET/v1/templates/contractReturn the versioned Template Contract.
GET/v1/templatesList the current team's templates.
GET/v1/templates/{templateId}Return template details, including content, sample data, and PDF parameters.
POST/v1/templates/validateValidate a template payload without rendering a PDF.
POST/v1/templates/previewRender a candidate template as PDF or JSON.
POST/v1/templates/{templateId}/diffCompare a candidate payload with the published version.
POST/v1/templates/draftsCreate or update a template draft.
POST/v1/templates/{templateId}/publishPublish the active draft.

Request fields​

Template API request bodies use the fields below. Each endpoint accepts a different subset. See the endpoint reference for the exact request shape.

FieldTypeDescription
templateIdstring (UUID)Identifies an existing template when saving a draft. Omit it to create a new template and its first draft.
namestringTemplate name. Required when creating a new template and optional when updating one. Maximum length: 100 characters.
descriptionstringOptional template description. Maximum length: 500 characters.
templateEnginestringTemplate syntax. Currently only HANDLEBARS is supported. Required for validate, preview, and new template creation, but optional for diff and draft updates.
contentstringComplete Base64-encoded UTF-8 HTML document, including any CSS. Required for validate, preview, diff, and new template creation. Optional when updating an existing template; a supplied value replaces the complete stored document. Maximum decoded size: 2 MB.
sampleDataobjectRepresentative JSON data used to evaluate the template. Required for validate, preview, diff, and new template creation. Optional when updating an existing template; a supplied object replaces the complete stored object. Maximum JSON size: 2 MB.
parametersobjectDefault PDF parameters saved with a template version. Required for validate, preview, and diff. Optional for template creation and existing-template updates; updates apply it as a shallow patch. Maximum JSON size: 2 MB.
commentstringOptional publish comment. Maximum length: 500 characters.

Template parameters​

The parameters object contains the PDF parameters saved with a template version. When creating a new template, you can omit parameters, send an empty object ({}), or provide only selected fields. PDFBolt fills in the missing fields using the defaults shown below and saves the resulting parameters with the template version.

When generating PDFs from the published template, the saved parameters are applied automatically. To change them for a specific PDF, send conversion parameters alongside templateId and templateData. They override the saved parameters for that request only and are not saved to the template.

When validating, previewing, or comparing a candidate, use the same parameters fields. The Template API accepts the fields and values below:

FieldAccepted valuesNew template default
formatLetter, Legal, Tabloid, Ledger, A0–A6Letter
landscapetrue or falsefalse
waitUntilload, domcontentloaded, networkidle, or commitload
printBackgroundtrue or falsetrue
displayHeaderFootertrue or falsefalse
headerTemplateBase64-encoded HTML stringNot set
footerTemplateBase64-encoded HTML stringNot set
waitForFunctionJavaScript functionSee the default below
Default waitForFunction

When waitForFunction is omitted while creating a new template, PDFBolt saves this function:

// wait for all fonts and images to be loaded, if loading fails, try waitUntil networkidle
() => { return document.readyState === 'complete' && document.fonts.status === 'loaded' && Array.from(document.images).every(img => img.complete); }

When updating an existing template, parameters is an optional shallow patch. PDFBolt starts with the active draft's parameters, or the published version's parameters when no draft exists. Omitted fields and {} preserve existing values. Set headerTemplate, footerTemplate, or waitForFunction to null to remove that optional value. Every other parameter requires a concrete value.

Endpoint reference​

Get Template Contract​

Returns the current version of the Template Contract for programmatic template management. It covers authentication, payload fields, HTML/CSS and Handlebars guidance, defaults, workflows, limits, and technical errors. No authentication is required.

Method: GET

https://api.pdfbolt.com/v1/templates/contract

Success Example​

curl 'https://api.pdfbolt.com/v1/templates/contract'

Template Contract and OpenAPI​

GET /v1/templates/contract provides PDFBolt-specific rules for creating, rendering, reviewing, and publishing templates.

OpenAPI YAML defines the exact endpoints, required fields, response schemas, and status codes. Use both when building a Template API integration.

List Templates​

Returns the current team's templates with details about their published and draft versions. Templates are ordered by the latest version update, newest first.

Method: GET

https://api.pdfbolt.com/v1/templates

Success Example​

curl 'https://api.pdfbolt.com/v1/templates' \
  -H 'PERSONAL-ACCESS-TOKEN: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'

Get Template Details​

Returns the template details, including its content, sample data, PDF parameters, active draft, and latest published version. If a draft exists, the content, sample data, and PDF parameters come from it. Otherwise, they come from the published version.

Method: GET

https://api.pdfbolt.com/v1/templates/{templateId}

Success Example​

curl 'https://api.pdfbolt.com/v1/templates/2b1124e7-7f8d-4fd9-9d0a-4f8cf0c58f98' \
  -H 'PERSONAL-ACCESS-TOKEN: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'

Validate Template Payload​

Validates a template payload without saving it or rendering a PDF. It checks required fields, Base64 content, payload size limits, the template engine, Handlebars syntax and evaluation, and supported PDF parameters. Use it before previewing or saving a draft.

Method: POST

https://api.pdfbolt.com/v1/templates/validate
  • Required body fields: templateEngine, content, sampleData, parameters
  • Optional body fields: None

Success Example​

{
  "templateEngine": "HANDLEBARS",
  "content": "PCFkb2N0eXBlIGh0bWw+PGh0bWw+PGJvZHk+PGgxPkludm9pY2Uge3tpbnZvaWNlTnVtYmVyfX08L2gxPjwvYm9keT48L2h0bWw+",
  "sampleData": {"invoiceNumber": "INV-1001"},
  "parameters": {
    "format": "A4",
    "waitUntil": "networkidle",
    "printBackground": true
  }
}

Preview Template Payload​

Renders a candidate template payload as a PDF without saving it. Set responseFormat=json to receive the PDF as Base64 together with its size. Each successful preview consumes conversion credits.

Method: POST

https://api.pdfbolt.com/v1/templates/preview
  • Required body fields: templateEngine, content, sampleData, parameters
  • Optional body fields: None
responseFormatReturns
pdf (default)PDF file (application/pdf)
jsonJSON with the PDF encoded as Base64 and its size in MB

Success Example​

{
  "templateEngine": "HANDLEBARS",
  "content": "PCFkb2N0eXBlIGh0bWw+PGh0bWw+PGJvZHk+PGgxPkludm9pY2Uge3tpbnZvaWNlTnVtYmVyfX08L2gxPjwvYm9keT48L2h0bWw+",
  "sampleData": {"invoiceNumber": "INV-1001"},
  "parameters": {"format": "A4", "waitUntil": "networkidle", "printBackground": true}
}

Compare a candidate with the published version​

The template must already have a published version. This endpoint renders it as before and the candidate payload as after for visual comparison. Conversion credits are charged separately for each PDF that renders successfully.

Method: POST

https://api.pdfbolt.com/v1/templates/{templateId}/diff
  • Required body fields: content, sampleData, parameters
  • Optional body fields: templateEngine

Success Example​

{
  "content": "PCFkb2N0eXBlIGh0bWw+PGh0bWw+PGJvZHk+PGgxPkludm9pY2Uge3tpbnZvaWNlTnVtYmVyfX08L2gxPjxwPnt7Y3VzdG9tZXJOYW1lfX08L3A+PC9ib2R5PjwvaHRtbD4=",
  "sampleData": {"invoiceNumber": "INV-1001", "customerName": "Acme Inc."},
  "parameters": {"format": "A4", "waitUntil": "networkidle", "printBackground": true}
}

Create or update a template draft​

Creates a new template and its first draft when templateId is omitted. When templateId is provided, the endpoint updates only the supplied fields, using the active draft as the base or the published version when no draft exists. The resulting payload is validated without rendering a PDF or consuming conversion credits.

Method: POST

https://api.pdfbolt.com/v1/templates/drafts

Create Draft​

Omit templateId to create a new template and its first draft. If parameters is omitted or contains only some fields, PDFBolt fills in the remaining values using the Dashboard Designer defaults.

  • Required body fields: name, templateEngine, content, sampleData
  • Optional body fields: description, parameters
{
  "name": "Invoice",
  "description": "Monthly invoice template",
  "templateEngine": "HANDLEBARS",
  "content": "PCFkb2N0eXBlIGh0bWw+PGh0bWw+PGJvZHk+PGgxPkludm9pY2Uge3tpbnZvaWNlTnVtYmVyfX08L2gxPjwvYm9keT48L2h0bWw+",
  "sampleData": {"invoiceNumber": "INV-1001"},
  "parameters": {"format": "A4", "waitUntil": "networkidle", "printBackground": true}
}

Update Draft​

Include templateId and at least one field to update. PDFBolt starts from the active draft, or from the published version when no active draft exists:

  • Omitted top-level fields preserve their current values.
  • Supplied content replaces the complete HTML document.
  • Supplied sampleData replaces the complete JSON object; it is not deep-merged.
  • Supplied parameters is a shallow patch. Omitted parameter fields and {} preserve their current values.
  • null removes headerTemplate, footerTemplate, or waitForFunction. Other parameter fields require concrete values.
  • description: "" clears the description.

If an active draft exists, it is updated in place and keeps its draftVersionId and versionNumber. If the template has a published version but no active draft, PDFBolt creates a new draft with the next version number.

  • Required body fields: templateId and at least one field to update
  • Updatable fields: name, description, templateEngine, content, sampleData, parameters

Validate, preview, and diff requests remain complete candidate payloads. Partial-update behavior applies only to saving an existing template draft.

{
  "templateId": "93fee603-cb2a-40db-8deb-b2e3cb1eed0f",
  "parameters": {"format": "A4"}
}

Publish a template draft​

Publishes the active draft as the template's latest published version. Use the published template for PDF conversions by sending its templateId and templateData to a Conversion API endpoint.

A JSON request body is required. Send {} to publish without a comment. If the template has no active draft, the API returns 400 BAD_REQUEST.

Method: POST

https://api.pdfbolt.com/v1/templates/{templateId}/publish
  • Required body fields: None (a JSON body is still required and may be empty)
  • Optional body fields: comment (maximum 500 characters)

Success Example​

{
  "comment": "Ready for production"
}

Generate PDFs from a published template​

Send the published templateId to /v1/direct, /v1/sync, or /v1/async. Pass dynamic values in templateData and authenticate with an API-KEY.

The Conversion API uses the latest published version, even when a newer draft exists. You can add conversion parameters to override the template defaults for one PDF. These overrides are not saved to the template.

Use the published template ID and template data to generate a PDF:

{
  "templateId": "93fee603-cb2a-40db-8deb-b2e3cb1eed0f",
  "templateData": {
    "invoiceNumber": "INV-1001",
    "customerName": "Acme Inc."
  }
}

See the OpenAPI YAML for the complete request schemas.

Billing and Rate Limits​

Within the Template API, only the preview and diff endpoints render PDFs and consume conversion credits. They use the team's plan-based Conversion API limits and appear in Dashboard logs and usage as Preview Conversions. All other Template API operations do not consume conversion credits.

List, get, validate, save draft, and publish use separate fixed per-user management limits. Their 429 responses include Retry‑After. Preview and diff follow the Conversion API retry behavior, while the public contract endpoint is exempt from rate limiting.

See Rate Limits for current limits, response headers, and retry guidance.

Error Handling​

Template API request failures use the standard PDFBolt JSON error response:

{
  "timestamp": "2026-07-13T12:00:00Z",
  "httpErrorCode": 400,
  "errorCode": "BAD_REQUEST",
  "errorMessage": "Template validation failed: Field 'content' is required. Send a Base64-encoded UTF-8 HTML document as a string."
}

Read errorMessage for the specific cause. See Error Handling for shared error codes and retry guidance, and the OpenAPI YAML for the exact responses supported by each endpoint.

Request-level failures return non-2xx responses for all Template API endpoints. Preview also returns PDF rendering failures as non-2xx responses. Diff behaves differently: after request validation succeeds, it returns HTTP 200 even if one or both PDFs fail to render. Inspect before.error and after.error before treating the comparison as successful.

Next Steps​