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 generation 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

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

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 generation-log foreign keys do not change. Requires template ownership or organization admin access.

Generation logs

Returns a paginated list of PDF generation events for your organization. Each log exposes templateInternalId and the templateExternalId captured when that generation 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

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 withimport_docx,process_docx_importandconvert_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 thestarting 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 theMCP integration guidefor an end-to-end example.

Errors

All errors return a JSON body with a top-level error object.

{
  "error": {
    "code": "schema_validation_failed",
    "message": "Missing required field: company"
  }
}

Rate limits

Rate limits apply per API key, per minute. When a limit is exceeded, the API returns a 429 status. Check the response headers to determine when you can retry.

Rate limit headers

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.