Blink PDF API Reference: Base URL, Auth, and Errors

Blink PDF is a REST API with two verbs: render Markdown to PDF, and fill an AcroForm by name. Fill is not a mode on POST /v1/render. There is no /v1/forms route (404). Same bp_ key. This overview covers the base URL, available endpoints, request and response conventions, and what to expect when something goes wrong.

Base URL

All API requests are made to the following base URL:

https://api.blinkpdf.io

The current API version is v1. Rendering endpoints are prefixed with /v1/; the unversioned health check lives at /health.

The base URL does not include a trailing slash. Append endpoint paths exactly as shown in the table below.

Endpoints at a Glance

Method	Path	Description
`POST`	`/v1/render`	Convert Markdown to a PDF binary
`POST`	`/v1/render/validate`	Validate a render request body without generating a PDF or consuming units
`POST`	`/v1/inspect`	List fillable AcroForm fields (`pdf` XOR `templateId`). No unit
`POST`	`/v1/validate-fill`	Dry-run a fill by name. No PDF. No unit
`POST`	`/v1/fill`	Fill an AcroForm by name. Streams PDF. 1 unit. Never `/NeedAppearances`
`POST`	`/v1/templates`	Store a blank AcroForm. No unit
`GET`	`/v1/templates`	List stored blanks `{ id, title }`
`GET`	`/v1/templates/{id}`	Cached inspect plus `downloadUrl`. `Accept: application/pdf` streams the blank
`PATCH`	`/v1/templates/{id}`	Title and/or replacement bytes on the same id
`DELETE`	`/v1/templates/{id}`	Delete a stored blank (gone, not hidden)
`GET`	`/v1/templates/{id}/download`	Stream the stored blank PDF
`POST`	`/v1/templates/sandwich-document/render`	Render a structured sandwich document (first-page header + last-page signature)
`GET`	`/v1/fonts`	List the hosted font catalog and Google Fonts limits for your key
`GET`	`/v1/style-targets`	Machine-readable catalog of the styling vocabulary (`rules` selectors and properties)
`GET`	`/v1/themes`	List the 15 curated design themes
`GET`	`/`	Machine-readable entry point linking the public API surfaces (includes `inspect`, `validateFill`, `fill`, `templates`)
`GET`	`/health`	Liveness probe (no auth required)

Fill guides: overview, inspect, fill, templates. /v1/forms is not a route.

Pick a curated look with the theme field (default report-clean) — call GET /v1/themes for the catalog, see Themes. Pick fonts per request with the fontStack field, or pull any Google Fonts family by URL with googleFontsUrl — see Fonts & Typography. Call GET /v1/fonts for the hosted catalog and GET /v1/style-targets for the full rules styling vocabulary.

Request Format

Authenticated POST requests send JSON (or, on inspect / validate-fill / fill / templates, multipart pdf) and:

Header	Value
`x-api-key`	`bp_...` (same key for render and fill)
`Accept`	`application/pdf` on fill and render; `application/json` on inspect, validate-fill, and validate-render
`Content-Type`	`application/json` (or `multipart/form-data` when uploading a PDF file)

POST /v1/render/validate and POST /v1/validate-fill expect Accept: application/json because the response is JSON, not PDF bytes. GET requests that require authentication need only the x-api-key header — no request body is sent. GET /v1/templates/{id} may send Accept: application/pdf to stream the stored blank.

Response Format

A successful call to POST /v1/fill, POST /v1/render, or POST /v1/templates/sandwich-document/render returns a binary PDF (application/pdf). Pipe or write the response body directly to a file rather than reading it as text. POST /v1/fill streams the bytes and does not keep the output. On the public free plan, successful PDF responses from POST /v1/fill, POST /v1/render, and sandwich template routes include a non-removable bottom-center footer (“Made with Blink PDF” plus the brand mark). The response status and schema are unchanged. GET /health, POST /v1/inspect, POST /v1/validate-fill, POST /v1/render/validate, template-library JSON, and all error responses return JSON (application/json).

Validate before render

POST /v1/render/validate runs the same TypeBox schema and cross-field semantic checks as POST /v1/render, without generating a PDF, metering usage, or recording a successful render audit. Use it to iterate on rules, typography, furniture, and related options before spending a unit. Fill has a matching dry-run: POST /v1/validate-fill. Same pdf XOR templateId plus values as fill. No PDF. No unit. Empty required names land in missingRequired; fill still writes. A valid body returns 200 with valid: true. When the caller is authenticated, the response also reports the resolved typography (declared pool, active body/heading families, and any unused declarations) and a contentDigest for delivery deduplication:

{ "valid": true }

Validation failures return the same 400 error shape as a failed render request (validation_failed, invalid_body, and related codes). The endpoint does not emit X-Render-* or X-BlinkPDF-Usage-* headers.

Response Headers

Every successful render (POST /v1/render or POST /v1/templates/sandwich-document/render) includes render-status headers and, when the caller is authenticated under plan limits, usage and attribution headers. POST /v1/fill shares the same spend-cap, tier rate/concurrency, and usage ledger path. A counted fill is 1 unit. Fill overlay advisories ride X-Fill-Warnings — see Fill.

Render status

Header	Description
`X-Render-Status`	`ok` when no warn- or error-level diagnostics were emitted; `degraded` otherwise
`X-Render-Rendered-As-Requested`	`true` when the PDF matches what you asked for (no error-severity issues such as missing images or glyphs, and no `image-fetch-skipped` warnings). `false` when the output diverged
`X-Render-Diagnostics`	Base64url-encoded UTF-8 JSON array of actionable diagnostics. Omitted when there were no diagnostics to report
`X-Render-Diagnostics-Truncated`	`true` when the diagnostics array was truncated to fit header size limits (highest-severity entries are kept first). The diagnostics header itself may be omitted when even one entry cannot fit
`X-Render-Fonts`	The per-role font families actually embedded, including per-depth heading overrides
`X-Render-Font-Fallback`	The family used for glyphs the primary fonts missed (e.g. `inter`; see `glyphFallback`)
`X-Render-Theme-Fallback`	Present when the requested `theme` slug was unknown; names the applied theme and a `didYouMean` suggestion
`X-Render-Typography-Notes`	Informational notes about typography resolution
`X-Render-Rule-Warnings`	Advisories for `rules` that matched nothing or were inert
`X-Render-Static-Warnings`	Node-level advisories raised during layout
`X-Render-Ms`	Render wall-time in milliseconds
`X-Request-Id`	Unique request identifier. Include this when emailing [email protected]

Each diagnostic object includes severity, code, message, and help (a blinkpdf://reference/… URI). When applicable, entries also include resource and httpStatus. Decode X-Render-Diagnostics like this:

import base64
import json

raw = response.headers.get("X-Render-Diagnostics")
if raw:
    padded = raw + "=" * (-len(raw) % 4)
    diagnostics = json.loads(base64.urlsafe_b64decode(padded))

Usage and attribution

Successful authenticated renders on both POST /v1/render and POST /v1/templates/sandwich-document/render, and successful fills on POST /v1/fill, emit usage and attribution headers when billing limits apply:

Header	Description
`X-BlinkPDF-Billing`	Billing outcome: `counted` (billed), `deduped-cache` (cache replay, not billed; `POST /v1/render` only), or `deduped-idempotent` (idempotency-key replay, not billed; `POST /v1/render` and `POST /v1/fill`). The authoritative “was this billed?” signal
`X-BlinkPDF-Usage-Event-Id`	The metering event id for this render
`X-BlinkPDF-Usage-PDFs-This-Period`	Render units used in the current billing period (when attributable)
`X-BlinkPDF-Usage-Included`	Render units included in your plan for the period
`X-BlinkPDF-Usage-Overage`	Render units used beyond the included volume
`X-BlinkPDF-Cache`, `X-BlinkPDF-Cache-Age`	Cache outcome (`hit`/`miss`) and, on a hit, the age of the cached render in seconds — `POST /v1/render` only (template routes do not use the process-local PDF LRU)
`X-BlinkPDF-Content-Digest`	Canonical per-account render digest used for delivery deduplication — `POST /v1/render` only
`X-BlinkPDF-Period-Start`	ISO-8601 start of the current billing period
`X-BlinkPDF-Account`, `X-BlinkPDF-Key-Id`, `X-BlinkPDF-Key-Name`	Opaque account id, API key id, and optional key label for attribution

Sandwich template

POST /v1/templates/sandwich-document/render is metered like POST /v1/render: it counts 1 unit on a successful billed response, shares spend-cap and tier rate/concurrency, applies the free-tier watermark when applicable, and emits the usage/attribution headers above (except cache and content-digest headers). Successful responses always include X-Template-Version (currently 1.0.0). 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 — so the Markdown body never collides with either chrome band. Client x-idempotency-key is not accepted on template routes (no body fingerprint / pre-check). Do not send it expecting dedupe.

Error Codes

When a request cannot be completed, the API returns a standard HTTP error status code with a JSON body of the shape { "error": "<code>", "detail": "<message>" }. Field-level validation failures may also include an errors array; each member can carry machine-readable kind, allowed keys/values, relocation hints, and optional variants (accepted shapes for object-valued unions: discriminant when, keys, required, enums — never internal numeric ranges).

Status Code	`error`	What It Means
`400`	`validation_failed` / `invalid_body` / …	The request body is malformed, is not valid JSON, or fails schema validation
`401`	`unauthorized`	The `x-api-key` header is absent or the API key is invalid
`402`	`spend_cap_reached`	Spend cap reached on `POST /v1/fill`, `POST /v1/render`, or `POST /v1/templates/*/render` — you hit your configured cap or your plan’s hard cap (2× included volume); billing is paused until the next period
`404`	`not_found`	No matching route, or no stored template with that `templateId` for this account. `/v1/forms` is always this
`405`	`method_not_allowed`	The HTTP method is not supported on this path
`409`	`idempotency_conflict`	A different request body was sent with an already-used idempotency key (`POST /v1/render` and `POST /v1/fill`)
`409`	`template_limit`	Stored-template object cap reached (`maxTemplates` / `current`). Not the persistent-PDF cap
`413`	`payload_too_large`	The request body exceeds the maximum allowed size (`bodyBytes` on fill-by-bytes / render; `maxTemplateBytes` on store/replace)
`422`	`image_too_large`	A single image exceeds 24 megapixels, or the render’s total image area exceeds 48 megapixels
`422`	`no_acroform` / `need_appearances` / `encrypted_pdf` / `xfa_unsupported` / `signed_pdf`	Template rejected on inspect, validate-fill, fill, or store. See Fill errors
`429`	`rate_limited`	You have exceeded your rate limit. Check the `Retry-After` header for when you can retry
`500`	`internal_error`	The rendering pipeline encountered an unexpected error
`502`	—	Bad gateway (`POST /v1/render` only; HTML body)
`503`	`service_unavailable`	A dependency (such as the font source or template store) is temporarily unavailable; retry shortly
`504`	`service_unavailable`	Fill (or render) produce exceeded the 120 s ceiling. Retry-safe with `x-idempotency-key`

Caller-value fill faults (unknown_field_name, type_mismatch, skipped_field_name, appearance_unencodable) are 400 with RFC 9457 type https://blinkpdf.io/errors/<code>. One bad key fails the whole fill.

When you receive a 429, read the Retry-After response header. It contains the number of seconds you should wait before sending another request.

Rate Limiting

Rate limits are enforced per API key and vary by plan. POST /v1/fill, POST /v1/inspect, POST /v1/validate-fill, POST /v1/render, and sandwich template routes share the plan post-auth rate and concurrency buckets. If you exceed your limit, the API returns 429 Too Many Requests and includes a Retry-After header.

Calls to GET /health, POST /v1/inspect, POST /v1/validate-fill, POST /v1/render/validate, and /v1/templates never consume units. POST /v1/render/validate is rate-limited in its own per-tier bucket, independent of render throughput. Inspect and validate-fill share the fill/render limiters but still spend zero units. Only successful POST /v1/fill, POST /v1/render, and POST /v1/templates/*/render responses with X-BlinkPDF-Billing: counted consume units. A fill is 1 unit.

Versioning

The current API version is v1, reflected in every endpoint path. When breaking changes are introduced, a new version prefix (e.g. /v2/) will be released alongside the existing version. You will always receive advance notice before an older version is deprecated.

​Base URL

​Endpoints at a Glance

​Request Format

​Response Format

​Validate before render

​Response Headers

​Render status

​Usage and attribution

​Sandwich template

​Error Codes

​Rate Limiting

​Versioning

Base URL

Endpoints at a Glance

Request Format

Response Format

Validate before render

Response Headers

Render status

Usage and attribution

Sandwich template

Error Codes

Rate Limiting

Versioning