pdfs-build Rendering API

openapi: 3.2.0
info:
  title: pdfs.build Rendering API
  version: '2.0'
  summary: Render PDFs from templates, manage templates, webhooks, embedded editor sessions and delegated agent access.
  description: 'All requests are authenticated with an organization-scoped API key (`prs_...`) sent as a Bearer token. Create keys under **Settings → API Keys** in the dashboard or with the MCP `create_api_key` tool. Keys are shown once.


    The organization in every `/v2` URL must match the key''s organization, otherwise the request fails with `403 organization_scope_mismatch`.


    **Errors** are JSON with a top-level `error` string — a machine-readable code for most failures, a phrase for a few legacy ones — usually alongside a human-readable `message`. Data validation and template compilation failures carry `details` / `diagnostics` instead of a `message`.


    **Versions.** `/v2` addresses templates by an external id you control. The legacy `/v1` routes identify templates by their generated internal id and remain supported for existing integrations.


    **Timestamps.** Objects served by the render service (templates, render jobs, logs, webhook endpoints) carry UTC timestamps in ISO 8601 form without a timezone suffix, e.g. `2026-08-30T12:00:00.123456`. Embedded-editor sessions and delegated access return RFC 3339 with a trailing `Z`.


    The narrative guide — authentication, webhook signatures, the MCP server, migrating from v1 — lives at https://pdfs.build/docs/ (Markdown mirror: https://pdfs.build/docs.md).'
  contact:
    name: pdfs.build
    url: https://pdfs.build
    email: hello@pdfs.build
  termsOfService: https://pdfs.build/terms/
  license:
    name: Proprietary
    url: https://pdfs.build/terms/
servers:
- url: https://api.pdfs.build
  description: Production
security:
- apiKey: []
tags:
- name: Rendering
  description: Compile a published template with your data. Synchronous renders return the PDF; async renders return a job handle and notify webhooks.
paths:
  /v2/organizations/{organizationId}/templates/{externalId}/render:
    parameters:
    - $ref: '#/components/parameters/organizationId'
    - $ref: '#/components/parameters/externalId'
    post:
      tags:
      - Rendering
      summary: Render PDF
      operationId: renderTemplate
      description: 'Validates `data` against the template''s schema, compiles the template, and returns the PDF. Requires a published template and a plan with REST API access (Starter and higher).


        Send `"async": true` to render in the background instead: the response is `202` with a job handle; poll the job or wait for the `render.completed` / `render.failed` webhook. Async renders count toward the same monthly quota as synchronous ones.


        Webhook events for this render go to every enabled endpoint of the organization, or only to the endpoints in `webhookIds` when provided (an empty list sends nowhere).'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RenderRequest'
            examples:
              sync:
                summary: Synchronous render
                value:
                  data:
                    company: Acme Corp
                    items:
                    - name: Consulting
                      qty: 3
                      price: 150
                    due_date: '2026-06-01'
              async:
                summary: Async render, restricted to one webhook endpoint
                value:
                  data:
                    company: Acme Corp
                  async: true
                  webhookIds:
                  - whe_5xg6Kq0PSTeK1bXf3eDR3w
              pinned:
                summary: Render a specific version
                value:
                  data:
                    company: Acme Corp
                  version: 4
      responses:
        '200':
          description: The rendered PDF.
          headers:
            Content-Disposition:
              schema:
                type: string
              description: '`inline; filename="<template>.pdf"`'
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        '202':
          description: Async render accepted and queued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RenderJobAccepted'
        '400':
          description: '`data` does not match the template schema (`Validation failed` with `details`), an invalid `version` selector, or `invalid_external_id`.'
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/ValidationError'
                - $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          description: '`api_renders_not_allowed_on_free` — REST renders need Starter or higher.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: '`draft_not_renderable` (publish first) or `organization_scope_mismatch`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          $ref: '#/components/responses/TemplateNotFound'
        '422':
          description: The template failed to compile with this data (`Compilation failed` with `diagnostics`), or `unknown_webhook_ids`.
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/CompilationError'
                - $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/QuotaExceeded'
        '500':
          $ref: '#/components/responses/InternalError'
  /v2/organizations/{organizationId}/templates/{externalId}/batches:
    parameters:
    - $ref: '#/components/parameters/organizationId'
    - $ref: '#/components/parameters/externalId'
    post:
      tags:
      - Rendering
      summary: Render a batch
      operationId: createRenderBatch
      description: 'Queues one async render per entry in `items`, up to 500, against one template and one version. The version is resolved when the batch is submitted, 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. The whole batch is admitted against your monthly quota or rejected with `429`; a batch is never partially queued.


        Items emit no per-render webhooks. On plans with webhooks (every paid plan), one `batch.completed` event goes to every enabled endpoint (or the `webhookIds` given) once every item has succeeded or failed. Poll `statusUrl` for per-item status and download links.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RenderBatchRequest'
            example:
              items:
              - data:
                  company: Acme Corp
                  total: 450
              - data:
                  company: Globex
                  total: 1200
              webhookIds:
              - whe_5xg6Kq0PSTeK1bXf3eDR3w
      responses:
        '202':
          description: Batch accepted and queued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RenderBatchAccepted'
        '400':
          description: An invalid or unrenderable `version` selector, or `invalid_external_id`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          description: '`api_renders_not_allowed_on_free`: REST renders need Starter or higher.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          $ref: '#/components/responses/OrganizationScopeMismatch'
        '404':
          $ref: '#/components/responses/TemplateNotFound'
        '413':
          description: The request body exceeds 10 MB.
        '422':
          description: '`invalid_batch_size` (0 or more than 500 items) or `unknown_webhook_ids`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/QuotaExceeded'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    RenderJobAccepted:
      type: object
      required:
      - id
      - status
      - statusUrl
      properties:
        id:
          type: string
          example: job_7a1b9c2d
        status:
          type: string
          const: queued
        statusUrl:
          type: string
          format: uri
          example: https://api.pdfs.build/v2/organizations/org_abc/renders/job_7a1b9c2d
    RenderRequest:
      type: object
      properties:
        data:
          type: object
          description: Key-value pairs matching the template's schema. Defaults to `{}`.
          additionalProperties: true
        async:
          type: boolean
          default: false
          description: 'Render in the background and return `202` with a job handle. `version` is resolved when the job is queued, as for a batch: one that does not exist is a `400`, and a channel is held to the version it named then.'
        webhookIds:
          type: array
          items:
            type: string
          description: 'Restrict this render''s webhook events to these endpoint ids (`whe_...`). Unknown ids fail with `422 unknown_webhook_ids`. Omitted: all enabled endpoints. `[]`: none.'
        version:
          $ref: '#/components/schemas/VersionSelector'
    CompilationError:
      type: object
      required:
      - error
      - diagnostics
      properties:
        error:
          type: string
          const: Compilation failed
        diagnostics:
          type: array
          items:
            $ref: '#/components/schemas/TypstDiagnostic'
    ValidationError:
      type: object
      required:
      - error
      - details
      properties:
        error:
          type: string
          const: Validation failed
        details:
          type: array
          items:
            type: object
            required:
            - path
            properties:
              path:
                type: string
                description: JSON path of the offending value.
              message:
                type: string
    ExternalId:
      type: string
      pattern: ^[A-Za-z0-9._~-]{1,128}$
      description: Organization-scoped template id you control. 1–128 ASCII letters, digits, `.`, `_`, `~` or `-`; `.` and `..` are reserved. Case-sensitive.
    RenderBatchRequest:
      type: object
      required:
      - items
      properties:
        items:
          type: array
          minItems: 1
          maxItems: 500
          items:
            type: object
            properties:
              data:
                type: object
                description: Template data for this document, validated against the template schema when the item renders.
        webhookIds:
          type: array
          items:
            type: string
          description: 'Endpoints to notify with `batch.completed`. Omitted: every enabled endpoint. Empty: none.'
        version:
          $ref: '#/components/schemas/VersionSelector'
    TypstDiagnostic:
      type: object
      required:
      - severity
      - message
      properties:
        severity:
          type: string
          enum:
          - error
          - warning
        message:
          type: string
        line:
          type: integer
        column:
          type: integer
        snippet:
          type: string
        source_context:
          type: string
        hint:
          type: string
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          description: Machine-readable code (e.g. `draft_not_renderable`) or, for a few legacy failures, a short phrase.
        message:
          type: string
          description: Human-readable detail. Present on most coded errors.
      example:
        error: draft_not_renderable
        message: Only published templates can be rendered via the API. Publish this template first.
    RenderBatchAccepted:
      type: object
      required:
      - id
      - status
      - total
      - statusUrl
      properties:
        id:
          type: string
          example: batch_3f6a0c1e
        status:
          type: string
          const: processing
        total:
          type: integer
          example: 2
        statusUrl:
          type: string
          format: uri
          example: https://api.pdfs.build/v2/organizations/org_abc/batches/batch_3f6a0c1e
    VersionSelector:
      description: Which content to render. Omitted or `null` resolves through the `latest` channel, which follows promotions rather than in-progress edits. A positive integer pins a version number, `"draft"` renders the mutable working copy, and any other string names a channel.
      oneOf:
      - type: integer
        minimum: 1
      - type: string
        examples:
        - latest
        - draft
        - staging
        - '4'
  responses:
    InternalError:
      description: Rendering failed for a reason that is not the template or the data. Safe to retry.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Internal compilation error
    QuotaExceeded:
      description: '`render_quota_exceeded` — this billing period''s render quota is used up. Upgrade or buy a top-up pack.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    OrganizationScopeMismatch:
      description: The organization in the URL does not match the API key's organization.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: organization_scope_mismatch
            message: The organization in the URL does not match the API key organization
    TemplateNotFound:
      description: No template with that id is accessible to this key. Another user's draft is indistinguishable from a missing template.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Template not found
    Unauthorized:
      description: Missing, invalid or expired API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Unauthorized
  parameters:
    externalId:
      name: externalId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/ExternalId'
      description: The template's organization-scoped external id.
      example: invoice-primary
    organizationId:
      name: organizationId
      in: path
      required: true
      schema:
        type: string
      description: Your organization id. Must match the API key's organization.
      example: org_abc
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: prs_...
      description: Organization-scoped API key, created under Settings → API Keys or with the MCP `create_api_key` tool.
externalDocs:
  description: 'API guide: authentication, errors, webhooks, MCP, migrating from v1'
  url: https://pdfs.build/docs/