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 Template Designer.

Base URL​

Send Template API requests to:

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

Authentication​

Except for public GET and HEAD requests to /v1/templates/contract, Template API requests require a Personal Access Token. Create one in the Personal Access Tokens section of the API Credentials page in the Dashboard.

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

PERSONAL-ACCESS-TOKEN: <YOUR_PERSONAL_ACCESS_TOKEN>

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

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

Personal Access Tokens cannot be restricted to specific templates or operations and do not expire automatically. You can have up to five tokens, including deactivated tokens. Deactivation takes effect immediately and cannot be undone in the Dashboard.

How the Template API Works​

Use this workflow to create and publish a template, then generate PDFs through the Conversion API:

  1. Retrieve the contract. Call GET /v1/templates/contract to get the current template rules and supported fields.
  2. Prepare the template. Create a complete HTML document with any Handlebars placeholders and Base64-encode it.
  3. Validate the template. Check the payload and template syntax without rendering a PDF.
  4. Preview and review. Render the template as a PDF and visually inspect every page. Revise and repeat until it is ready.
  5. Save the draft. Store the reviewed template without changing the published version used by the Conversion API.
  6. Verify the draft. Retrieve the template and confirm that the intended values were saved.
  7. Publish the draft. Make it the version used by the Conversion API.
  8. Generate PDFs. Send the templateId and document-specific templateData to the Conversion API.

Endpoints Overview​

The Template API provides the following endpoints:

MethodEndpointPurpose
GET/v1/templates/contractRetrieve the versioned Template Contract.
HEAD/v1/templates/contractCheck the public Template Contract endpoint without returning a response body.
GET/v1/templatesList the current team's templates.
GET/v1/templates/{templateId}Retrieve 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 template preview and return a raw PDF or JSON response.
POST/v1/templates/{templateId}/diffCompare proposed template changes 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)Existing template UUID used for draft updates. Omit it to create a template.
namestringNon-blank template name. Required for creation. Maximum length: 100 characters.
descriptionstringOptional template description. Maximum length: 500 characters.
templateEnginestringTemplate engine. Currently only HANDLEBARS is supported.
contentstringComplete Base64-encoded UTF-8 HTML document, including CSS and any Handlebars placeholders. When supplied in an update, it replaces the stored document. Maximum decoded size: 2 MB.
sampleDataobjectRepresentative JSON data used to evaluate the template. When supplied in an update, it replaces the stored object. Maximum JSON size: 2 MB.
parametersobjectPDF parameters used to validate, render, or save a template. Draft updates apply supplied fields 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.

Use the same fields when validating, previewing, comparing, or saving a template:

FieldTypeAccepted valuesNew template default
formatstringLetter, Legal, Tabloid, Ledger, A0–A6Letter
landscapebooleantrue or falsefalse
waitUntilstringload, domcontentloaded, networkidle, or commitload
printBackgroundbooleantrue or falsetrue
displayHeaderFooterbooleantrue or falsefalse
headerTemplatestring | nullBase64-encoded HTMLNot set
footerTemplatestring | nullBase64-encoded HTMLNot set
waitForFunctionstring | nullJavaScript functionSee the default below

Only these eight parameters can be saved with a template version. Other Conversion API parameters can be sent when generating a PDF, but they apply only to that conversion.

Default waitForFunction

When waitForFunction is omitted during template creation, 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); }

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 for GET or HEAD. Use HEAD to check the endpoint status and response headers without returning a response body.

Methods: GET, HEAD

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 published and draft version details, excluding deleted templates. Results are ordered by the latest version update, newest first, and are not paginated.

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's content, sample data, PDF parameters, and metadata for its active draft and latest published version. If an active draft exists, the content, sample data, and PDF parameters come from it. Otherwise, they come from the latest 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.

A Handlebars placeholder does not need a matching value in sampleData to pass validation. If the value is missing, the placeholder produces no output.

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 template payload as a PDF without saving it. Use ?responseFormat=json to receive the PDF as Base64 with its size in MB. Each successful preview render counts toward your available document conversions.

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 Proposed Changes with the Published Version​

The template must have a published version. The endpoint renders the published version as before and the supplied template payload as after for visual comparison without saving the changes.

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, or saves changes to an existing template when templateId is provided. Every save validates the complete draft, including preserved fields, without rendering a PDF or consuming conversion credits.

Make one change at a time to a template. Wait for each save or publish request to finish before making another change through the Template API or Dashboard Template Designer. Concurrent changes, including changes made by another user, may overwrite one another.

Method: POST

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

Create a New Template​

Omit templateId to create a new template and its first draft. If you omit parameters or provide only some fields, PDFBolt fills in the rest using the template defaults.

An omitted or null description is saved as an empty string.

  • 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 an Existing Template​

Include templateId and at least one field to update. PDFBolt uses the active draft as the base, or the published version if no active draft exists:

  • Omitted top-level fields (name, description, templateEngine, content, sampleData, and parameters) preserve their current values.
  • Supplied content replaces the complete HTML document.
  • Supplied sampleData replaces the complete JSON object. It is not deep-merged.
  • The parameters object is applied as a shallow patch. Include only the fields you want to update. Omitted fields are preserved. An empty parameters object does not change any parameters and does not count as an update.
  • Within parameters, set headerTemplate, footerTemplate, or waitForFunction to null to remove the saved value. To update format, landscape, waitUntil, printBackground, or displayHeaderFooter, provide a concrete value.
  • description: "" clears the description.
  • Explicit null is rejected for every top-level update field.

PDFBolt updates an active draft in place, preserving its draftVersionId and versionNumber. If only a published version exists, it creates the next draft version from it.

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

Partial updates are supported only when saving a draft for an existing template. Validate, preview, and diff still require complete template payloads.

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

Publish a Template Draft​

Publishes the template's active draft.

A JSON object is required. Send {} to publish without a comment.

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​

To generate PDFs, send the template's templateId and document-specific templateData to /v1/direct, /v1/sync, or /v1/async. Authenticate with an API-KEY.

The Conversion API always uses the latest published version, even if a newer draft exists. Add conversion parameters to override the saved template defaults for that request. The overrides are not saved to the template.

{
  "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​

Each successful preview render counts toward your available document conversions. For a diff, each successfully rendered side counts separately. These renders use the team's plan-based Conversion API limits and appear in Dashboard logs and usage as Preview Conversions. Other Template API operations do not count toward document conversions.

Listing, retrieving, validating, saving, and publishing templates use separate fixed per-user management limits. Their 429 responses include Retry-After. Preview and diff follow the Conversion API retry behavior. Public GET and HEAD requests to /v1/templates/contract are not rate limited.

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

Error Handling​

Application-level Template API errors use the standard PDFBolt JSON response format:

{
  "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 responses documented for each endpoint.

Request-level failures return non-2xx responses. Preview rendering failures also return non-2xx responses. Diff rendering failures are returned differently: after request validation succeeds, the endpoint returns HTTP 200 even if one or both renders fail. Check before.error and after.error before treating the comparison as successful.

Next Steps​