API Reference

Authentication

All API requests require a bearer token. Create and manage API keys from Developer tools → API keys (/developers/api-keys) in your dashboard. Keys are shown once on creation — store them securely.

The primary public REST API is versioned under /v2/organizations/:organizationId/* and accepts API keys only. API keys are organization-scoped, and the organization in the URL must match the key. The legacy /v1/* API remains supported.

Key format

Keys are prefixed with prs_ and scoped to your organization.

curl https://api.pdfs.build/v2/organizations/org_abc/templates \
  -H "Authorization: Bearer prs_your_api_key"

Create template

Creates a draft template owned by the user that minted the API key. A draft is not rendered until it is published, except as "version": "draft" on a plan with no published-template limit (see Render PDF). Template source is normalized through the same publishing pipeline used by the app and should define a top-level #let render(...) = { ... } function whose named parameters match the schema fields.

Request body

Returns 201 with both the immutable generated internalId and your externalId. V2 URLs use the external ID; v1 continues to use the internal ID.

External IDs are case-sensitive, 1–128 characters, and may contain ASCII letters, digits, ., _, ~, and -. The values . and .. are reserved. IDs remain reserved after a template is deleted.

Publish template

Promotes a draft template to published so it becomes visible to your organization and callable via the render endpoint. The caller must own the template or be an organization admin/owner. Enforces your plan's published-template limit. Publishing a template that is already published ships its current draft as a new version, so edits made since (for example in the embedded editor) reach renders; with no edits since, nothing changes. To test changes before they reach production, see how to test template changes before they reach production, or Promote from CI to do it from a pipeline.

Request body (optional)

Returns the updated template detail. Returns 402 template_limit_reached if the org's plan does not allow another published template, and 409 publish_conflict if the template changed while it was being checked: nothing was published, and publishing again checks the current version.

Unpublish template

Moves a published template back to draft. Once unpublished, it is removed from organization template listings, and a render of it answers 403 draft_not_renderable whatever version it names, except "draft" on a plan with no published-template limit (see Render PDF). A caller that sends "draft" keeps rendering it there: to stop that too, change what it sends or revoke its API key. Existing render log entries are preserved.

Returns the updated template detail.

Render PDF

Compiles the specified template with the provided data payload and returns a binary PDF. Data is validated against the template's schema before rendering.

Request body

Versions

Publishing freezes a template into an immutable version and points the latest channel at it. Later edits stay in the draft until you promote them, so production keeps rendering the same document (and the same schema) while you iterate. To look at the draft as it is, render it with "version": "draft". To test it as it will ship, freeze it as a new version and render that number or a channel such as staging, then promote it and every caller that omits version picks it up. Promoting an older version back is an instant rollback. A publish answers with publishedVersion, the version latest now serves: publishing again with nothing changed freezes no new version and answers with the same number, so pin that rather than counting publishes. Promote from CI does all of this from a pipeline with an API key. For the same steps in the app, see how to test template changes before they reach production.

Response

Returns Content-Type: application/pdf on success, with two headers that say what was rendered: X-Template-Version, the frozen version (absent when the draft was rendered), and X-Template-Channel, the channel the request went through (latest when version was omitted, staging, or draft; absent when you sent a version number). Both are exposed to browsers through CORS. On error, returns JSON with an error object.

const response = await fetch(
  'https://api.pdfs.build/v2/organizations/org_abc/templates/invoice-primary/render',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      data: {
        company: 'Acme Corp',
        items: [
          { name: 'Consulting', qty: 3, price: 150 },
        ],
        due_date: '2025-06-01',
      }
    }),
  }
);

const pdf = await response.arrayBuffer();

import requests

response = requests.post(
    "https://api.pdfs.build/v2/organizations/org_abc/templates/invoice-primary/render",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "data": {
            "company": "Acme Corp",
            "items": [
                {"name": "Consulting", "qty": 3, "price": 150}
            ],
            "due_date": "2025-06-01",
        }
    },
)

with open("output.pdf", "wb") as f:
    f.write(response.content)

curl -X POST \
  "https://api.pdfs.build/v2/organizations/org_abc/templates/invoice-primary/render" \
  -H "Authorization: Bearer prs_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"data": {"company": "Acme Corp", "due_date": "2025-06-01"}}' \
  --output output.pdf

Async renders

Add "async": true to the render request body to render in the background instead of waiting for the PDF. The API answers 202 Accepted immediately with a job handle; you then wait for the render.completed webhook or poll the job status. Omitting async (or sending false) keeps the synchronous behavior unchanged, and async renders count toward the same monthly quota as synchronous renders. The version is resolved when you submit, as for a batch: one that does not exist is refused with 400 before anything is queued, and a channel such as latest is held to the version it pointed at then. "draft" is not held: the job reads the draft when it runs.

Request body

Response

Returns 202 Accepted with the job handle. The quota admission check happens at enqueue; finalization happens when the job completes.

{
  "id": "job_7a1b...",
  "status": "queued",
  "statusUrl": "https://api.pdfs.build/v2/organizations/org_abc/renders/job_7a1b..."
}

Polling for the result

{
  "id": "job_7a1b...",
  "status": "success",
  "templateExternalId": "invoice-primary",
  "durationMs": 123,
  "downloadUrl": "https://api.pdfs.build/v2/organizations/org_abc/renders/job_7a1b.../pdf",
  "createdAt": "2026-08-30T12:00:00Z",
  "completedAt": "2026-08-30T12:00:01Z"
}

The downloadUrl requires the same API key (Authorization: Bearer prs_...). The legacy POST /v1/render route remains sync-only.

Batch renders

Render up to 500 documents from one template in a single request. Every item becomes an async render job, all against the same template version: the version is resolved when you submit, so promoting a channel mid-batch does not mix versions. The exception is a batch that renders the live draft ("version": "draft", a template with nothing promoted yet, or a legacy auto-publish template): the draft is not pinned, so edits made mid-batch can reach later items. As for a single render, a batch for a template that is not published is refused with 403 draft_not_renderable, unless it asks for "draft" on a plan with no published-template limit (see Render PDF). Items send no per-render webhooks; one batch.completed event goes out when every item has succeeded or failed (webhooks need a paid plan).

Request body

Response

Returns 202 Accepted with id, status, total and statusUrl. The whole batch is admitted against your monthly quota at once: if it does not fit, the request fails with 429 and nothing is queued. Only successful items are charged. More than 500 items returns 422 invalid_batch_size; the body may be up to 10 MB.

Polling for the result

GET /v2/organizations/:organizationId/batches/:batchId returns the batch's status (processing or completed), succeeded, failed and pending counts, and every item in submission order as { index, jobId, status, downloadUrl?, error? }. Each downloadUrl is that item's render job PDF route and needs the same API key.

List templates

Returns published templates in the API key's organization. Drafts created by the key owner remain available through the single-template endpoint.

[
  {
    "internalId": "550e8400-e29b-41d4-a716-446655440000",
    "externalId": "invoice-primary",
    "name": "Invoice v3",
    "description": "Standard invoice with line items",
    "status": "published",
    "createdAt": "2025-03-12T10:24:00Z",
    "updatedAt": "2025-04-01T08:15:00Z"
  }
]

Get template

Returns a single template's metadata, schema definition, sample data, and schemaLocked state. Use the schema field to know which keys your data payload must include when rendering.

{
  "internalId": "550e8400-e29b-41d4-a716-446655440000",
  "externalId": "invoice-primary",
  "name": "Invoice v3",
  "status": "published",
  "schemaLocked": true,
  "schema": {
    "type": "object",
    "properties": {
      "company": { "type": "string" },
      "due_date": { "type": "string", "format": "date" },
      "items": { "type": "array" }
    }
  },
  "sampleData": { /* ... */ }
}

Rename external ID

Send {"externalId":"invoice-primary"}. The old v2 URL stops resolving immediately; the internal ID, v1 URL, and historical render-log foreign keys do not change. Requires template ownership or organization admin access.

Render logs

Returns a paginated list of PDF render events for your organization. Each log exposes templateInternalId and the templateExternalId captured when that render occurred, so later renames do not rewrite audit history. Use GET /v2/organizations/:organizationId/logs/:logId for detail or GET /v2/organizations/:organizationId/templates/:externalId/logs for one template.

Query parameters

Webhooks

Outbound webhooks notify your systems when API renders complete or fail — both synchronous renders and async render jobs. UI, MCP, and other in-app renders do not emit webhook events. Webhooks are available on every paid plan.

Register endpoints from Developers → Webhooks in the dashboard, over MCP (create_webhook and friends), or through the v2 API directly — all three surfaces manage the same endpoints with the same plan gating. An organization can register multiple endpoints, and every enabled endpoint receives every render event. To restrict a single render's events to specific endpoints, pass their ids in the optional webhookIds field on the render endpoint — ids must reference existing, enabled endpoints of the same organization, and unknown ids return 422. Webhook delivery never affects render responses.

Managing endpoints via the API

Create, rotate-secret, and test require a paid plan; list, update, delete, and deliveries stay open. Endpoint URLs must be public http(s) destinations — non-global addresses (loopback, private, link-local, CGNAT, and other reserved ranges) are rejected with 400 url_not_allowed at registration and re-validated before every delivery.

Events

Payload

{
  "id": "evt_9f2c...",
  "type": "render.completed",
  "createdAt": "2026-08-30T12:00:00Z",
  "data": {
    "renderId": "d4e5...",
    "jobId": "job_7a1b...",
    "organizationId": "org_...",
    "templateExternalId": "invoice-primary",
    "status": "success",
    "durationMs": 123,
    "errorMessage": null,
    "downloadUrl": "https://api.pdfs.build/v2/organizations/org_.../renders/job_7a1b.../pdf"
  }
}

id is unique per delivery — use it for consumer-side idempotency. jobId and downloadUrl are present for async renders only; the download URL requires the same API key. render.failed events set status: "error" and errorMessage.

Verifying signatures

Each delivery is signed with the endpoint secret using the Standard Webhooks scheme, so you can verify it with any svix-compatible library. The signing secret (whsec_...) is shown once when the endpoint is created.

Acknowledgement and retries

Respond with any 2xx within 5 seconds; anything else — including timeouts — counts as a failed attempt and is retried with capped exponential backoff: up to 10 attempts, min(60, 2^attempts) minutes between attempts. A delivery is marked failed after the 10th attempt. You can inspect recent deliveries and send test events from the dashboard.

Promote from CI

If your templates live in a repository, a CI job can take each change to production with an API key and test it on the way: push the Typst to the template's draft, freeze the draft as a version, point dev and then staging at it, render staging, and promote it. Production keeps serving the version it has until the last step, and a change that would break production's callers stops there unless the job says otherwise.

Before the first run, publish the template once: that freezes v1 and points latest, which is production, at it. On a plan with no published-template limit, a new template's draft can be rendered before then with "version": "draft". A template from before versions may still publish its edits as they are saved: if GET …/draft answers "autoPublishEdits": true, turn on Freeze production in its Versions tab first, or step 1 changes production at once and step 5 is refused with 409 auto_publish_enabled. The API key's creator must own the template or be an owner or admin of the organization, or the calls that change it answer 403 forbidden.

The examples use curl and jq, a template with the external ID invoice-primary, and two variables:

API="https://api.pdfs.build/v2/organizations/$PDFS_ORG_ID/templates/invoice-primary"
AUTH="Authorization: Bearer $PDFS_API_KEY"

--fail-with-body makes curl print an error answer and exit with an error, so with set -e (a GitHub Actions run step has it) a refused step stops the job and says why. Set API and AUTH in every run step, and run steps 3 and 4 in one, since step 4 reads the VERSION step 3 sets. Steps 1 and 2 run in the job of the branch every change lands on first, main say. The later steps can run there too, or in the jobs of other branches (a push to stage points staging, a push to production promotes): each finds the version by the commit the freeze was told of, so no job hands a version number to another.

1. Push the Typst

jq -n --rawfile code invoice.typ \
      --slurpfile schema schema.json \
      --slurpfile sample sample.json \
      '{code: $code, schema: $schema[0], sampleData: $sample[0]}' |
curl -sS --fail-with-body -X PUT "$API/draft" \
  -H "$AUTH" -H "Content-Type: application/json" --data-binary @-

The answer is the draft as the write left it (code left out here):

{
  "externalId": "invoice-primary",
  "status": "published",
  "schema": { "type": "object", "properties": { ... }, "required": ["invoiceNo"] },
  "sampleData": { "invoiceNo": "INV-0119" },
  "pageSettings": {},
  "generatedFromBlocks": false,
  "autoPublishEdits": false,
  "updatedAt": "2026-11-04T11:29:25.140Z",
  "changed": true,
  "frozenAsLatest": null
}

Production has not moved. "changed": false means the draft held all of this already, and nothing was compiled or written; code that differs only by spaces, tabs and line breaks at its end counts as the same. To have the push refused when someone changed the template in the app since you last pulled it, add the updatedAt you pulled as expectedUpdatedAt: the answer is then 409 template_changed, and your own pushes since that pull do not count as changes. If the Typst does not compile against the sample data and the default fixtures, the answer is 422 compile_gate_failed with the diagnostics, and the draft stays as it was. 503 compiler_unavailable and 429 rate_limited say nothing about your template: send the same request again, after Retry-After seconds when the header is there.

2. Freeze it and point dev at it

jq -n --arg sha "$GITHUB_SHA" '{changelog: ("Commit " + $sha), ref: $sha, promoteTo: "dev"}' > freeze-body.json
curl -sS --fail-with-body --retry 20 --retry-max-time 1200 -X POST "$API/versions" \
  -H "$AUTH" -H "Content-Type: application/json" --data-binary @freeze-body.json -o freeze.json ||
  { cat freeze.json; exit 1; }

{
  "version": 5,
  "contentHash": "sha256:331c5e4f...",
  "created": true,
  "ref": "3f2a9c1e5b7d4a20c9e1f6b3d8a2c7e4f1b9d063",
  "promotedTo": "dev",
  "promotion": {
    "name": "dev",
    "version": 5,
    "updatedAt": "2026-11-04T11:29:28.299Z",
    "updatedBy": "s1dSGJv3...",
    "previousVersion": 4,
    "moved": true,
    "forced": false,
    "schemaChanges": { "breaking": [], "notable": [] }
  },
  "latestCreated": false
}

v5 cannot change from here on. dev is made the first time it is named, and previousVersion is null then. If the draft has not changed since the newest version, nothing new is frozen: the answer is 200 with that version and "created": false. That freeze still compiles and counts against the freeze limit, and it is what records this commit as a ref of the version: skip it, and the later steps answer 404 ref_not_found for the commit. So a job that promotes by commit freezes every template it pushes, on every push. It meets 429 once it has frozen more than the limit takes at once (about ten, then one a minute). --retry 20 waits out a 429 or a 503 for its Retry-After (curl 7.66 or later) and sends the freeze again, from the file, as stdin cannot be sent twice, and --retry-max-time 1200 stops retrying after 20 minutes (a request under way may still finish later). Sending it again is safe: a freeze that went through already answers the same version, 200 with "created": false, and records nothing new.

ref is recorded on the version the freeze answers with, whether it made one or not, so every commit names the version it was frozen as. A ref names one version for good: a freeze that would record it on another (a job for an old commit run again after newer ones changed the draft) is refused with 409 ref_conflict, and nothing is frozen. Run this branch's job one push at a time (in GitHub Actions, concurrency: { group: "pdfs-freeze-${{ github.ref }}", cancel-in-progress: false }): two runs whose steps 1 and 2 interleave would record one commit's ref on the other's draft, and a ref is not moved once recorded. Not every commit of the branch is frozen: a push of several commits runs the job for the last of them, and with the group a run still waiting is replaced by a newer push's.

3. Point staging at it

Once your checks against dev pass, in the same job or the one a push to your stage branch starts:

curl -sS --fail-with-body -X PUT "$API/channels/staging" \
  -H "$AUTH" -H "Content-Type: application/json" \
  -d "{\"ref\": \"$GITHUB_SHA\"}" -o staging.json || { cat staging.json; exit 1; }
VERSION=$(jq -er .version staging.json)

{
  "name": "staging",
  "version": 5,
  "updatedAt": "2026-11-04T11:29:28.399Z",
  "updatedBy": "s1dSGJv3...",
  "previousVersion": 4,
  "moved": true,
  "forced": false,
  "schemaChanges": { "breaking": [], "notable": [] }
}

Staging moves to the version that commit was frozen as, wherever dev has gone since. In a branch's own job $GITHUB_SHA is the commit the branch is at, so move the stage and production branches by fast-forward to commits the first branch froze (git merge --ff-only, or git push origin <commit>:refs/heads/stage), once that commit's job on the first branch has succeeded. Before then, for a commit it never ran for, and for a merge, squash or rebase, which makes a commit no freeze was told of, the answer is 404 ref_not_found. refs in GET …/versions lists the commits there are. A channel can have any name, so qa or uat work the same way.

4. Test against staging

curl -sS --fail-with-body -X POST "$API/render" \
  -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"version": "staging", "data": {"invoiceNo": "INV-0120"}}' \
  -D headers.txt -o staging.pdf || { cat staging.pdf; exit 1; }

grep -i '^x-template' headers.txt
# x-template-version: 5
# x-template-channel: staging
test "$(grep -i '^x-template-version:' headers.txt | tr -d '\r' | cut -d' ' -f2)" = "$VERSION" ||
  { echo "staging did not render v$VERSION"; exit 1; }

The headers say what was rendered. The last line fails the job unless staging rendered $VERSION, since someone may have moved staging in the meantime. Your staging environment renders the same way, with "version": "staging". Test renders count toward your monthly quota like any other.

5. Promote to production

curl -sS --fail-with-body -X PUT "$API/channels/latest" \
  -H "$AUTH" -H "Content-Type: application/json" \
  -d "{\"ref\": \"$GITHUB_SHA\"}"

{
  "name": "latest",
  "version": 5,
  "updatedAt": "2026-11-04T11:29:29.526Z",
  "updatedBy": "s1dSGJv3...",
  "previousVersion": 4,
  "moved": true,
  "forced": false,
  "schemaChanges": { "breaking": [], "notable": [] }
}

Every render that leaves out version gets v5 from now on. To roll back, move latest to the old number: -d '{"version": 4}'. A promotion that runs as a job of its own, behind a manual approval say, can send {"fromChannel": "staging"} to ship exactly what staging serves, and "expectedVersion": 4 to be refused with 409 channel_moved if production has moved since it was read.

When the change would break production

Say v5 adds a required poNumber field. Production's callers do not send it yet, so v5 would refuse their requests. Steps 2 and 3 still go through, because dev and staging are where such a change is tested, and their answers list it:

"schemaChanges": {
  "breaking": [
    { "path": "poNumber", "kind": "required_added", "message": "\"poNumber\" is now required" }
  ],
  "notable": []
}

Step 5 is refused with 409, and production stays on v4:

{
  "error": "breaking_schema_change",
  "message": "Moving production (\"latest\") from v4 to v5 changes the data a request must send, so a request that works today could fail: \"poNumber\" is now required. Nothing was changed. Send force: true to move it anyway.",
  "currentVersion": 4,
  "targetVersion": 5,
  "breaking": [
    { "path": "poNumber", "kind": "required_added", "message": "\"poNumber\" is now required" }
  ],
  "notable": []
}

A change is breaking when a request that works today could fail on it: a new required field, an optional field made required, a changed type, or fewer enum values. A removed field or a new optional one is listed under notable and does not stop the move. Read those too: a template written in Typst refuses a field it does not take, so callers that still send a removed field fail with unexpected argument.

Ship the callers first. While they roll out, they can pin "version": 5 and send the new field. Then promote with force:

curl -sS --fail-with-body -X PUT "$API/channels/latest" \
  -H "$AUTH" -H "Content-Type: application/json" \
  -d "{\"ref\": \"$GITHUB_SHA\", \"force\": true}"

The answer has "forced": true and lists the same change under schemaChanges.breaking.

The same steps are in the app's Versions tab and over MCP: see how to test template changes before they reach production.

Get template draft

Returns the template's draft: the working copy the editor shows, which production does not render until it is frozen and promoted. The answer has the Typst code, schema, sampleData and pageSettings, and updatedAt, the draft's version to the millisecond. generatedFromBlocks is true for a template built from blocks in the visual editor, whose code cannot be written over the API. autoPublishEdits is true for a template from before versions, where production serves the draft as it is. Pictures in sampleData are storage keys: one sent back as it came stays the same picture.

A key sees its creator's own templates, every published template, and any template its creator may edit.

Update template draft

Replaces any of the draft's code, schema, sampleData and pageSettings; what you leave out stays as it is. This is how a CI job pushes the Typst its repository holds. It changes the draft and nothing else: production keeps rendering the version latest points at, no channel moves, and the editor's History gets an entry for the write. The exception is a template with autoPublishEdits, whose production serves the draft, so a write there is live at once. The key's creator must own the template or be an organization owner or admin (403 forbidden).

Request body

Send at least one of the first four (400 empty_draft_update). Any other field is refused (400 invalid_draft_update).

Compile check

Nothing is written unless the draft the write would leave compiles against its sample data and the default fixtures. If it does not, the answer is 422 compile_gate_failed with failed_fixtures and diagnostics. If the compile check could not run, the answer is 503 compiler_unavailable: send the write again, after Retry-After seconds when the header is there. The write is also refused for a link to anything but an http:, https:, mailto: or tel: address (400 unsafe_link_target), a picture stored for another template (400 foreign_image_key), and a template built from blocks (409 template_has_blocks).

Response

Returns 200 with the draft as the write left it, plus changed and frozenAsLatest. A write the draft already holds answers "changed": false at once, with no compile and no rate-limit cost, so a pipeline can push every template on every merge. Code that differs from the draft's only by spaces, tabs and line breaks at its very end, such as the final newline a file gets, is the draft's code: the draft keeps its own, and the write changes nothing for it. frozenAsLatest is a version number only for the first write to a published template that has never had a version: production was serving that draft, so it is frozen as v1 and latest is pointed at it before the write goes in. Otherwise it is null.

Writes that compile are limited per organization, to about 60 at once and then two a minute: past the limit the answer is 429 rate_limited with Retry-After. Someone with the template open in the editor is told it changed when they next save.

List versions

Returns the template's frozen versions, newest first, each with the channels on it and the refs freezes recorded on it, in the order they were recorded; every channel with the version it points at; and draft, which says whether the draft holds changes the newest version does not. A key sees the template as Get template draft does: its creator's own templates, every published template, and any template its creator may edit, so an organization owner's or admin's key sees a member's unpublished template.

{
  "versions": [
    {
      "version": 5,
      "contentHash": "sha256:331c5e4f...",
      "changelog": "Commit 3f2a9c1",
      "createdAt": "2026-11-04T11:29:28.299Z",
      "createdBy": "s1dSGJv3...",
      "channels": ["dev", "staging"],
      "refs": ["3f2a9c1e5b7d4a20c9e1f6b3d8a2c7e4f1b9d063"]
    },
    {
      "version": 4,
      "contentHash": "sha256:d7e3e108...",
      "changelog": "Commit 9b04e7d",
      "createdAt": "2026-11-02T16:02:11.870Z",
      "createdBy": "s1dSGJv3...",
      "channels": ["latest"],
      "refs": ["9b04e7d2c1a8f3e6b5d4c7a9e2f1b8d3c6a5e4f7", "0d8c1f2e3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d"]
    }
  ],
  "channels": [
    { "name": "dev", "version": 5, "updatedAt": "2026-11-04T11:29:28.299Z", "updatedBy": "s1dSGJv3..." },
    { "name": "latest", "version": 4, "updatedAt": "2026-11-02T16:40:05.112Z", "updatedBy": "s1dSGJv3..." },
    { "name": "staging", "version": 5, "updatedAt": "2026-11-04T11:29:28.399Z", "updatedBy": "s1dSGJv3..." }
  ],
  "draft": { "newestVersion": 5, "hasUnfrozenChanges": false }
}

Freeze a version

Compiles the draft against its sample data and the default fixtures, as publishing does, and freezes it as a new immutable version. Production does not move. Send promoteTo to point a channel at the new version in the same call. The key's creator must own the template or be an organization owner or admin.

Request body (optional)

Response

Returns 201 with version, contentHash, created, ref, promotedTo and promotion (what moving the channel did, as Move a channel answers it). If the draft has not changed since the newest version, nothing new is frozen: the answer is 200 with that version and "created": false. It still compiles, and counts against the limit below. latestCreated is true when the template was published with no version yet: the freeze also points latest at the version, which is the draft production was already serving.

A draft that does not compile answers 422 compile_gate_failed and freezes nothing. A compile check that could not run answers 503 compiler_unavailable, which says nothing of the draft: send the request again, after Retry-After seconds when the header is there. With promoteTo, a move that would be refused freezes nothing either: 409 breaking_schema_change (only for latest), 409 template_not_published or 409 auto_publish_enabled. 409 publish_conflict means the draft changed while it was being compiled: freeze again. promoteTo takes no expectedVersion; to guard against a move made at the same moment, freeze without it and move the channel with expectedVersion.

ref is recorded on the version the answer names, a new one or, with "created": false, the newest. A version can carry many refs, and within a template a ref names one version: the same ref sent again for the same version changes nothing, and sent when the answer would be another version it is refused with 409 ref_conflict, which names the version it is on in refVersion, and nothing is frozen. A freeze refused for any reason records no ref. A ref that breaks the rule above is 400 invalid_ref.

Freezing compiles, so an organization may freeze about ten versions at once and then one a minute. Past that the answer is 429 rate_limited with Retry-After.

Move a channel

Points a channel at a version, and makes the channel if it does not exist yet. A channel is a name you choose, such as dev, staging or qa: up to 64 lowercase letters, digits, ., _ and -, starting with a letter or a digit, and neither draft nor only digits, so it never shadows a version (400 invalid_channel_name). latest is production: moving it is a promotion, and moving it to an older version is a rollback. Renders that leave out version follow at once. The template must be published (409 template_not_published), and the key's creator must own it or be an organization owner or admin.

Request body

Schema changes

Every move compares the schema of the target version with the schema of the version the channel serves now, rollbacks included. For latest, a change a request that works today could fail on (a new required field, an optional field made required, a changed type, fewer enum values) is refused with 409 breaking_schema_change, which lists each change in breaking, and nothing moves. Send force: true to move it anyway. Any other channel moves and lists what breaks in schemaChanges.breaking, because that is where such a change is tested. Show each change's message: new kind values may be added.

Response

Returns 200 with the channel (name, version, updatedAt, updatedBy) and previousVersion (null for a new channel), moved (false when it was on that version already), forced and schemaChanges (breaking and notable). A version the template does not have is 404 version_not_found, a fromChannel that does not exist is 404 channel_not_found, and a ref no freeze of this template recorded is 404 ref_not_found. On a template that publishes its edits as they are saved (one from before versions), latest does not move (409 auto_publish_enabled): turn that off in the template's Versions tab first.

Remove a channel

Removes a channel and answers with the version it pointed at: { "name": "dev", "version": 5 }. The version is kept and can still be rendered by number. A render that names the removed channel is refused with 400 until the channel is set again. latest cannot be removed (400 channel_protected): unpublish the template instead. A channel that does not exist answers 404 channel_not_found.

Migrate from v1

V1 remains supported and continues to identify templates by the generated internal ID. V2 adds an organization-scoped external ID that you control. Existing templates initially use their internal ID as the external ID; rename it in the dashboard or with PATCH /v2/organizations/:organizationId/templates/:externalId.

Importing a .docx

An existing Word document can be converted into a template instead of being rebuilt by hand. The import reads the document's structure and produces template code plus a matching JSON Schema, which is then editable like any other template — including through the chat agent.

Available in the app under Templates → Import, and over MCP with import_docx, process_docx_import and convert_docx_to_template.

A hyperlink to anything but an http:, https:, mailto: or tel: address (sms:, file:) keeps its text and loses its address, and the import says which addresses went (droppedLinks in the response, and in the tool's result over MCP).

Documents whose structure is expressed with real Word styles — headings, tables, lists — import most cleanly, because those are what map onto template structure. A file formatted by hand, with spacing and alignment instead of styles, carries no structure to read and is usually faster to redraw from one of the starting designs.

MCP server (for AI agents)

The same authentication layer also serves a Model Context Protocol endpoint. Agents that connect to it can design, publish, and render PDFs inside a single conversation — without API keys or dashboard handoffs.

Tool surface

The MCP server exposes the entire template lifecycle plus authenticated rendering. MCP renders count toward the same monthly PDF render quota as UI, authenticated form, automation, and REST API renders.

The four version tools are not available on a delegated connection.

Sessions and parallel agents

Each MCP connection gets its own isolated session on initialize, holding one active template (the one last loaded with get_template or created with create_template). Editing tools like edit_document and save_template operate on that session's active template.

Every editing tool takes a templateId and is refused when it does not match the session's active template, so a write can never land on the wrong document.

To build many templates in parallel, give each agent its own MCP connection — parallel agents then work on separate templates with fully independent state. Do not fan multiple agents out over a single shared connection: their calls run one at a time against one active template, so whichever agent loads a template last makes every other agent's calls fail. If two sessions do end up editing the same template, save_template detects the external modification and refuses to silently overwrite it — reload with get_template and re-apply your changes.

Connect from Claude Desktop, Cursor, or any MCP-compatible client. See the MCP integration guide for an end-to-end example.

Errors

All errors return a JSON body whose top-level error is a string — a machine-readable code for most failures — usually alongside a human-readable message. Validation and compilation failures instead carry a structured details or diagnostics array.

{
  "error": "draft_not_renderable",
  "message": "This template is not published. Publish it to render it through the API. On a plan with no published-template limit, you can also render its draft with \"version\": \"draft\"."
}

Rate limits

Requests are not throttled per API key. The limit that applies is your plan's monthly PDF render quota, shared by every render surface — REST API, app, MCP and the embedded editor. Once it is used up, render requests return 429 with render_quota_exceeded until the billing period rolls over or you buy a top-up pack; async renders are counted when they are queued.

The two calls that compile a template without rendering it are limited per organization, however many keys it has: a draft write (about 60 at once and then two a minute) and a freeze (about ten at once and then one a minute). Past the limit they answer 429 rate_limited with Retry-After. A draft write the draft already holds costs nothing.

Everything else (template management, logs and webhook endpoints) is not metered.

API keys

API keys are scoped to your organization and grant access to all templates your organization can see. Keys are prefixed with prs_ and displayed only once on creation — copy them immediately and store them in a secret manager or environment variable.

A key belongs to the member who created it, and keeps working after they leave the organization so that integrations do not break. Owners and admins see who created each key, can rename or revoke any key in the organization, and are emailed when someone leaves with keys that still work. Members manage their own keys.

A key acts with the role of the member who created it. Writing a template's draft, freezing a version and moving or removing a channel need a key whose creator owns the template or is an owner or admin of the organization, so a CI job that promotes templates other people own needs a key made by an owner or admin.