blinkpdf-io Discovery API

openapi: 3.2.0
info:
  title: Blink PDF Discovery API
  description: 'Render Markdown into accessible, PDF/UA-conformant PDFs over HTTP. Send Markdown plus optional document metadata, fonts, page layout, viewer hints, and per-block style overrides to `POST /v1/render`, or use a structured template such as `POST /v1/templates/sandwich-document/render` or `POST /v1/templates/layout-document/render`. Fill by name is a separate verb: template (PDF bytes or stored id) plus `{ name: value }` returns a filled PDF; it is not a second verb on `POST /v1/render`. Inspect the complete AcroForm hierarchy at `POST /v1/inspect`, dry-run at `POST /v1/validate-fill`, and fill at `POST /v1/fill`. `POST /v1/fill` streams the PDF and does not keep the output. Stored templates live at `/v1/templates` (store, list, update, delete, download); JSON get/patch/delete by id is gone. Each visible revision atomically binds immutable blank bytes, inspect, resources, and pins. Inspect describes unsupported document and field traits through capabilities and diagnostics; strict fill and template storage reject unsupported subsets. Names are ISO fully qualified names. Omitted names stay unchanged. `false` is a value. Unknown names reject the request. The filled PDF never includes `/NeedAppearances`. Fill is request/response: a live template PDF is one binary multipart part capped by the tier `maxTemplateBytes`, and produce has a 120 second ceiling. No job id. Authentication is via an `x-api-key` header. An unknown path returns HTTP 404 with the named error `not_found`. A method a registered path does not accept returns 405 `method_not_allowed` with an `Allow` header listing the methods that path accepts.'
  version: 5.0.0
  contact:
    name: Blink PDF Support
    email: support@blinkpdf.io
  license:
    name: Proprietary
    identifier: LicenseRef-Proprietary
servers:
- url: https://api.blinkpdf.io
  description: Production
tags:
- name: Discovery
  description: Machine-readable API entry point
paths:
  /openapi.json:
    get:
      tags:
      - Discovery
      summary: Public OpenAPI document
      description: This API's curated public OpenAPI document, the one `/docs` renders.
      operationId: publicOpenApiDocument
      responses:
        '405':
          description: A named error whose `error` is `method_not_allowed` (the path does not accept this method; the `Allow` header lists the ones it accepts).
          headers:
            Allow:
              schema:
                const: GET, HEAD
                type: string
              description: Methods this path accepts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error.method_not_allowed'
        '429':
          description: 'A named error whose `error` is `rate_limited` (the per-address flood shield in front of every route: too many requests from this client address; retry after `Retry-After`).'
          headers:
            Retry-After:
              schema:
                minimum: 1
                type: integer
              description: Seconds to wait before retrying; every 429 states it, and in a batch in which no item succeeded it is the first failed row's `retryAfterSeconds`
              required: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error.rate_limited'
              examples:
                rate_limited:
                  summary: '`rate_limited`'
                  value:
                    error: rate_limited
                    detail: Too many requests from this client address. Retry after the Retry-After interval.
                    retryAfterSeconds: 5
  /:
    get:
      tags:
      - Discovery
      summary: API entry point
      description: Unauthenticated discovery document naming the path of every operation this document publishes, keyed by surface. Every path except a URI template (`templateDownload`) is also advertised in the RFC 8288 `Link` response header. Fill is not a second verb on `POST /v1/render`.
      operationId: discoveryRoot
      responses:
        '200':
          description: Machine-readable entry point naming the path of every public API surface
          content:
            application/json:
              schema:
                additionalProperties: false
                description: Machine-readable entry point naming the path of every public API surface
                type: object
                required:
                - name
                - version
                - render
                - validate
                - compose
                - validateCompose
                - renderLayoutDocument
                - validateLayoutDocument
                - renderSandwichDocument
                - validateSandwichDocument
                - inspect
                - validateFill
                - fill
                - validateRewrite
                - rewrite
                - planRepair
                - pages
                - validatePages
                - stamp
                - read
                - templates
                - templateDownload
                - styleTargets
                - themes
                - fonts
                - account
                - openapi
                - apiReference
                - health
                - ready
                properties:
                  name:
                    description: Human-readable API name
                    type: string
                  version:
                    description: Deployed API version
                    type: string
                  render:
                    description: Path to render Markdown to a PDF (POST)
                    type: string
                  validate:
                    description: Path to validate a render body without rendering (POST)
                    type: string
                  compose:
                    description: Path to compose a canvas cover and a paginated stream body to a PDF (POST)
                    type: string
                  validateCompose:
                    description: Path to validate a compose body and report its layout without rendering (POST)
                    type: string
                  renderLayoutDocument:
                    description: Path to render the layout-document template to a PDF (POST)
                    type: string
                  validateLayoutDocument:
                    description: Path to validate a layout-document template body without rendering (POST)
                    type: string
                  renderSandwichDocument:
                    description: Path to render the sandwich-document template to a PDF (POST)
                    type: string
                  validateSandwichDocument:
                    description: Path to validate a sandwich-document template body without rendering (POST)
                    type: string
                  inspect:
                    description: Path to list fillable AcroForm fields (POST)
                    type: string
                  validateFill:
                    description: Path to dry-run a fill by name without writing a PDF (POST)
                    type: string
                  fill:
                    description: Path to fill an AcroForm by name (POST). Streams the PDF; does not keep the output
                    type: string
                  validateRewrite:
                    description: Path to compile a complete AcroForm replacement (POST)
                    type: string
                  rewrite:
                    description: Path to emit a validated AcroForm replacement (POST)
                    type: string
                  planRepair:
                    description: Path to analyze AcroForm quality and plan deterministic repairs (POST)
                    type: string
                  pages:
                    description: Path to build one PDF from the selected pages of existing PDFs (POST). Does not keep the output
                    type: string
                  validatePages:
                    description: 'Path to dry-run a page operation: its page count and diagnostics, without a PDF (POST)'
                    type: string
                  stamp:
                    description: Path to stamp text, images, and codes onto the pages of an existing PDF (POST)
                    type: string
                  read:
                    description: Path to read a native PDF as Markdown with the box of every line and its form values (POST)
                    type: string
                  templates:
                    description: 'Path to the stored AcroForm library: GET lists, POST stores, PATCH updates, DELETE removes'
                    type: string
                  templateDownload:
                    description: URI template (RFC 6570) of the PDF bytes of a stored AcroForm (GET); `{id}` is its template id
                    type: string
                  styleTargets:
                    description: Path to the styling vocabulary catalog (GET)
                    type: string
                  themes:
                    description: Path to the theme catalog the render `theme` field names (GET)
                    type: string
                  fonts:
                    description: Path to the hosted font catalog and Google Fonts limits (GET)
                    type: string
                  account:
                    description: Path to the authenticated caller account and billing tier (GET)
                    type: string
                  openapi:
                    description: Path to the curated public OpenAPI 3.1 document (GET; static artifact)
                    type: string
                  apiReference:
                    description: Path to the Scalar API reference shell (GET; static HTML)
                    type: string
                  health:
                    description: Path to the liveness probe (GET)
                    type: string
                  ready:
                    description: Path to the readiness probe (GET); 503 while the service drains
                    type: string
        '405':
          description: A named error whose `error` is `method_not_allowed` (the path does not accept this method; the `Allow` header lists the ones it accepts).
          headers:
            Allow:
              schema:
                const: GET, HEAD
                type: string
              description: Methods this path accepts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error.method_not_allowed'
        '429':
          description: 'A named error whose `error` is `rate_limited` (the per-address flood shield in front of every route: too many requests from this client address; retry after `Retry-After`).'
          headers:
            Retry-After:
              schema:
                minimum: 1
                type: integer
              description: Seconds to wait before retrying; every 429 states it, and in a batch in which no item succeeded it is the first failed row's `retryAfterSeconds`
              required: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error.rate_limited'
              examples:
                rate_limited:
                  summary: '`rate_limited`'
                  value:
                    error: rate_limited
                    detail: Too many requests from this client address. Retry after the Retry-After interval.
                    retryAfterSeconds: 5
components:
  schemas:
    Error.method_not_allowed:
      additionalProperties: false
      description: 'Named error: `error` names it, `detail` explains it, and the members its code declares follow.'
      type: object
      required:
      - error
      - detail
      properties:
        error:
          const: method_not_allowed
          type: string
        detail:
          description: Caller-safe sentence naming the cause and the fix
          type: string
    Error.rate_limited:
      additionalProperties: false
      description: 'Named error: `error` names it, `detail` explains it, and the members its code declares follow.'
      type: object
      required:
      - error
      - detail
      - retryAfterSeconds
      properties:
        error:
          const: rate_limited
          type: string
        detail:
          description: Caller-safe sentence naming the cause and the fix
          type: string
        retryAfterSeconds:
          minimum: 1
          description: Whole seconds to wait before retrying, the value of the `Retry-After` header when the response is the refusal
          type: integer
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: API key issued from your Blink PDF account, prefixed `bp_`. Send it in the `x-api-key` header on every operation whose `security` lists `apiKey`; an operation with empty `security` takes no key.