blinkpdf-io Account API

openapi: 3.2.0
info:
  title: Blink PDF Account 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: Account
  description: The authenticated caller account and billing tier
paths:
  /v1/account:
    get:
      tags:
      - Account
      summary: Identify the authenticated caller
      description: Returns the owning `account` and enforcement billing `tier` of the credential on this request, the same pair `POST /v1/render/validate` reports. It does not render, validate a document, meter usage, or take a concurrency slot, so a client can learn which account and per-tier limits apply before spending a render. A revoked or unknown credential returns **401**.
      operationId: getAccount
      security:
      - apiKey: []
      responses:
        '200':
          description: The caller account and its enforcement tier.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account.Identity'
        '401':
          description: A named error whose `error` is `unauthorized` (the `x-api-key` header is missing, or names no valid, enabled `bp_*` key).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error.unauthorized'
        '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
        '500':
          description: A named error whose `error` is `internal_error` (an unexpected server error).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error.internal_error'
        '503':
          description: A named error whose `error` is `service_unavailable` (API key validation or the subscription tier lookup is temporarily unavailable; retry shortly).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error.service_unavailable'
components:
  schemas:
    Error.service_unavailable:
      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: service_unavailable
          type: string
        detail:
          description: Caller-safe sentence naming the cause and the fix
          type: string
    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
    Account.Identity:
      description: 'The authenticated caller: its owning account and its enforcement billing tier'
      type: object
      required:
      - account
      - tier
      properties:
        account:
          description: 'Opaque owning account id: the same value `POST /v1/render/validate` returns as `account` and renders return in `x-blinkpdf-account`'
          type: string
        tier:
          description: 'The caller''s enforcement billing tier: the tier `POST /v1/render/validate` reports and the per-tier limits apply to'
          type: string
          enum:
          - free
          - pro
          - business
    Error.unauthorized:
      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: unauthorized
          type: string
        detail:
          description: Caller-safe sentence naming the cause and the fix
          type: string
    Error.internal_error:
      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: internal_error
          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.