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 public REST API is versioned under /v1/* and accepts API keys only. The web app uses separate internal /api/* routes backed by app sessions, so API keys authenticate the public REST surface only.

Key format

Keys are prefixed with prs_ and scoped to your organization.

curl https://api.pdfs.build/v1/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. The request body submits ready-to-render template code, schema, and example data — no lint or transformation is applied, so payloads should be valid template code with a top-level #let render(...) = { ... } function whose named parameters match the schema fields.

Request body

Returns 201 with the full template detail, including the generated id. Save that id; you will need it to publish and render the template.

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 via /v1/render 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/v1/render',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      templateId: 'tmpl_abc123',
      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/v1/render",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "templateId": "tmpl_abc123",
        "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/v1/render" \
  -H "Authorization: Bearer prs_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"templateId": "tmpl_abc123", "data": {"company": "Acme Corp", "due_date": "2025-06-01"}}' \
  --output output.pdf

List templates

Returns all templates visible to the authenticated user — their own drafts and their organization's published templates.

[
  {
    "id": "tmpl_abc123",
    "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.

{
  "id": "tmpl_abc123",
  "name": "Invoice v3",
  "status": "published",
  "schema": {
    "type": "object",
    "properties": {
      "company": { "type": "string" },
      "due_date": { "type": "string", "format": "date" },
      "items": { "type": "array" }
    }
  },
  "sampleData": { /* ... */ }
}

Generation logs

Returns a paginated list of PDF generation events for your organization. Useful for auditing, debugging, and tracking usage.

Query parameters

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 exercise the public render API end-to-end inside a single conversation — without the user touching the dashboard.

Tool surface

The MCP server exposes the entire template lifecycle plus an API-key admin surface so an agent can self-serve a key, test the render API, and clean up afterwards.

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.