Templates and versions

A template is stored HTML with Liquid placeholders, plus optional CSS, sample data and page settings. Once it exists, your application sends only a template_id and the data for each document.

What a template holds

Create templates in the dashboard, whose editor has tabs for HTML, CSS, sample data and page settings and a live preview, or with POST /v1/templates. Both save to the same place.

The HTML is checked when you save: a Liquid syntax error or an unknown filter is rejected with template_render_error, whose details give the line and column.

Rendering with a template

curl https://api.castpdf.com/v1/pdf \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"template_id": "8d1f2c3b-4a5e-4f60-9b7a-1c2d3e4f5a6b", "data": {"number": "INV-042", "total": 1234.5}}' \
  --output invoice.pdf

• data is the template's Liquid data. Without it, the version's sample_data is used.
• The template's own CSS is used. A request that also sends css is rejected with invalid_request; to change the styling, edit the template's CSS.
• Templates render in print mode unless the template's settings or the request say otherwise.
• Page options in the request (mode, format, orientation, margins) override the template's settings for that document.

Versions

Every save that changes the HTML, CSS, sample data or settings creates a new version, numbered 1, 2, 3 and so on. Versions are never edited in place, so a document can always be traced to the exact version that produced it: template_version in GET /v1/pdf/:id.

• Renaming a template creates no version.
• An update sends only the fields that change; the others are copied from the current version. The settings object is replaced as a whole.
• The latest 50 versions are kept, plus the pinned version; older ones are deleted. GET /v1/templates/:id/versions lists the ones that exist.

Which version renders

A render, or a preview, uses the first of these that applies:

1. the template_version in the request (version for a preview);
2. the pinned version;
3. the current (latest) version.

A version that no longer exists is template_not_found.

Pinning

Pinning lets you keep editing a template without changing what production renders:

1. Pin the version production should use: POST /v1/templates/:id/pin with "version": 3, or Pin in the dashboard's versions menu.
2. Edit and save as often as you like. New versions (4, 5, …) do not affect renders that send only template_id.
3. Preview the new version with real data, then pin it. Or unpin with "version": null, so renders follow the latest version again.

curl https://api.castpdf.com/v1/templates/8d1f2c3b-4a5e-4f60-9b7a-1c2d3e4f5a6b/pin \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"version": 5}'

Previews

POST /v1/templates/:id/preview renders a version with your data (or its sample data) and returns the PDF:

curl https://api.castpdf.com/v1/templates/8d1f2c3b-4a5e-4f60-9b7a-1c2d3e4f5a6b/preview \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"version": 5, "data": {"number": "INV-042", "total": 1234.5}}' \
  --output preview.pdf

Previews always carry the "CASTPDF TEST" watermark, never count towards your plan, are not stored and are not listed in the document log, whichever key you use. They are limited to 30 per minute per team and key mode. The dashboard editor's live preview works the same way, re-rendering as you type.

Page settings

A template's settings set its page defaults. Each one can be overridden per document in POST /v1/pdf.

The setting is called margin in a template and margins in POST /v1/pdf.

An @page size or margin in your CSS wins over the template settings. Remove it from your CSS if you want the settings (or the API's format and margins) to apply. The starter templates set their page in their settings only. See the print CSS guide.

Deleting

DELETE /v1/templates/:id deletes a template. Renders that use its id then fail with template_not_found. Documents generated earlier stay available until their retention ends.