Drafts, publishing and versions

Saving is not publishing

Saving updates the template draft you are working on. Publishing selects a version for production. A template can have a published version while you work on a newer draft; do not assume draft changes are already published.

Before publishing

Preview with both sample data and realistic long data, and check the required output formats. Compare the active and published versions in History. Publish when the content you want to use in production is ready.

Restoring from history

Restoring a historical version saves that content as a new active version; it does not erase older history. Check the content again after restoring. Publish separately if you also want to replace the published version.

Reading, restoring and publishing a version

Every manual save opens a new version and nothing is ever overwritten. Restoring an older version does not delete the newer ones - it writes the old definition as a new version, so the history stays complete.

# Version list - newest first
curl -s https://api.pdfgine.com/api/v1/templates/invoice/history \
  -H "X-PDFgine-Key: $PDFGINE_KEY"

# The definition of one version
curl -s https://api.pdfgine.com/api/v1/templates/invoice/history/3 \
  -H "X-PDFgine-Key: $PDFGINE_KEY"

# Go back to that version - written as a new version, the old one is kept
curl -X POST https://api.pdfgine.com/api/v1/templates/invoice/history/3/restore \
  -H "X-PDFgine-Key: $PDFGINE_KEY"

# Publish the draft
curl -X POST https://api.pdfgine.com/api/v1/templates/invoice/publish \
  -H "X-PDFgine-Key: $PDFGINE_KEY"

{
  "type": "https://pdfgine.dev/problems/template-conflict",
  "title": "Template conflict",
  "status": 409,
  "detail": "The template was changed by another operation. Load the current version and try again.",
  "templateCode": "invoice",
  "currentVersion": 19,
  "currentDraftRevision": 0
}

A write that carries a stale expectedVersion is refused rather than merged. The 409 body names the template and its current version and draft revision - read the current definition, reapply your change and write again.

Conflicts and connection codes

Saving from an outdated version can conflict if another session has changed the same template. Review the current state and history instead of blindly overwriting changes. The connection code identifies the template in API requests. If it changes, update integrations that use that code too.

What usually goes wrong

• Saving is not publishing. A draft can be perfect for days while production keeps printing the last published version.
• Restoring does not delete anything. It writes the old definition as a new version, so the history stays and the version number keeps climbing.
• A 409 repeated with the same expectedVersion is refused again. Read the current version, apply your change on top of it, then write.
• A render with purpose editor-test uses the draft, production uses the published version. Two renders that look identical can come from two different designs.
• The history endpoint is paged. Without limit you get the most recent page and a Link header; treating that page as the whole history hides the older revisions.