BrewMyPDF API

openapi: 3.1.0
info:
  title: BrewMyPDF API
  version: '2026-11-03'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-11-03: 28 operation(s) read from 8 public documentation page(s) (each operation
    names its page in x-source). This is not the provider''s published contract; BrewMyPDF has published no machine-readable contract that the
    pipeline could find. Engine: local.'
  x-evidence-tiers:
    code-example: 2
    documentation: 26
    pages-with-code: 2
    pages-read: 8
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-11-03'
  x-generator: generate-contract-from-docs.py
  x-engine: local
  x-sources:
  - https://brewmypdf.com/docs/api
  - https://brewmypdf.com/docs/schema
  - https://brewmypdf.com/docs/mcp
  - https://brewmypdf.com/docs/handson/credit-note
  - https://brewmypdf.com/docs/handson/payslip
  - https://brewmypdf.com/docs/handson/contract
  - https://brewmypdf.com/docs/handson/delivery-note
  - https://brewmypdf.com/docs/handson/shipping-label
paths:
  /mcp:
    post:
      operationId: post_mcp
      tags:
      - Mcp
      summary: Using BrewMyPDF from an AI agent (MCP)
      x-source: https://brewmypdf.com/docs/mcp
      parameters:
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
        description: Bearer token containing your API key (different header name from the REST API).
      - name: content-type
        in: header
        required: true
        schema:
          type: string
        description: Must be set to application/json.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostMcpRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostMcpResponse'
      x-evidence:
        kind: documentation
  /v1/account:
    get:
      operationId: get_v1_account
      tags:
      - Account
      summary: Test the key with GET /v1/account — it is cheap and has no side effects.
      x-source: https://brewmypdf.com/docs/api
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/assets:
    post:
      operationId: post_v1_assets
      tags:
      - Assets
      summary: Upload a background image with POST /v1/assets.
      x-source: https://brewmypdf.com/docs/api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1AssetsRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1AssetsResponse'
      x-evidence:
        kind: documentation
  /v1/assets/{id}:
    delete:
      operationId: delete_v1_assets_id
      tags:
      - Assets
      summary: Delete with DELETE /v1/assets/{id}.
      x-source: https://brewmypdf.com/docs/api
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteV1AssetsIdResponse'
      x-evidence:
        kind: documentation
  /v1/batch:
    post:
      operationId: post_v1_batch
      tags:
      - Batch
      summary: Many at once POST /v1/batch takes an items array — up to 50 — and queues them together.
      x-source: https://brewmypdf.com/docs/api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1BatchRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1BatchResponse'
      x-evidence:
        kind: documentation
  /v1/create:
    post:
      operationId: post_v1_create
      tags:
      - Create
      summary: Render now POST /v1/create renders and answers in the same request.
      x-source: https://brewmypdf.com/docs/api
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1CreateRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1CreateResponse'
      x-evidence:
        kind: documentation
  /v1/create-async:
    post:
      operationId: post_v1_create_async
      tags:
      - Create Async
      summary: POST /v1/create-async
      x-source: https://brewmypdf.com/docs/api
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: 'curl -X POST https://brewmypdf.com/v1/create-async  -H "x-api-key: bmp_live_..."  -H "content-type: application/json"  --data-binary
          @invoice.json'
  /v1/embed/sessions:
    post:
      operationId: post_v1_embed_sessions
      tags:
      - Embed
      summary: POST /v1/embed/sessions creates an embed session for the editor.
      x-source: https://brewmypdf.com/docs/api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1EmbedSessionsRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1EmbedSessionsResponse'
      x-evidence:
        kind: documentation
  /v1/files:
    post:
      operationId: post_v1_files
      tags:
      - Files
      summary: 'Upload a PDF with POST /v1/files — put the PDF straight in the body with content-type: application/pdf.'
      x-source: https://brewmypdf.com/docs/api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1FilesRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1FilesResponse'
      x-evidence:
        kind: documentation
  /v1/files/{id}:
    get:
      operationId: get_v1_files_id
      tags:
      - Files
      summary: 'GET /v1/files/{id} tells you what the file is: how many pages, the size and rotation of each one, whether it is encrypted, whether
        it carries an XFA form, and the names of any form fields inside.'
      x-source: https://brewmypdf.com/docs/api
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1FilesIdResponse'
      x-evidence:
        kind: documentation
  /v1/intake/runs:
    post:
      operationId: post_v1_intake_runs
      tags:
      - Intake
      summary: POST /v1/intake/runs takes documents folded into data objects for spreadsheet intake.
      x-source: https://brewmypdf.com/docs/api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1IntakeRunsRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1IntakeRunsResponse'
      x-evidence:
        kind: documentation
  /v1/intake/runs/{id}:
    get:
      operationId: get_v1_intake_runs_id
      tags:
      - Intake
      summary: GET /v1/intake/runs/{id} returns status and URLs for a finished intake run.
      x-source: https://brewmypdf.com/docs/api
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1IntakeRunsIdResponse'
      x-evidence:
        kind: documentation
  /v1/intake/runs/{id}/zip:
    post:
      operationId: post_v1_intake_runs_id_zip
      tags:
      - Intake
      summary: POST /v1/intake/runs/{id}/zip builds that ZIP for a finished run — streamed to storage, up to 500 MB in total.
      x-source: https://brewmypdf.com/docs/api
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/jobs/01M0:
    post:
      operationId: post_v1_jobs_01M0
      tags:
      - Jobs
      summary: POST /v1/jobs/01M0
      x-source: https://brewmypdf.com/docs/api
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: 'curl https://brewmypdf.com/v1/jobs/01M0...  -H "x-api-key: bmp_live_..." Many at once POST /v1/batch takes an items array —
          up to 50 — and queues them together. Each item carries its own template or template_id and its own data, so one call can render a statement
          for every customer. The response is a list of job ids; collect each result from /v1/jobs/{id}. It never waits, because waiting on fifty '
  /v1/jobs/{id}:
    get:
      operationId: get_v1_jobs_id
      tags:
      - Jobs
      summary: GET /v1/jobs/{id} reports the state and, once done, the same signed URL.
      x-source: https://brewmypdf.com/docs/api
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1JobsIdResponse'
      x-evidence:
        kind: documentation
  /v1/jobs/{id}/retry:
    post:
      operationId: post_v1_jobs_id_retry
      tags:
      - Jobs
      summary: A failed job can be run again with POST /v1/jobs/{id}/retry.
      x-source: https://brewmypdf.com/docs/api
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1JobsIdRetryResponse'
      x-evidence:
        kind: documentation
  /v1/pdf/fields:
    post:
      operationId: post_v1_pdf_fields
      tags:
      - Pdf
      summary: POST /v1/pdf/fields fills in form fields that already exist.
      x-source: https://brewmypdf.com/docs/api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1PdfFieldsRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1PdfFieldsResponse'
      x-evidence:
        kind: documentation
  /v1/pdf/merge:
    post:
      operationId: post_v1_pdf_merge
      tags:
      - Pdf
      summary: POST /v1/pdf/merge joins files in the order you list them, up to 20.
      x-source: https://brewmypdf.com/docs/api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1PdfMergeRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1PdfMergeResponse'
      x-evidence:
        kind: documentation
  /v1/pdf/stamp:
    post:
      operationId: post_v1_pdf_stamp
      tags:
      - Pdf
      summary: POST /v1/pdf/stamp writes text onto a file.
      x-source: https://brewmypdf.com/docs/api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1PdfStampRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1PdfStampResponse'
      x-evidence:
        kind: documentation
  /v1/templates:
    get:
      operationId: get_v1_templates
      tags:
      - Templates
      summary: Fill a template dropdown with GET /v1/templates.
      x-source: https://brewmypdf.com/docs/api
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: string
        description: Maximum number of templates to return, up to 200
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1TemplatesResponse'
      x-evidence:
        kind: documentation
    post:
      operationId: post_v1_templates
      tags:
      - Templates
      summary: POST /v1/templates creates one from { name, doc } and returns template_id and version_id.
      x-source: https://brewmypdf.com/docs/api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1TemplatesRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1TemplatesResponse'
      x-evidence:
        kind: documentation
  /v1/templates/{id}:
    delete:
      operationId: delete_v1_templates_id
      tags:
      - Templates
      summary: DELETE /v1/templates/{id} is a soft delete — past renders keep their history.
      x-source: https://brewmypdf.com/docs/api
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
    get:
      operationId: get_v1_templates_id
      tags:
      - Templates
      summary: GET /v1/templates/{id} returns the template with its current doc and schema_version.
      x-source: https://brewmypdf.com/docs/api
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1TemplatesIdResponse'
      x-evidence:
        kind: documentation
    put:
      operationId: put_v1_templates_id
      tags:
      - Templates
      summary: 'PUT /v1/templates/{id} updates it: pass doc to write a new version, name to rename, or both.'
      x-source: https://brewmypdf.com/docs/api
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PutV1TemplatesIdRequest'
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/templates/{id}/form:
    get:
      operationId: get_v1_templates_id_form
      tags:
      - Templates
      summary: GET /v1/templates/{id}/form?format=xlsx (or csv) returns the data form for spreadsheet intake.
      x-source: https://brewmypdf.com/docs/api
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: format
        in: query
        required: false
        schema:
          type: string
        description: xlsx or csv
      - name: sheet
        in: query
        required: false
        schema:
          type: string
        description: Sheet name for csv format
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/templates/{id}/schema:
    get:
      operationId: get_v1_templates_id_schema
      tags:
      - Templates
      summary: GET /v1/templates/{id}/schema returns the template schema (paths and JSON Schema).
      x-source: https://brewmypdf.com/docs/api
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/templates/{id}/versions:
    get:
      operationId: get_v1_templates_id_versions
      tags:
      - Templates
      summary: GET /v1/templates/{id}/versions lists versions (without doc bodies — newest first, current marked).
      x-source: https://brewmypdf.com/docs/api
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1TemplatesIdVersionsResponse'
      x-evidence:
        kind: documentation
  /v1/templates/{id}/versions/{vid}/restore:
    post:
      operationId: post_v1_templates_id_versions_vid_restore
      tags:
      - Templates
      summary: POST /v1/templates/{id}/versions/{vid}/restore makes an older version current again.
      x-source: https://brewmypdf.com/docs/api
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: vid
        in: path
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
components:
  schemas:
    PostMcpRequest:
      type: object
      properties:
        jsonrpc:
          type: string
          description: JSON-RPC version, always "2.0".
        id:
          type: integer
          description: Client‑generated request identifier.
        method:
          type: string
          description: One of the MCP tools, e.g., "tools/list".
        params:
          type: object
          description: Parameters required by the chosen method.
      required:
      - jsonrpc
      - id
      - method
    PostMcpResponse:
      type: object
      properties:
        jsonrpc:
          type: string
          description: JSON-RPC version, "2.0".
        id:
          type: integer
          description: Matches the request id.
        result:
          type: object
          description: Successful response payload specific to the called method.
        error:
          type: object
          description: Error object when the call fails (contains code and message).
    PostV1AssetsRequest:
      type: object
      properties:
        file:
          type: string
          description: image file, content-type image/jpeg or image/png
      required:
      - file
    PostV1AssetsResponse:
      type: object
      properties:
        ok:
          type: boolean
        asset_id:
          type: string
    DeleteV1AssetsIdResponse:
      type: object
      properties:
        ok:
          type: boolean
    PostV1BatchRequest:
      type: object
      properties:
        items:
          type: array
          description: each item has its own template or template_id and data
        merge:
          type: boolean
          description: if true, returns one merged PDF
      required:
      - items
    PostV1BatchResponse:
      type: object
      properties:
        ok:
          type: boolean
        ids:
          type: array
          description: list of job ids
        url:
          type: string
          description: download URL when merge=true
    PostV1CreateRequest:
      type: object
      properties:
        template:
          type: object
        template_id:
          type: string
        data:
          type: object
        format:
          type: string
          description: png or jpeg for image output
        quality:
          type: integer
          description: 1‑100 for jpeg
    PostV1CreateResponse:
      type: object
      properties:
        ok:
          type: boolean
        id:
          type: string
        format:
          type: string
        url:
          type: string
        expiresAt:
          type: integer
    PostV1EmbedSessionsRequest:
      type: object
      properties:
        template_id:
          type: string
        mode:
          type: string
          description: '"edit" or "view"'
        ttl_seconds:
          type: integer
          description: Lifetime of the session, defaults to 15 minutes, max 1 hour
      required:
      - template_id
      - mode
    PostV1EmbedSessionsResponse:
      type: object
      properties:
        url:
          type: string
          description: Short‑lived URL to embed
    PostV1FilesRequest:
      type: object
      properties:
        file:
          type: string
          description: PDF file
      required:
      - file
    PostV1FilesResponse:
      type: object
      properties:
        ok:
          type: boolean
        file_id:
          type: string
    GetV1FilesIdResponse:
      type: object
      properties:
        pages:
          type: integer
        size:
          type: integer
        rotation:
          type: integer
        encrypted:
          type: boolean
        xfa:
          type: boolean
        fields:
          type: array
          description: field names
    PostV1IntakeRunsRequest:
      type: object
      properties:
        template_id:
          type: string
        hash:
          type: string
        total:
          type: integer
        seq_start:
          type: integer
        docs:
          type: array
          description: Array of { key, data } objects
        run_id:
          type: string
          description: Omit on first chunk
      required:
      - template_id
      - hash
      - total
      - seq_start
      - docs
    PostV1IntakeRunsResponse:
      type: object
      properties:
        run_id:
          type: string
    GetV1IntakeRunsIdResponse:
      type: object
      properties:
        status:
          type: string
        counts:
          type: object
        signed_url:
          type: string
        zip_url:
          type: string
    GetV1JobsIdResponse:
      type: object
      properties:
        ok:
          type: boolean
        status:
          type: string
        url:
          type: string
          description: signed download URL when done
        error_code:
          type: string
          description: when failed
    PostV1JobsIdRetryResponse:
      type: object
      properties:
        ok:
          type: boolean
        id:
          type: string
    PostV1PdfFieldsRequest:
      type: object
      properties:
        file_id:
          type: string
        values:
          type: object
          description: field name/value pairs
        flatten:
          type: boolean
      required:
      - file_id
      - values
    PostV1PdfFieldsResponse:
      type: object
      properties:
        ok:
          type: boolean
        filled:
          type: array
          description: fields successfully filled
        missing:
          type: array
          description: fields not present
        rejected:
          type: array
          description: values not written
        url:
          type: string
          description: download URL of result
    PostV1PdfMergeRequest:
      type: object
      properties:
        file_ids:
          type: array
          description: list of uploaded file IDs
      required:
      - file_ids
    PostV1PdfMergeResponse:
      type: object
      properties:
        ok:
          type: boolean
        url:
          type: string
    PostV1PdfStampRequest:
      type: object
      properties:
        file_id:
          type: string
        text:
          type: string
        pages:
          type: array
          description: 1‑based page numbers
        x:
          type: number
        y:
          type: number
        size:
          type: number
        opacity:
          type: number
        rotate:
          type: number
        color:
          type: string
      required:
      - file_id
      - text
    PostV1PdfStampResponse:
      type: object
      properties:
        ok:
          type: boolean
        url:
          type: string
    GetV1TemplatesResponse:
      type: object
      properties:
        id:
          type: string
          description: Template identifier
        name:
          type: string
          description: Template name
        timestamps:
          type: object
          description: Creation and update timestamps
    PostV1TemplatesRequest:
      type: object
      properties:
        name:
          type: string
          description: Name of the template
        doc:
          type: object
          description: Template document JSON
      required:
      - name
      - doc
    PostV1TemplatesResponse:
      type: object
      properties:
        template_id:
          type: string
          description: Created template identifier
        version_id:
          type: string
          description: Initial version identifier
    GetV1TemplatesIdResponse:
      type: object
      properties:
        id:
          type: string
        doc:
          type: object
        schema_version:
          type: string
    PutV1TemplatesIdRequest:
      type: object
      properties:
        name:
          type: string
          description: New name for the template
        doc:
          type: object
          description: New document JSON
    GetV1TemplatesIdVersionsResponse:
      type: object
      properties:
        versions:
          type: array
          description: List of version objects
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
security:
- apiKey: []
tags:
- name: Account
- name: Assets
- name: Batch
- name: Create
- name: Create Async
- name: Embed
- name: Files
- name: Intake
- name: Jobs
- name: Mcp
- name: Pdf
- name: Templates