Add running headers, footers, page numbers, section-driven fragments, divider rules, per-page overrides, and optional decorative watermarks using the furniture field on POST /v1/render.
Blink PDF lets you define running headers and footers that repeat on every page of your rendered document. You configure them through the furniture object of your POST /v1/render request body — no templates to host, no HTML to write. Headers and footers are built from ordered fragments: static text, page numbers, document metadata, running section titles, and section ordinals derived from your Markdown headings.
The fields below are validated against the live API schema. The API Reference → Render endpoint is generated directly from the server’s OpenAPI contract and is always the authoritative source for every field and constraint.
Sourced from a data: URI, an http(s):// URL, or a blink://asset/<id> handle
pageNumber
The current page number
totalPages
The total number of pages
documentTitle
metadata.title, or the title derived from the first heading
sectionTitle
The running section title at a heading depth (1–6)
sectionIndex
The section ordinal at a heading depth (1–6)
Use format: twoDigit (01, 12; ≥100 renders in full) or decimal (1, 2, …)
Fragments in a slot are concatenated in order. A “Page 3 of 12” footer is four fragments: text → pageNumber → text → totalPages. A magazine-style header might combine sectionIndex and sectionTitle at depth: 1.
A fragment that can only ever render empty — a sectionTitle/sectionIndex at a heading depth the document never reaches, or a documentTitle when no title resolves — is flagged by validate_render_pdf as furniture_fragment_empty so you can fix or drop it.
Running headers and footers. slots applies to every page; set omitFirstPage: true to suppress furniture on the cover page only, or pass firstPage to override the first page. Set omitLastPage: true to suppress furniture on the closing page (when totalPages > 1), or pass lastPage to override the final page. Optional pageOverrides supplies arbitrary per-page exceptions. Optional decorations draws header/footer divider rules. Optional watermark draws faint text behind body content.
Content for each of the six positions. Each key (topLeft, topCenter, topRight, bottomLeft, bottomCenter, bottomRight) is optional and takes a content array of fragments (1–16 per slot) and an optional slot-level style.
When true, suppresses all furniture on the first page only — including watermark and decorations. Use this for cover pages while keeping headers and footers on every following page.
A first-page-only override of slots with the same six-slot shape. Use when the cover should show different furniture than the rest, not when you want a blank first page (use omitFirstPage instead).
When true, suppresses all furniture on the final page only — including watermark and decorations. Ignored when the document has only one page. Use this for signature or closing pages while keeping headers and footers on every preceding page.
A last-page-only override of slots with the same six-slot shape. Use when the closing page should show different furniture than the rest, not when you want a blank final page (use omitLastPage instead).
Distance of the furniture from the page edges, in points. Accepts top (header distance from the top edge) and bottom (footer distance from the bottom edge).
Non-text margin graphics composed alongside the six-slot grid (up to 8 entries). Each item is a rule — a horizontal hairline in a header or footer band.
Stroke overrides. Omitted fields fall back to defaults (0.5 pt hairline, 6 pt offset). Accepts color (#RGB or #RRGGBB), width (0.1–50 pt), opacity (0–1), dash ([dash, gap] in points), inset (horizontal inset from each content edge), offset (vertical gap between band text and the rule), and lineCap (butt, round, projecting).
Arbitrary per-page furniture exceptions (up to 64 entries). Later matching entries win per field. Cover/closing sugar (omitFirstPage, firstPage, omitLastPage, lastPage) applies after overrides on pages 1 and the final page.
Decorative watermark drawn behind body content on every page (distinct from the Free-plan billing mark). Either static text (1–256 characters) or per-page sectionIndex at a heading depth. Optional color, opacity, fontSize, and position (center, top-left, top-right, bottom-left, bottom-right).
Furniture is drawn within the page margins. If a header or footer is clipped, increase page.margin.top or page.margin.bottom (margins are in points — see Document Options).
The following request renders a policy document with a header in the top-left corner of every page and a centered “Page X of Y” footer in the bottom-right.
curl https://api.blinkpdf.io/v1/render \ --request POST \ --header 'Accept: application/pdf' \ --header 'Content-Type: application/json' \ --header 'x-api-key: bp_xxxxxxxxxxxxxxxxxxxx' \ --data '{ "markdown": "# Employee Leave Policy\n\n## Overview\n\nThis policy governs all forms of leave available to full-time employees.\n\n## Annual Leave\n\nAll employees accrue 20 days of annual leave per calendar year.\n\n## Sick Leave\n\nUp to 10 days of paid sick leave are available per year without a medical certificate.", "metadata": { "title": "Employee Leave Policy", "author": "Acme HR Department" }, "page": { "margin": { "top": 84, "right": 57, "bottom": 84, "left": 57 } }, "furniture": { "slots": { "topLeft": { "content": [{ "kind": "text", "value": "Acme Corp — Internal Use Only" }] }, "bottomRight": { "content": [ { "kind": "text", "value": "Page " }, { "kind": "pageNumber" }, { "kind": "text", "value": " of " }, { "kind": "totalPages" } ] } } } }'
const response = await fetch("https://api.blinkpdf.io/v1/render", { method: "POST", headers: { "x-api-key": "bp_xxxxxxxxxxxxxxxxxxxx", "Accept": "application/pdf", "Content-Type": "application/json", }, body: JSON.stringify({ markdown: `# Employee Leave Policy## OverviewThis policy governs all forms of leave available to full-time employees.## Annual LeaveAll employees accrue 20 days of annual leave per calendar year.## Sick LeaveUp to 10 days of paid sick leave are available per year without a medical certificate.`, metadata: { title: "Employee Leave Policy", author: "Acme HR Department", }, page: { margin: { top: 84, right: 57, bottom: 84, left: 57 }, }, furniture: { slots: { topLeft: { content: [{ kind: "text", value: "Acme Corp — Internal Use Only" }], }, bottomRight: { content: [ { kind: "text", value: "Page " }, { kind: "pageNumber" }, { kind: "text", value: " of " }, { kind: "totalPages" }, ], }, }, }, }),});const pdf = await response.arrayBuffer();
import httpxresponse = httpx.post( "https://api.blinkpdf.io/v1/render", headers={ "x-api-key": "bp_xxxxxxxxxxxxxxxxxxxx", "Accept": "application/pdf", "Content-Type": "application/json", }, json={ "markdown": ( "# Employee Leave Policy\n\n" "## Overview\n\n" "This policy governs all forms of leave available to full-time employees.\n\n" "## Annual Leave\n\n" "All employees accrue 20 days of annual leave per calendar year.\n\n" "## Sick Leave\n\n" "Up to 10 days of paid sick leave are available per year without a medical certificate." ), "metadata": { "title": "Employee Leave Policy", "author": "Acme HR Department", }, "page": { "margin": {"top": 84, "right": 57, "bottom": 84, "left": 57}, }, "furniture": { "slots": { "topLeft": { "content": [{"kind": "text", "value": "Acme Corp — Internal Use Only"}], }, "bottomRight": { "content": [ {"kind": "text", "value": "Page "}, {"kind": "pageNumber"}, {"kind": "text", "value": " of "}, {"kind": "totalPages"}, ], }, }, }, },)with open("leave-policy.pdf", "wb") as f: f.write(response.content)
Furniture is stamped on every page by default, including the first and last. To keep a cover page clean, set "omitFirstPage": true — this suppresses slots, decorations, and the decorative watermark on the first page only. To keep a closing page clean (for example a signature sheet), set "omitLastPage": true when the document has more than one page. Use firstPage or lastPage when those pages need different furniture, not a blank page.
