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, and sample data. 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",
  "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.

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.

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