pdfs-build Embedded editor API

openapi: 3.2.0
info:
  title: pdfs.build Embedded editor 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: Embedded editor
  description: 'Exchange an API key for a short-lived, template-scoped session token that mounts the editor in your product with `@pdfsbuild/react`. Requires the Platform (or a custom) plan. Guide: https://pdfs.build/embed/'
paths:
  /v2/organizations/{organizationId}/templates/{externalId}/embed-sessions:
    parameters:
    - $ref: '#/components/parameters/organizationId'
    - $ref: '#/components/parameters/externalId'
    post:
      tags:
      - Embedded editor
      summary: Create embedded editor session
      operationId: createEmbedSession
      description: Called from your backend. Exchanges the API key for a short-lived session token (`emb_...`) scoped to one template and one of your end users; your frontend mounts the editor with that token. Every AI turn in the session is metered against `externalTenantId`. Requires the Platform (or a custom) plan.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmbedSessionRequest'
      responses:
        '201':
          description: The session token. Hand `token` to the browser; never the API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmbedSession'
        '400':
          description: Invalid request body; `issues` describes each field.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationIssues'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: '`embedded_plan_required` or `organization_scope_mismatch`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: The template is not accessible to this key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          $ref: '#/components/responses/BackendUnavailable'
  /v2/organizations/{organizationId}/embed-sessions/{sessionId}:
    parameters:
    - $ref: '#/components/parameters/organizationId'
    - $ref: '#/components/parameters/sessionId'
    delete:
      tags:
      - Embedded editor
      summary: Revoke embedded editor session
      operationId: revokeEmbedSession
      description: Ends a session before it expires, e.g. when the end user signs out of your product.
      responses:
        '200':
          $ref: '#/components/responses/Ok'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/OrganizationScopeMismatch'
        '404':
          description: Unknown or already expired session.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Session not found
        '502':
          $ref: '#/components/responses/BackendUnavailable'
components:
  parameters:
    sessionId:
      name: sessionId
      in: path
      required: true
      schema:
        type: string
      description: Embedded session id, as returned when the session was created.
    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
  schemas:
    Ok:
      type: object
      required:
      - ok
      properties:
        ok:
          type: boolean
          const: true
    ValidationIssues:
      type: object
      required:
      - error
      - issues
      properties:
        error:
          type: string
        issues:
          type: object
          description: Per-field problems, keyed by field name.
          additionalProperties: true
    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.
    EmbedSession:
      type: object
      required:
      - sessionId
      - token
      - templateId
      - expiresAt
      properties:
        sessionId:
          type: string
        token:
          type: string
          description: Session token (`emb_...`) for `@pdfsbuild/react`. Scoped to this template and user.
        templateId:
          type: string
          description: The template's internal id — what the SDK addresses the document by.
        expiresAt:
          type: string
          format: date-time
    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.
    EmbedSessionRequest:
      type: object
      required:
      - externalTenantId
      - externalUserId
      properties:
        externalTenantId:
          type: string
          minLength: 1
          maxLength: 200
          description: Your customer's id. AI usage in the session is metered against it.
        externalUserId:
          type: string
          minLength: 1
          maxLength: 200
          description: The end user's id in your system, for attribution.
        expiresInSeconds:
          type: integer
          minimum: 60
          maximum: 3600
          description: Session lifetime.
  responses:
    BackendUnavailable:
      description: The service that owns this resource could not be reached. Safe to retry.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: embed_backend_unavailable
    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
    Ok:
      description: Done.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Ok'
    Unauthorized:
      description: Missing, invalid or expired API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Unauthorized
  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/