> ## Documentation Index > Fetch the complete documentation index at: https://docs.blinkpdf.io/llms.txt > Use this file to discover all available pages before exploring further. # Render a sandwich document > Renders a sandwich-style PDF where a header (logo, professional identity, subject/context data) appears only on the first page and a footer (signature, name) appears only on the last page. Header and footer assets are provided as inline `data:image/...;base64,...` strings. The Markdown body is rendered normally, with remote images subject to strict security policies (private IP rejection and mixed-content disabled). ## OpenAPI ````yaml /openapi.json post /v1/templates/sandwich-document/render openapi: 3.1.0 info: title: Blink PDF 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`. Authentication is via an `x-api-key` header. Unknown routes return HTTP 404 with body `{ "error": "not_found" }`. version: 1.3.1 contact: name: Blink PDF Support email: support@blinkpdf.io license: name: Proprietary identifier: LicenseRef-Proprietary servers: - url: https://api.blinkpdf.io description: Production security: [] tags: - name: Discovery description: Machine-readable API entry point - name: Health description: Liveness probes - name: Render description: Markdown-to-PDF rendering - name: Fonts description: Hosted font catalog and Google Fonts capability discovery - name: SandwichDocument description: >- Sandwich documents — a first-page header (logo, professional identity, subject/context data) and a last-page footer (signature, name) wrapping a Markdown body paths: /v1/templates/sandwich-document/render: post: tags: - SandwichDocument summary: Render a sandwich document description: >- Renders a sandwich-style PDF where a header (logo, professional identity, subject/context data) appears only on the first page and a footer (signature, name) appears only on the last page. Header and footer assets are provided as inline `data:image/...;base64,...` strings. The Markdown body is rendered normally, with remote images subject to strict security policies (private IP rejection and mixed-content disabled). operationId: render_sandwich_document requestBody: description: >- Sandwich document: a first-page header (logo, professional identity, subject and document context), a Markdown body, and a last-page footer (optional signature, divider, professional name). Image assets (logo, signature) are inlined as `data:` URLs. Page-1 body clearance uses a flow offset for the header band; bottom margins reserve the repeating page-footer band and, when the last-page signature would not fit under the body, the signature band as well. content: application/json: schema: $ref: '#/components/schemas/Template.sandwich-document.Body' required: true responses: '200': description: >- PDF bytes. Metered like `POST /v1/render` (usage, spend-cap, tier rate/concurrency). Diagnostics via `X-Render-Status` / `X-Render-Diagnostics`. `X-Template-Version` is `1.0.0`. Successful responses include wall-clock `X-Render-Ms`. Template routes do not use the process-local 60s PDF LRU, so `X-BlinkPDF-Cache` is not set. headers: X-Render-Status: schema: type: string enum: - ok - degraded description: >- Whether the PDF rendered without warn- or error-level issues (`degraded` when any warn/error diagnostic was emitted). X-Render-Rendered-As-Requested: schema: type: string enum: - 'true' - 'false' description: >- `false` when error-severity issues changed the document (for example missing images or glyphs); `true` otherwise. X-Render-Diagnostics: schema: type: string description: >- Base64url-encoded UTF-8 JSON array of actionable diagnostics when any were emitted. Omitted on a clean render. X-Render-Diagnostics-Summary: schema: type: string description: >- Plain-text companion to `X-Render-Diagnostics`. Present whenever `X-Render-Diagnostics` is. X-Render-Ms: schema: type: integer minimum: 0 description: >- Wall-clock milliseconds from when the template handler begins font resolution and PDF generation until the successful 200 response is ready, including font stack resolution, template render, usage metering, and header assembly. Omitted on non-200 responses. Template routes do not consult the process-local PDF LRU, so this value always reflects a full render path. X-Template-Version: schema: type: string description: Semver of this template contract (`1.0.0`). content: application/pdf: schema: type: string format: binary '400': $ref: '#/components/responses/Responses.BadRequest' '401': $ref: '#/components/responses/Responses.Unauthorized' '402': $ref: '#/components/responses/Responses.SpendCapReached' '405': $ref: '#/components/responses/Responses.MethodNotAllowed' '413': $ref: '#/components/responses/Responses.PayloadTooLarge' '429': $ref: '#/components/responses/Responses.RateLimited' '500': $ref: '#/components/responses/Responses.InternalError' '503': $ref: '#/components/responses/Responses.SourceUnavailable' security: - apiKey: [] components: schemas: Template.sandwich-document.Body: additionalProperties: false description: >- Sandwich document: a first-page header (logo, professional identity, subject and document context), a Markdown body, and a last-page footer (optional signature, divider, professional name). Image assets (logo, signature) are inlined as `data:` URLs. Page-1 body clearance uses a flow offset for the header band; bottom margins reserve the repeating page-footer band and, when the last-page signature would not fit under the body, the signature band as well. type: object required: - markdown - metadata - header - footer properties: markdown: minLength: 0 maxLength: 262144 description: Markdown source rendered as the body between header and footer type: string metadata: additionalProperties: false description: >- PDF document metadata embedded in the rendered file. Visible to any reader of the PDF — never include confidential or sensitive personal data, secrets, or other sensitive information. type: object required: - title properties: title: minLength: 1 maxLength: 1024 pattern: \S description: Document title embedded in the PDF metadata type: string author: minLength: 1 maxLength: 1024 pattern: \S description: Document author embedded in the PDF metadata type: string subject: minLength: 1 maxLength: 1024 pattern: \S description: Document subject embedded in the PDF metadata type: string keywords: maxItems: 32 description: Keywords embedded in the PDF metadata type: array items: minLength: 1 maxLength: 256 pattern: \S description: A single keyword type: string creator: minLength: 1 maxLength: 1024 pattern: \S description: Name of the application that authored the source document type: string creationDate: format: date-time pattern: >- ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,9})?(Z|[+-]\d{2}:\d{2})$ description: Creation timestamp as an ISO 8601 date-time type: string modificationDate: format: date-time pattern: >- ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,9})?(Z|[+-]\d{2}:\d{2})$ description: Last-modification timestamp as an ISO 8601 date-time type: string trapped: type: string enum: - 'true' - 'false' - unknown header: additionalProperties: false type: object required: - professional - subject - context properties: professional: additionalProperties: false type: object required: - name - logo properties: prefix: anyOf: - minLength: 0 maxLength: 1024 description: >- Plain text rendered with the theme defaults; may be empty type: string - additionalProperties: false type: object required: - text properties: text: minLength: 0 maxLength: 1024 description: Text content to render; may be empty type: string fontRole: description: >- Font weight and style to apply to this text within the active font stack anyOf: - const: regular type: string - const: bold type: string - const: italic type: string - const: boldItalic type: string fontSize: minimum: 1 maximum: 999 description: Font size in PDF points; defaults to the theme value type: number color: pattern: ^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$ description: Color as a 3- or 6-digit hex code, e.g. `#1a73e8` type: string description: Honorific or title shown before the name, e.g. `Dr.` name: anyOf: - minLength: 0 maxLength: 1024 description: >- Plain text rendered with the theme defaults; may be empty type: string - additionalProperties: false type: object required: - text properties: text: minLength: 0 maxLength: 1024 description: Text content to render; may be empty type: string fontRole: description: >- Font weight and style to apply to this text within the active font stack anyOf: - const: regular type: string - const: bold type: string - const: italic type: string - const: boldItalic type: string fontSize: minimum: 1 maximum: 999 description: Font size in PDF points; defaults to the theme value type: number color: pattern: ^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$ description: Color as a 3- or 6-digit hex code, e.g. `#1a73e8` type: string description: Professional first or given name lastName: anyOf: - minLength: 0 maxLength: 1024 description: >- Plain text rendered with the theme defaults; may be empty type: string - additionalProperties: false type: object required: - text properties: text: minLength: 0 maxLength: 1024 description: Text content to render; may be empty type: string fontRole: description: >- Font weight and style to apply to this text within the active font stack anyOf: - const: regular type: string - const: bold type: string - const: italic type: string - const: boldItalic type: string fontSize: minimum: 1 maximum: 999 description: Font size in PDF points; defaults to the theme value type: number color: pattern: ^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$ description: Color as a 3- or 6-digit hex code, e.g. `#1a73e8` type: string description: Professional family or last name logo: pattern: >- ^data:image/(png|jpeg|jpg|gif|tiff|svg\+xml);base64,[A-Za-z0-9+/=]+$ maxLength: 4194304 description: Logo image shown in the header type: string credentials: minItems: 0 maxItems: 16 description: >- Credentials rendered as a compact identity line under the name type: array items: additionalProperties: false type: object required: - title - institution - identifier properties: title: anyOf: - minLength: 0 maxLength: 1024 description: >- Plain text rendered with the theme defaults; may be empty type: string - additionalProperties: false type: object required: - text properties: text: minLength: 0 maxLength: 1024 description: Text content to render; may be empty type: string fontRole: description: >- Font weight and style to apply to this text within the active font stack anyOf: - const: regular type: string - const: bold type: string - const: italic type: string - const: boldItalic type: string fontSize: minimum: 1 maximum: 999 description: >- Font size in PDF points; defaults to the theme value type: number color: pattern: ^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$ description: >- Color as a 3- or 6-digit hex code, e.g. `#1a73e8` type: string description: Qualification or credential title institution: anyOf: - minLength: 0 maxLength: 1024 description: >- Plain text rendered with the theme defaults; may be empty type: string - additionalProperties: false type: object required: - text properties: text: minLength: 0 maxLength: 1024 description: Text content to render; may be empty type: string fontRole: description: >- Font weight and style to apply to this text within the active font stack anyOf: - const: regular type: string - const: bold type: string - const: italic type: string - const: boldItalic type: string fontSize: minimum: 1 maximum: 999 description: >- Font size in PDF points; defaults to the theme value type: number color: pattern: ^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$ description: >- Color as a 3- or 6-digit hex code, e.g. `#1a73e8` type: string description: Issuing institution identifier: anyOf: - minLength: 0 maxLength: 1024 description: >- Plain text rendered with the theme defaults; may be empty type: string - additionalProperties: false type: object required: - text properties: text: minLength: 0 maxLength: 1024 description: Text content to render; may be empty type: string fontRole: description: >- Font weight and style to apply to this text within the active font stack anyOf: - const: regular type: string - const: bold type: string - const: italic type: string - const: boldItalic type: string fontSize: minimum: 1 maximum: 999 description: >- Font size in PDF points; defaults to the theme value type: number color: pattern: ^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$ description: >- Color as a 3- or 6-digit hex code, e.g. `#1a73e8` type: string description: License, registration, or credential identifier registrations: minItems: 0 maxItems: 16 description: Registry entries rendered alongside the credentials type: array items: additionalProperties: false type: object required: - label - value properties: label: anyOf: - minLength: 0 maxLength: 1024 description: >- Plain text rendered with the theme defaults; may be empty type: string - additionalProperties: false type: object required: - text properties: text: minLength: 0 maxLength: 1024 description: Text content to render; may be empty type: string fontRole: description: >- Font weight and style to apply to this text within the active font stack anyOf: - const: regular type: string - const: bold type: string - const: italic type: string - const: boldItalic type: string fontSize: minimum: 1 maximum: 999 description: >- Font size in PDF points; defaults to the theme value type: number color: pattern: ^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$ description: >- Color as a 3- or 6-digit hex code, e.g. `#1a73e8` type: string description: Registry name or identifier label value: anyOf: - minLength: 0 maxLength: 1024 description: >- Plain text rendered with the theme defaults; may be empty type: string - additionalProperties: false type: object required: - text properties: text: minLength: 0 maxLength: 1024 description: Text content to render; may be empty type: string fontRole: description: >- Font weight and style to apply to this text within the active font stack anyOf: - const: regular type: string - const: bold type: string - const: italic type: string - const: boldItalic type: string fontSize: minimum: 1 maximum: 999 description: >- Font size in PDF points; defaults to the theme value type: number color: pattern: ^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$ description: >- Color as a 3- or 6-digit hex code, e.g. `#1a73e8` type: string description: Registry number or value description: Professional identity shown at the top of the first page subject: additionalProperties: false type: object required: - items properties: sectionTitle: anyOf: - minLength: 0 maxLength: 1024 description: >- Plain text rendered with the theme defaults; may be empty type: string - additionalProperties: false type: object required: - text properties: text: minLength: 0 maxLength: 1024 description: Text content to render; may be empty type: string fontRole: description: >- Font weight and style to apply to this text within the active font stack anyOf: - const: regular type: string - const: bold type: string - const: italic type: string - const: boldItalic type: string fontSize: minimum: 1 maximum: 999 description: Font size in PDF points; defaults to the theme value type: number color: pattern: ^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$ description: Color as a 3- or 6-digit hex code, e.g. `#1a73e8` type: string description: Optional heading rendered above the rows items: minItems: 0 maxItems: 32 description: Label/value rows rendered as a grid type: array items: additionalProperties: false type: object required: - label - value properties: label: anyOf: - minLength: 0 maxLength: 1024 description: >- Plain text rendered with the theme defaults; may be empty type: string - additionalProperties: false type: object required: - text properties: text: minLength: 0 maxLength: 1024 description: Text content to render; may be empty type: string fontRole: description: >- Font weight and style to apply to this text within the active font stack anyOf: - const: regular type: string - const: bold type: string - const: italic type: string - const: boldItalic type: string fontSize: minimum: 1 maximum: 999 description: >- Font size in PDF points; defaults to the theme value type: number color: pattern: ^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$ description: >- Color as a 3- or 6-digit hex code, e.g. `#1a73e8` type: string description: Row label, shown before the value value: anyOf: - minLength: 0 maxLength: 1024 description: >- Plain text rendered with the theme defaults; may be empty type: string - additionalProperties: false type: object required: - text properties: text: minLength: 0 maxLength: 1024 description: Text content to render; may be empty type: string fontRole: description: >- Font weight and style to apply to this text within the active font stack anyOf: - const: regular type: string - const: bold type: string - const: italic type: string - const: boldItalic type: string fontSize: minimum: 1 maximum: 999 description: >- Font size in PDF points; defaults to the theme value type: number color: pattern: ^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$ description: >- Color as a 3- or 6-digit hex code, e.g. `#1a73e8` type: string description: Row value, shown after the label visible: description: >- When `false`, the row is omitted from the rendered section; defaults to shown type: boolean description: >- Subject profile section rendered as a label/value grid (client, party, patient, etc.) context: additionalProperties: false type: object required: - items properties: sectionTitle: anyOf: - minLength: 0 maxLength: 1024 description: >- Plain text rendered with the theme defaults; may be empty type: string - additionalProperties: false type: object required: - text properties: text: minLength: 0 maxLength: 1024 description: Text content to render; may be empty type: string fontRole: description: >- Font weight and style to apply to this text within the active font stack anyOf: - const: regular type: string - const: bold type: string - const: italic type: string - const: boldItalic type: string fontSize: minimum: 1 maximum: 999 description: Font size in PDF points; defaults to the theme value type: number color: pattern: ^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$ description: Color as a 3- or 6-digit hex code, e.g. `#1a73e8` type: string description: Optional heading rendered above the rows items: minItems: 0 maxItems: 32 description: Label/value rows rendered as a grid type: array items: additionalProperties: false type: object required: - label - value properties: label: anyOf: - minLength: 0 maxLength: 1024 description: >- Plain text rendered with the theme defaults; may be empty type: string - additionalProperties: false type: object required: - text properties: text: minLength: 0 maxLength: 1024 description: Text content to render; may be empty type: string fontRole: description: >- Font weight and style to apply to this text within the active font stack anyOf: - const: regular type: string - const: bold type: string - const: italic type: string - const: boldItalic type: string fontSize: minimum: 1 maximum: 999 description: >- Font size in PDF points; defaults to the theme value type: number color: pattern: ^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$ description: >- Color as a 3- or 6-digit hex code, e.g. `#1a73e8` type: string description: Row label, shown before the value value: anyOf: - minLength: 0 maxLength: 1024 description: >- Plain text rendered with the theme defaults; may be empty type: string - additionalProperties: false type: object required: - text properties: text: minLength: 0 maxLength: 1024 description: Text content to render; may be empty type: string fontRole: description: >- Font weight and style to apply to this text within the active font stack anyOf: - const: regular type: string - const: bold type: string - const: italic type: string - const: boldItalic type: string fontSize: minimum: 1 maximum: 999 description: >- Font size in PDF points; defaults to the theme value type: number color: pattern: ^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$ description: >- Color as a 3- or 6-digit hex code, e.g. `#1a73e8` type: string description: Row value, shown after the label visible: description: >- When `false`, the row is omitted from the rendered section; defaults to shown type: boolean description: Document context section rendered as a label/value grid highlights: additionalProperties: false type: object required: - items properties: sectionTitle: anyOf: - minLength: 0 maxLength: 1024 description: >- Plain text rendered with the theme defaults; may be empty type: string - additionalProperties: false type: object required: - text properties: text: minLength: 0 maxLength: 1024 description: Text content to render; may be empty type: string fontRole: description: >- Font weight and style to apply to this text within the active font stack anyOf: - const: regular type: string - const: bold type: string - const: italic type: string - const: boldItalic type: string fontSize: minimum: 1 maximum: 999 description: Font size in PDF points; defaults to the theme value type: number color: pattern: ^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$ description: Color as a 3- or 6-digit hex code, e.g. `#1a73e8` type: string description: Optional heading rendered above the rows items: minItems: 0 maxItems: 32 description: Label/value rows rendered as a grid type: array items: additionalProperties: false type: object required: - label - value properties: label: anyOf: - minLength: 0 maxLength: 1024 description: >- Plain text rendered with the theme defaults; may be empty type: string - additionalProperties: false type: object required: - text properties: text: minLength: 0 maxLength: 1024 description: Text content to render; may be empty type: string fontRole: description: >- Font weight and style to apply to this text within the active font stack anyOf: - const: regular type: string - const: bold type: string - const: italic type: string - const: boldItalic type: string fontSize: minimum: 1 maximum: 999 description: >- Font size in PDF points; defaults to the theme value type: number color: pattern: ^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$ description: >- Color as a 3- or 6-digit hex code, e.g. `#1a73e8` type: string description: Row label, shown before the value value: anyOf: - minLength: 0 maxLength: 1024 description: >- Plain text rendered with the theme defaults; may be empty type: string - additionalProperties: false type: object required: - text properties: text: minLength: 0 maxLength: 1024 description: Text content to render; may be empty type: string fontRole: description: >- Font weight and style to apply to this text within the active font stack anyOf: - const: regular type: string - const: bold type: string - const: italic type: string - const: boldItalic type: string fontSize: minimum: 1 maximum: 999 description: >- Font size in PDF points; defaults to the theme value type: number color: pattern: ^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$ description: >- Color as a 3- or 6-digit hex code, e.g. `#1a73e8` type: string description: Row value, shown after the label visible: description: >- When `false`, the row is omitted from the rendered section; defaults to shown type: boolean description: Optional highlighted facts rendered as a compact horizontal line description: First-page header band content footer: additionalProperties: false type: object required: - professionalName properties: signature: pattern: >- ^data:image/(png|jpeg|jpg|gif|tiff|svg\+xml);base64,[A-Za-z0-9+/=]+$ maxLength: 4194304 description: Optional signature image shown in the last-page footer type: string professionalName: anyOf: - minLength: 1 maxLength: 1024 pattern: \S description: >- Plain text rendered with the theme defaults; must contain a non-whitespace character type: string - additionalProperties: false type: object required: - text properties: text: minLength: 1 maxLength: 1024 pattern: \S description: >- Text content to render; must contain a non-whitespace character type: string fontRole: description: >- Font weight and style to apply to this text within the active font stack anyOf: - const: regular type: string - const: bold type: string - const: italic type: string - const: boldItalic type: string fontSize: minimum: 1 maximum: 999 description: Font size in PDF points; defaults to the theme value type: number color: pattern: ^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$ description: Color as a 3- or 6-digit hex code, e.g. `#1a73e8` type: string description: Professional name shown beneath the signature professionalCredentials: anyOf: - minLength: 0 maxLength: 1024 description: Plain text rendered with the theme defaults; may be empty type: string - additionalProperties: false type: object required: - text properties: text: minLength: 0 maxLength: 1024 description: Text content to render; may be empty type: string fontRole: description: >- Font weight and style to apply to this text within the active font stack anyOf: - const: regular type: string - const: bold type: string - const: italic type: string - const: boldItalic type: string fontSize: minimum: 1 maximum: 999 description: Font size in PDF points; defaults to the theme value type: number color: pattern: ^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$ description: Color as a 3- or 6-digit hex code, e.g. `#1a73e8` type: string description: Optional credential line shown below the professional name organization: additionalProperties: false type: object properties: phone: anyOf: - minLength: 0 maxLength: 1024 description: >- Plain text rendered with the theme defaults; may be empty type: string - additionalProperties: false type: object required: - text properties: text: minLength: 0 maxLength: 1024 description: Text content to render; may be empty type: string fontRole: description: >- Font weight and style to apply to this text within the active font stack anyOf: - const: regular type: string - const: bold type: string - const: italic type: string - const: boldItalic type: string fontSize: minimum: 1 maximum: 999 description: Font size in PDF points; defaults to the theme value type: number color: pattern: ^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$ description: Color as a 3- or 6-digit hex code, e.g. `#1a73e8` type: string description: Organization phone number address: anyOf: - minLength: 0 maxLength: 1024 description: >- Plain text rendered with the theme defaults; may be empty type: string - additionalProperties: false type: object required: - text properties: text: minLength: 0 maxLength: 1024 description: Text content to render; may be empty type: string fontRole: description: >- Font weight and style to apply to this text within the active font stack anyOf: - const: regular type: string - const: bold type: string - const: italic type: string - const: boldItalic type: string fontSize: minimum: 1 maximum: 999 description: Font size in PDF points; defaults to the theme value type: number color: pattern: ^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$ description: Color as a 3- or 6-digit hex code, e.g. `#1a73e8` type: string description: Organization postal address email: anyOf: - minLength: 0 maxLength: 1024 description: >- Plain text rendered with the theme defaults; may be empty type: string - additionalProperties: false type: object required: - text properties: text: minLength: 0 maxLength: 1024 description: Text content to render; may be empty type: string fontRole: description: >- Font weight and style to apply to this text within the active font stack anyOf: - const: regular type: string - const: bold type: string - const: italic type: string - const: boldItalic type: string fontSize: minimum: 1 maximum: 999 description: Font size in PDF points; defaults to the theme value type: number color: pattern: ^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$ description: Color as a 3- or 6-digit hex code, e.g. `#1a73e8` type: string description: Organization email address description: Optional organization contact details shown in the footer description: Last-page footer band content fontStack: minItems: 1 maxItems: 4 description: >- Ordered list of hosted font families for the cascade. Exactly one weighted body/heading family is required (for example `inter`, `lora`, or `source-serif-4`). Emoji families (`noto-emoji-mono`, `twemoji-mozilla`) are appended automatically when omitted so emoji glyphs always render; optional `jetbrains-mono` supplies the code role. Every hosted family is available on every plan. This route does not accept Google Fonts URLs. type: array items: type: string enum: - inter - lora - source-serif-4 - noto-emoji-mono - twemoji-mozilla - jetbrains-mono page: additionalProperties: false description: >- Page geometry and appearance for the output PDF, including optional full-sheet background. The sandwich-document template supplies defaults of size "Letter" and 2 cm margin when these fields (or the whole page object) are omitted; explicit values override the defaults for their respective fields. type: object properties: size: description: Page size; defaults to Letter when omitted anyOf: - const: A3 type: string - const: A4 type: string - const: A5 type: string - const: B4 type: string - const: B5 type: string - const: Letter type: string - const: Legal type: string - const: Tabloid type: string - const: HalfLetter type: string - type: array items: minimum: 1 maximum: 14400 type: number minItems: 2 maxItems: 2 orientation: type: string enum: - portrait - landscape margin: anyOf: - minimum: 0 maximum: 2880 description: Uniform page margin in PDF points applied to all four sides type: number - additionalProperties: false type: object required: - top - right - bottom - left properties: top: minimum: 0 maximum: 2880 description: Top margin in PDF points type: number right: minimum: 0 maximum: 2880 description: Right margin in PDF points type: number bottom: minimum: 0 maximum: 2880 description: Bottom margin in PDF points type: number left: minimum: 0 maximum: 2880 description: Left margin in PDF points type: number description: >- Page margins in PDF points; defaults to a uniform 2 cm (≈56.69 pt) when omitted background: description: >- Full-page sheet background, or `null` to suppress an explicit fill anyOf: - additionalProperties: false type: object required: - color properties: color: pattern: ^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$ description: Color as a 3- or 6-digit hex code, e.g. `#1a73e8` type: string opacity: minimum: 0 maximum: 1 description: Fill opacity from 0 to 1 type: number - type: 'null' Error.ValidationFailed: type: object required: - type - title - status - errors description: >- RFC 9457 problem document for a render-validation failure (a TypeBox schema violation, a cross-field semantic check, or both). Every field-level problem of one request — schema and semantic together — is collected into the `errors` array, so all problems are visible in a single response rather than one per round-trip. Semantic checks include `googleFontsUrl`/`googleFontsUrls` mutual exclusion, an undeclared `typography.pool` entry, and a `rules` `set.family`/`set.font` reference to an undeclared family or role. properties: type: type: string format: uri description: Problem type URI (https://blinkpdf.io/errors/validation_failed). title: type: string description: Short, human-readable summary of the problem type. status: type: integer description: HTTP status code generated for this problem (always 400). errors: type: array description: >- Every field-level violation of the request, each with a JSON Pointer `pointer`, a `detail` explanation, and the machine-readable `kind`. Members may also carry allowed keys/values, relocation hints, and did-you-mean suggestions. items: type: object required: - type - pointer - detail - kind properties: type: type: string format: uri description: >- Problem type URI for this member (https://blinkpdf.io/errors/validation_failed). pointer: type: string description: >- RFC 6901 JSON Pointer to the offending field, fragment-prefixed (`#/pageSize`, `#/margins/top`). detail: type: string description: Human-readable explanation of this field-level violation. property: type: string kind: type: string enum: - additional_property - missing_property - invalid_value - constraint allowedKeys: type: array items: type: string allowedValues: type: array items: type: string requiredKeys: type: array items: type: string variants: type: array description: >- Accepted variant shapes when the failing value is an object-valued union. Each entry publishes only when?/keys/required/enums — never internal numericRanges or nestedObjects. items: type: object required: - keys - required properties: when: type: object description: >- Discriminant when a required key pins a single literal (`{ kind: "grid" }`). properties: key: type: string value: type: string keys: type: array items: type: string description: All keys this variant accepts. required: type: array items: type: string description: Keys this variant requires. enums: type: object description: >- Allowed literal values per enum-valued key inside this variant. Additional properties are string arrays. Internal numericRanges/nestedObjects are never published. additionalProperties: type: array items: type: string relocate: type: object properties: path: type: string dotPath: type: string allowedKeys: type: array items: type: string relocateCandidates: type: array description: >- Additional relocation targets when the property name appears in multiple schema branches. items: type: object properties: path: type: string dotPath: type: string allowedKeys: type: array items: type: string didYouMean: type: array description: >- Near-miss suggestions. Each entry carries exactly one of `key` (a misspelled property name) or `value` (a bad enum/literal value), plus an optional `index` pinpointing the OR-array element it corrects. items: type: object properties: key: type: string value: type: string index: type: integer appliesTo: type: array items: type: string description: >- Node types where the rejected `rules[].set` property is valid, present when it is valid for some other type, so an agent can switch the selected type without parsing the message. schema: type: string description: >- Present on `POST /v1/render` validation failures. MCP resource URI for the compact per-path render contract index (`blinkpdf://reference/path-index`). errorsTruncated: type: boolean description: >- True when members were dropped or compacted to satisfy the response byte cap. Error.SingleFault: type: object required: - error description: >- Single-cause invalid-input envelope (RFC 9457 reserves the `errors` array for the multi-violation validation path; these single-cause faults do not use it). The `error` discriminator identifies the kind of failure: `invalid_body` (malformed JSON), `invalid_input` (an unrecognized or unsupported query parameter), `content_not_paginable` (the content cannot be laid out on the chosen page — e.g. a table cell taller than a single page), `font_family_not_available` (unknown font family — `available` lists supported keys), `invalid_google_fonts_url` (the `googleFontsUrl` value is not a supported Google Fonts URL form, declares no families, or declares too many), or `google_font_not_found` (a declared family does not exist on Google Fonts — `families` lists the ones not found, and `didYouMean` carries a near-miss family suggestion when a missing name is a typo of a sibling family declared in the same request). properties: error: type: string enum: - invalid_body - invalid_input - content_not_paginable - font_family_not_available - invalid_google_fonts_url - google_font_not_found code: type: string description: >- Canonical machine discriminator, mirroring `error` verbatim. Present on every single-cause error envelope so a client can branch on a single `code` field regardless of the specific error. The MCP server maps this to a broad retry category and preserves the specific name as `restErrorName`. detail: type: string available: type: array items: type: string description: >- Present when `error` is `font_family_not_available`. Lists every registered font key. families: type: array items: type: string description: >- Present when `error` is `google_font_not_found`. Lists the declared family names that do not exist on Google Fonts. didYouMean: type: array items: type: object properties: key: type: string value: type: string index: type: integer description: >- Present on a `google_font_not_found` error when a missing family name is a typo of a sibling family declared in the same request. Each entry carries `value` (the existing family the missing name appears to be a misspelling of). Error.Unauthorized: type: object required: - error properties: error: type: string enum: - unauthorized Error.SpendCapReached: type: object required: - error description: >- Returned when paid plan access is required: a plan volume limit was reached (`spend_cap_reached` — spend cap for paid; calendar monthly 250 render units for free). The detail names the exhausted limit. properties: error: type: string enum: - spend_cap_reached detail: type: string Error.MethodNotAllowed: type: object required: - error properties: error: type: string enum: - method_not_allowed Error.PayloadTooLarge: type: object required: - error properties: error: type: string enum: - payload_too_large Error.RateLimited: type: object required: - error description: >- Post-auth tier rate exhaustion and post-auth concurrency exhaustion both use `error: rate_limited`; distinguish them by `detail` (tier rate vs concurrency/plan copy). Render audit rows use separate `status` values (`rate_limited` vs `concurrency_limited`). properties: error: type: string enum: - rate_limited detail: type: string Error.Internal: type: object required: - error description: Unexpected server error. No additional details are provided. properties: error: type: string enum: - internal_error detail: type: string Error.ServiceUnavailable: type: object required: - error description: >- Transient outage shared by every 503. `font_source_unavailable` is a font catalogue read failure (`POST /v1/render`, `GET /v1/fonts`); `service_unavailable` is a subscription tier-lookup failure, fail-closed (`GET /v1/fonts`). Both are retryable. Each route documents which codes it can emit. properties: error: type: string enum: - service_unavailable - font_source_unavailable detail: type: string responses: Responses.BadRequest: description: >- Invalid input. A render-validation failure returns the RFC 9457 `Error.ValidationFailed` problem document with every schema and semantic violation collected in `errors`; a single-cause fault (malformed body, unknown query parameter, unknown font family, or an unusable Google Fonts reference) returns the `Error.SingleFault` envelope. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error.ValidationFailed' - $ref: '#/components/schemas/Error.SingleFault' examples: validationFailed: $ref: '#/components/examples/Error.ValidationFailed' semanticValidationFailed: $ref: '#/components/examples/Error.SemanticValidationFailed' invalidBody: $ref: '#/components/examples/Error.InvalidBody' invalidInput: $ref: '#/components/examples/Error.InvalidInput' fontFamilyNotAvailable: $ref: '#/components/examples/Error.FontFamilyNotAvailable' invalidGoogleFontsUrl: $ref: '#/components/examples/Error.InvalidGoogleFontsUrl' googleFontNotFound: $ref: '#/components/examples/Error.GoogleFontNotFound' Responses.Unauthorized: description: >- Missing or invalid `x-api-key` (must be a valid, enabled `bp_*` key; documentation endpoints and health are exempt) content: application/json: schema: $ref: '#/components/schemas/Error.Unauthorized' examples: unauthorized: $ref: '#/components/examples/Error.Unauthorized' Responses.SpendCapReached: description: >- Paid plan access required: a plan volume limit has been reached (`spend_cap_reached` — spend cap for paid; free calendar 250 render units monthly). Detail in body names the exhausted limit. Response may carry `X-BlinkPDF-Usage-*` headers. headers: X-BlinkPDF-Usage-PDFs-This-Period: schema: type: integer minimum: 0 description: Current render-unit usage in the active billing period. X-BlinkPDF-Usage-Included: schema: type: integer minimum: 0 description: The plan's included render-unit volume for the period. X-BlinkPDF-Period-Start: schema: type: string format: date-time description: ISO-8601 anchor (anniversary for paid, calendar month for free). content: application/json: schema: $ref: '#/components/schemas/Error.SpendCapReached' examples: spendCapReached: $ref: '#/components/examples/Error.SpendCapReached' Responses.MethodNotAllowed: description: >- Method not allowed on `/v1/render` (only POST is accepted); response carries `Allow: POST`. headers: Allow: schema: type: string enum: - POST description: Methods accepted on this path content: application/json: schema: $ref: '#/components/schemas/Error.MethodNotAllowed' examples: methodNotAllowed: $ref: '#/components/examples/Error.MethodNotAllowed' Responses.PayloadTooLarge: description: >- Serialized JSON request body exceeds the caller's plan tier limit (`getTechnicalLimits`: free 128 KiB, pro 2 MiB, business 5 MiB). Enforcement uses the UTF-8 byte length of `JSON.stringify(body)` after parse, so a missing or incorrect `Content-Length` header cannot bypass the cap. content: application/json: schema: $ref: '#/components/schemas/Error.PayloadTooLarge' examples: payloadTooLarge: $ref: '#/components/examples/Error.PayloadTooLarge' Responses.RateLimited: description: >- Rate or concurrency limit exceeded (post-auth per-tier limits from `getTechnicalLimits`: free 10/min + 1 concurrent, pro 120/min + 10 concurrent, business 600/min + 40 concurrent; a high pre-auth per-IP flood shield also exists but is sized above every plan rate and never binds first for plan traffic). Post-auth tier rate and concurrency blocks both return `error: rate_limited` but use different `detail` strings; audit rows distinguish `rate_limited` vs `concurrency_limited`. Tier-specific responses may include upgrade guidance in `detail`. The response carries `Retry-After` and defensive security headers. headers: Retry-After: schema: minimum: 1 type: integer description: Seconds remaining until the rate-limit window resets. Always >= 1. content: application/json: schema: $ref: '#/components/schemas/Error.RateLimited' examples: rateLimited: $ref: '#/components/examples/Error.RateLimited' Responses.InternalError: description: Unexpected server error. No additional details are provided. content: application/json: schema: $ref: '#/components/schemas/Error.Internal' examples: internal: $ref: '#/components/examples/Error.Internal' Responses.SourceUnavailable: description: >- Font catalogue temporarily unavailable (`font_source_unavailable`). This is a transient condition. A `Retry-After` header indicates when the client may retry. headers: Retry-After: schema: minimum: 1 type: integer description: Seconds the client should wait before retrying. Defaults to 30. content: application/json: schema: $ref: '#/components/schemas/Error.ServiceUnavailable' examples: fontSourceUnavailable: $ref: '#/components/examples/Error.FontSourceUnavailable' examples: Error.ValidationFailed: summary: Schema and semantic violations collected together description: >- Every problem of one request is reported at once: a TypeBox schema violation (an unknown property, with accepted keys and a `didYouMean`) alongside a cross-field semantic check, each as one `errors` member with a JSON Pointer `pointer`. value: type: https://blinkpdf.io/errors/validation_failed title: Validation failed status: 400 schema: blinkpdf://reference/path-index errors: - type: https://blinkpdf.io/errors/validation_failed pointer: '#/rule' detail: Unknown property 'rule' at body kind: additional_property property: rule allowedKeys: - fontStack - furniture - googleFontsUrl - googleFontsUrls - markdown - metadata - numbering - outline - page - rules - typography - viewer didYouMean: - key: rules - type: https://blinkpdf.io/errors/validation_failed pointer: '#/metadata/modificationDate' detail: >- metadata.modificationDate must not be earlier than metadata.creationDate (modification cannot precede creation) kind: constraint Error.SemanticValidationFailed: summary: Cross-field semantic check failed (errors array) value: type: https://blinkpdf.io/errors/validation_failed title: Validation failed status: 400 schema: blinkpdf://reference/path-index errors: - type: https://blinkpdf.io/errors/validation_failed pointer: '#/metadata/modificationDate' detail: >- metadata.modificationDate must not be earlier than metadata.creationDate (modification cannot precede creation) kind: constraint Error.InvalidBody: summary: Malformed JSON in the request body value: error: invalid_body detail: Unexpected end of JSON input Error.InvalidInput: summary: Unrecognized query parameter value: error: invalid_input detail: >- Unknown query parameter 'foobar'. POST /v1/render takes no query parameters. Error.FontFamilyNotAvailable: summary: Unknown font family value: error: font_family_not_available detail: Font family 'unknown' is not registered available: - inter - noto-emoji-mono - twemoji-mozilla - jetbrains-mono Error.InvalidGoogleFontsUrl: summary: Unsupported or malformed googleFontsUrl value: error: invalid_google_fonts_url detail: >- googleFontsUrl: unsupported host 'fonts.example.com'. Use a Google Fonts CSS URL (https://fonts.googleapis.com/css2?family=… or /css?family=…), a specimen page (https://fonts.google.com/specimen/), or a share link (https://fonts.google.com/share?selection.family=…). Error.GoogleFontNotFound: summary: Family does not exist on Google Fonts value: error: google_font_not_found detail: >- Google Fonts family 'Playfare Display' was not found. Check the family name on fonts.google.com and update the googleFontsUrl. Error.Unauthorized: summary: Missing or invalid x-api-key (bp_*) value: error: unauthorized Error.SpendCapReached: summary: Plan monthly spend cap reached value: error: spend_cap_reached detail: >- The monthly spend cap for this plan has been reached. Usage that exceeds the included volume is paused until the next billing period. Raise the spend cap or upgrade the plan to continue. Error.MethodNotAllowed: summary: Non-POST method on /v1/render value: error: method_not_allowed Error.PayloadTooLarge: summary: Request body exceeds the configured cap value: error: payload_too_large Error.RateLimited: summary: >- Per-tier rate limit exceeded (concurrency exhaustion uses the same error code with a different detail string) value: error: rate_limited detail: >- Tier rate limit exceeded. Retry after the Retry-After interval or upgrade for higher sustained throughput. Error.Internal: summary: Unexpected server error (no details provided) value: error: internal_error Error.FontSourceUnavailable: summary: Transient failure loading a requested font value: error: font_source_unavailable detail: Font asset temporarily unavailable; retry shortly. 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 request. The documentation and health endpoints are exempt. ````