pdfs-build Delegated agents API

openapi: 3.2.0
info:
  title: pdfs.build Delegated agents 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: Delegated agents
  description: Let your customers connect their own AI assistant (over MCP) to the templates under their tenant scope. Requires the Platform plan, the organization opt-in, and an API key owned by an organization owner or admin.
paths:
  /v2/organizations/{organizationId}/delegated/tickets:
    parameters:
    - $ref: '#/components/parameters/organizationId'
    post:
      tags:
      - Delegated agents
      summary: Mint connect ticket
      operationId: createDelegatedTicket
      description: Mints a single-use connect code for one of your end users. Show them `connectCode` and `mcpServerUrl`; they add the MCP server to their assistant and paste the code on the consent screen. Redeeming it creates a delegated grant that can reach only templates whose `scopePath` starts with one of `scopePrefixes`, using only the tools in `allowedTools`. Every prefix must start with `externalTenantId/`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConnectTicketRequest'
      responses:
        '201':
          description: The ticket. `connectCode` is single-use and short-lived.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectTicket'
        '400':
          description: '`invalid_connect_ticket_request` (with `issues`) or `invalid_scope` (a prefix does not start with the tenant id, or an unknown tool).'
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/ValidationIssues'
                - $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/DelegatedForbidden'
        '502':
          $ref: '#/components/responses/BackendUnavailable'
  /v2/organizations/{organizationId}/delegated/grants:
    parameters:
    - $ref: '#/components/parameters/organizationId'
    get:
      tags:
      - Delegated agents
      summary: List delegated grants
      operationId: listDelegatedGrants
      description: Every connection your customers have made, including expired and revoked ones.
      responses:
        '200':
          description: Grants, newest first.
          content:
            application/json:
              schema:
                type: object
                required:
                - grants
                properties:
                  grants:
                    type: array
                    items:
                      $ref: '#/components/schemas/DelegatedGrant'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/DelegatedForbidden'
        '502':
          $ref: '#/components/responses/BackendUnavailable'
  /v2/organizations/{organizationId}/delegated/grants/{grantId}:
    parameters:
    - $ref: '#/components/parameters/organizationId'
    - $ref: '#/components/parameters/grantId'
    delete:
      tags:
      - Delegated agents
      summary: Revoke delegated grant
      operationId: revokeDelegatedGrant
      description: 'Cuts the connection immediately: the grant and every token issued for it are revoked.'
      responses:
        '200':
          $ref: '#/components/responses/Ok'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/DelegatedForbidden'
        '404':
          description: Unknown grant, or already revoked.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Grant not found or already revoked
        '502':
          $ref: '#/components/responses/BackendUnavailable'
components:
  schemas:
    Ok:
      type: object
      required:
      - ok
      properties:
        ok:
          type: boolean
          const: true
    DelegatedGrant:
      type: object
      required:
      - id
      - externalTenantId
      - externalUserId
      - scopePrefixes
      - allowedTools
      - label
      - expiresAt
      - revokedAt
      - lastUsedAt
      - createdAt
      properties:
        id:
          type: string
        externalTenantId:
          type: string
        externalUserId:
          type: string
        scopePrefixes:
          type: array
          items:
            type: string
        allowedTools:
          type: array
          items:
            type: string
        label:
          type: string
        expiresAt:
          type:
          - string
          - 'null'
          format: date-time
        revokedAt:
          type:
          - string
          - 'null'
          format: date-time
        lastUsedAt:
          type:
          - string
          - 'null'
          format: date-time
        createdAt:
          type: string
          format: date-time
    ValidationIssues:
      type: object
      required:
      - error
      - issues
      properties:
        error:
          type: string
        issues:
          type: object
          description: Per-field problems, keyed by field name.
          additionalProperties: true
    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.
    ConnectTicketRequest:
      type: object
      required:
      - externalTenantId
      - externalUserId
      - scopePrefixes
      properties:
        externalTenantId:
          type: string
          minLength: 1
          maxLength: 200
          description: Billing boundary. Must equal the first segment of every prefix.
        externalUserId:
          type: string
          minLength: 1
          maxLength: 200
        scopePrefixes:
          type: array
          minItems: 1
          maxItems: 50
          items:
            type: string
            minLength: 1
            maxLength: 512
          description: 'Access boundary: the grant reaches templates whose `scopePath` starts with any of these.'
          example:
          - acct_9f3/entity_dubai/
          - acct_9f3/entity_ajman/
        allowedTools:
          type: array
          maxItems: 50
          items:
            type: string
          description: MCP tools the grant may call. Defaults to the delegated allowlist; tools that escalate access (schema writes, publishing, API keys) are always denied.
        label:
          type: string
          maxLength: 200
          description: Shown in your connection list.
        expiresInSeconds:
          type: integer
          minimum: 60
          maximum: 1800
          description: Ticket lifetime (default 10 minutes).
        grantExpiresInSeconds:
          type: integer
          minimum: 3600
          maximum: 31536000
          description: Lifetime of the grant created when the ticket is redeemed.
    ConnectTicket:
      type: object
      required:
      - ticketId
      - connectCode
      - mcpServerUrl
      - expiresAt
      properties:
        ticketId:
          type: string
        connectCode:
          type: string
          description: Show this to the end user (`dct_...`). Single use.
        mcpServerUrl:
          type: string
          format: uri
          example: https://backend.pdfs.build/mcp
        expiresAt:
          type: string
          format: date-time
  parameters:
    grantId:
      name: grantId
      in: path
      required: true
      schema:
        type: string
      description: Delegated grant id.
    organizationId:
      name: organizationId
      in: path
      required: true
      schema:
        type: string
      description: Your organization id. Must match the API key's organization.
      example: org_abc
  responses:
    DelegatedForbidden:
      description: '`admin_required` (the key''s owner is not an organization owner/admin), `delegated_plan_required`, `delegated_access_disabled` (the organization has not opted in), or `organization_scope_mismatch`.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    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
    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/