API Reference

Authentication

All API requests require a bearer token. Create and manage API keys from Settings → 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. Drafts are not visible to the render endpoint until they are published. 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.

Request body (optional)

Returns the updated template detail. Returns 402 template_limit_reached if the org's plan does not allow another published template.

Unpublish template

Moves a published template back to draft. Once unpublished, the template can no longer be rendered by the public API and is removed from organization template listings. 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 private until you promote them, so production keeps rendering the same document — and the same schema — while you iterate. Freeze the draft as a new version to test it ({ "version": 4 }) while production stays on the promoted one, then promote when you are ready and every caller that omits version picks it up. Promoting an older version back is an instant rollback.

Response

Returns Content-Type: application/pdf on success. 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.

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 template that renders its live draft (nothing promoted yet, or a legacy auto-publish template): the draft is not pinned, so edits made mid-batch can reach later items. Items send no per-render webhooks; one batch.completed event goes out when every item has succeeded or failed (webhooks need the Pro plan or higher).

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 the Pro plan and higher.

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 the Pro plan or higher; 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.

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.

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.

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": "Only published templates can be rendered via the API. Publish this template first."
}

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.

Template management, logs and webhook endpoints are 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.