pdfs-build Legacy v1 API

openapi: 3.2.0
info:
  title: pdfs.build Legacy v1 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: Legacy v1
  description: Templates addressed by their generated internal id. Supported, but new integrations should use `/v2`.
paths:
  /v1/render:
    post:
      tags:
      - Legacy v1
      deprecated: true
      summary: Render PDF (v1)
      operationId: renderTemplateV1
      description: Synchronous render addressed by the template's internal id. Emits webhook events to every enabled endpoint; there is no async mode on v1. Prefer `POST /v2/organizations/{organizationId}/templates/{externalId}/render`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RenderRequestV1'
      responses:
        '200':
          description: The rendered PDF.
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        '400':
          description: Missing `templateId`, an invalid `version`, or `data` failing schema validation.
          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`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: '`draft_not_renderable`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          $ref: '#/components/responses/TemplateNotFound'
        '422':
          description: Compilation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompilationError'
        '429':
          $ref: '#/components/responses/QuotaExceeded'
        '500':
          $ref: '#/components/responses/InternalError'
  /v1/templates:
    get:
      tags:
      - Legacy v1
      deprecated: true
      summary: List templates (v1)
      operationId: listTemplatesV1
      responses:
        '200':
          description: Published templates in the key's organization.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TemplateSummaryV1'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Legacy v1
      deprecated: true
      summary: Create template (v1)
      operationId: createTemplateV1
      description: Creates a draft whose external id equals its generated internal id. Cannot lock the schema or set a tenant scope; use v2 for those.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTemplateRequestV1'
      responses:
        '201':
          description: The created draft.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateV1'
        '400':
          description: Missing `name` or `code`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/templates/{id}:
    parameters:
    - $ref: '#/components/parameters/templateIdV1'
    get:
      tags:
      - Legacy v1
      deprecated: true
      summary: Get template (v1)
      operationId: getTemplateV1
      parameters:
      - $ref: '#/components/parameters/resolveImages'
      responses:
        '200':
          description: The template.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateV1'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/TemplateNotFound'
  /v1/templates/{id}/publish:
    parameters:
    - $ref: '#/components/parameters/templateIdV1'
    post:
      tags:
      - Legacy v1
      deprecated: true
      summary: Publish template (v1)
      operationId: publishTemplateV1
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublishTemplateRequest'
      responses:
        '200':
          description: The published template, with the version `latest` now serves.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublishedTemplateV1'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          description: '`template_limit_reached`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: '`forbidden`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          $ref: '#/components/responses/TemplateNotFound'
        '422':
          description: Compilation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompilationError'
  /v1/templates/{id}/unpublish:
    parameters:
    - $ref: '#/components/parameters/templateIdV1'
    post:
      tags:
      - Legacy v1
      deprecated: true
      summary: Unpublish template (v1)
      operationId: unpublishTemplateV1
      responses:
        '200':
          description: The template, now a draft.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateV1'
        '400':
          description: '`already_draft`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: '`forbidden`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          $ref: '#/components/responses/TemplateNotFound'
  /v1/templates/{id}/logs:
    parameters:
    - $ref: '#/components/parameters/templateIdV1'
    get:
      tags:
      - Legacy v1
      deprecated: true
      summary: List render logs for a template (v1)
      operationId: listTemplateLogsV1
      parameters:
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/logStatus'
      - $ref: '#/components/parameters/logSource'
      responses:
        '200':
          description: Newest first.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RenderLogListV1'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/TemplateNotFound'
  /v1/logs:
    get:
      tags:
      - Legacy v1
      deprecated: true
      summary: List render logs (v1)
      operationId: listLogsV1
      parameters:
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/logStatus'
      - $ref: '#/components/parameters/logSource'
      - name: templateId
        in: query
        schema:
          type: string
        description: Only logs for this internal template id.
      - name: search
        in: query
        schema:
          type: string
      - name: from
        in: query
        schema:
          type: string
          format: date-time
      - name: to
        in: query
        schema:
          type: string
          format: date-time
      responses:
        '200':
          description: Newest first.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RenderLogListV1'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/logs/{id}:
    parameters:
    - name: id
      in: path
      required: true
      schema:
        type: string
      description: Render log id.
    get:
      tags:
      - Legacy v1
      deprecated: true
      summary: Get render log (v1)
      operationId: getLogV1
      responses:
        '200':
          description: The log entry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RenderLogDetailV1'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Unknown log id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Log not found
components:
  schemas:
    RenderLogDetailV1:
      allOf:
      - $ref: '#/components/schemas/RenderLogV1'
      - type: object
        required:
        - organizationId
        properties:
          organizationId:
            type: string
          requestPayload:
            type:
            - object
            - 'null'
            additionalProperties: true
    Timestamp:
      type: string
      description: UTC, ISO 8601 without a timezone suffix.
      example: '2026-08-30T12:00:00.123456'
    PublishTemplateRequest:
      type: object
      properties:
        name:
          type: string
          description: Rename on publish.
        description:
          type: string
          description: Update the description on publish.
    CreateTemplateRequestV1:
      type: object
      required:
      - name
      - code
      properties:
        name:
          type: string
        description:
          type: string
        code:
          type: string
          description: Template source (`typstCode` accepted as a legacy alias).
        schema:
          type: object
          additionalProperties: true
        sampleData:
          type: object
          additionalProperties: true
        pageSettings:
          type: object
          additionalProperties: true
    RenderLogListV1:
      type: object
      required:
      - logs
      - total
      properties:
        logs:
          type: array
          items:
            $ref: '#/components/schemas/RenderLogV1'
        total:
          type: integer
    RenderLogV1:
      type: object
      required:
      - id
      - templateId
      - source
      - status
      - createdAt
      - apiKeyName
      - apiKeyPrefix
      properties:
        id:
          type: string
        templateId:
          type: string
          description: Internal template id.
        templateName:
          type:
          - string
          - 'null'
        source:
          type: string
        status:
          type: string
          enum:
          - pending
          - success
          - error
        errorMessage:
          type:
          - string
          - 'null'
        durationMs:
          type:
          - integer
          - 'null'
        apiKeyId:
          type:
          - string
          - 'null'
        userId:
          type:
          - string
          - 'null'
        templateUpdatedAt:
          oneOf:
          - $ref: '#/components/schemas/Timestamp'
          - type: 'null'
        createdAt:
          $ref: '#/components/schemas/Timestamp'
        apiKeyName:
          type:
          - string
          - 'null'
        apiKeyPrefix:
          type:
          - string
          - 'null'
    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
    PublishedTemplateV1:
      allOf:
      - $ref: '#/components/schemas/TemplateV1'
      - type: object
        required:
        - publishedVersion
        properties:
          publishedVersion:
            type: integer
            minimum: 1
            description: 'The version `latest` now points at: the one this publish froze, or the newest existing one when nothing changed since it. Pin renders to it with `version`.'
    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'
    TemplateStatus:
      type: string
      enum:
      - draft
      - published
    RenderRequestV1:
      type: object
      required:
      - templateId
      properties:
        templateId:
          type: string
          description: The template's generated internal id.
        data:
          type: object
          additionalProperties: true
        version:
          $ref: '#/components/schemas/VersionSelector'
    TemplateV1:
      allOf:
      - $ref: '#/components/schemas/TemplateSummaryV1'
      - type: object
        required:
        - userId
        properties:
          schema:
            type:
            - object
            - 'null'
            additionalProperties: true
          sampleData:
            type:
            - object
            - 'null'
            additionalProperties: true
          baseTemplateId:
            type:
            - string
            - 'null'
          userId:
            type: string
          organizationId:
            type:
            - string
            - 'null'
    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
    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.
    TemplateSummaryV1:
      type: object
      required:
      - id
      - name
      - status
      - createdAt
      - updatedAt
      properties:
        id:
          type: string
          description: Internal id.
        name:
          type: string
        description:
          type:
          - string
          - 'null'
        status:
          $ref: '#/components/schemas/TemplateStatus'
        createdAt:
          $ref: '#/components/schemas/Timestamp'
        updatedAt:
          $ref: '#/components/schemas/Timestamp'
  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
    Unauthorized:
      description: Missing, invalid or expired API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Unauthorized
    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'
    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
  parameters:
    templateIdV1:
      name: id
      in: path
      required: true
      schema:
        type: string
      description: The template's generated internal id.
    offset:
      name: offset
      in: query
      schema:
        type: integer
        minimum: 0
        default: 0
    logStatus:
      name: status
      in: query
      schema:
        type: string
        enum:
        - success
        - error
    logSource:
      name: source
      in: query
      schema:
        type: string
        enum:
        - api
        - ui
        - mcp
      description: Where the render was triggered from.
    limit:
      name: limit
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 200
        default: 50
    resolveImages:
      name: resolve_images
      in: query
      schema:
        type: string
        enum:
        - 'true'
      description: When `true`, image references in `sampleData` are resolved to fetchable URLs. Always on for templates built on a base template.
  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/