Render Markdown to PDF

Renders Markdown source into a PDF. The caller may select a font cascade via the fontStack field (an ordered list of hosted family keys — every family is available on every plan) or bring Google Fonts families by passing googleFontsUrl (legacy alias of the first entry) or googleFontsUrls (one or two CSS API, specimen, or share URLs copied from fonts.google.com; available on every plan). googleFontsUrl and googleFontsUrls are mutually exclusive. URLs are merged into a pool (max 4 distinct families). Positional defaults: first family of URL 1 → body; first family of URL 2 (or second family of URL 1 when only one URL) → heading. The optional typography object unifies pool overrides, up to two custom named roles (each binding a pool family or hosted key to a name referenced by rule set.font), per-family static weight maps (variantMap), and hosted heading variant policy (headingVariant). Body, heading, and per-depth heading families are assigned with rules (select + set.family); positional URL defaults apply otherwise. set.family accepts hosted weighted keys, Google display names from the pool, or named-role references. With Google Fonts present, the Google family takes the body/heading slot, so a weighted hosted family left in fontStack is ignored and reported as a fontstack_weighted_dropped note in X-Render-Typography-Notes; the stack then supplies only emoji and code families (omitting it applies the companion default). A malformed or unsupported Google Fonts URL returns 400 invalid_google_fonts_url; a family that does not exist on Google Fonts returns 400 google_font_not_found. When a non-default body/heading font cannot cover characters used in the document (for example list markers or accented letters), the render automatically falls back to the default inter family for body and heading text; the response then carries X-Render-Font-Fallback: inter plus the glyph diagnostics that triggered the fallback. glyphFallback lets the caller choose a different family for this fallback instead of the automatic inter default — a document-level, last-resort family applied per glyph, so only the codepoints the primary fonts miss route to it while every codepoint the primary fonts already cover keeps its requested family; when set, X-Render-Font-Fallback reports the chosen family instead of inter. Images are accepted via standard Markdown syntax (data: URLs are inlined; http(s): URLs are fetched). Remote images are subject to strict security policies (private IP addresses are rejected and mixed content is disabled). For accessibility, set the document language with viewer.language (a BCP 47 tag such as es-ES), which becomes the PDF /Lang; viewer also carries page-layout, page-mode, and viewer-preference hints. Rendering issues are reported via X-Render-Status, X-Render-Rendered-As-Requested, and when present X-Render-Diagnostics (JSON array of actionable objects).

Identical markdown and configuration are deduplicated per account for 60 seconds via a canonical content digest and an in-process LRU cache: cache hits return the stored PDF without re-rendering or billing (x-blinkpdf-cache: hit). Authenticated renders echo that digest as the x-blinkpdf-content-digest response header — the same value POST /v1/render/validate returns — so a client can correlate a validate with its later render. It is a digest of the request/config, not a hash of the output PDF bytes: an inert change (a rule matching nothing) shifts the digest without changing the rendered bytes, so compare the file bytes to detect a visual change. Optional x-idempotency-key still deduplicates safe client retries across the billing period; reusing a key with a different body returns 409 idempotency_conflict before rendering. Caching and idempotency are independent: a cache hit replays bytes without re-rendering, whereas a reused idempotency key can re-render (cache miss) yet still not increment the usage counter. The x-blinkpdf-billing response header reports which of the three outcomes occurred (counted, deduped-cache, deduped-idempotent) — read it rather than inferring billing from the usage counter staying flat.

Pass an optional theme slug to apply a ready-made design preset that resolves server-side to a fixed bundle of typography, page, furniture, numbering, and styling rules, then merged under anything you send yourself — your page/typography/furniture fields and your rules win on every conflict, and declaring your own font (googleFontsUrl(s), typography.body/heading, or a weighted fontStack) drops the theme’s font entirely. Theme fonts are bundled (hosted) families, so a theme never depends on Google at render time and the same source plus the same theme always renders the same bytes. The theme is chosen by you; the service never inspects your Markdown to pick one. An unrecognized slug falls back to report-clean (the unstyled default) without failing the render; POST /v1/render/validate echoes the resolved theme in its resolvedTheme field. Available themes (slug — use it when): report-clean — generic report or deep-dive; the clean default report-executive — 1–2 page executive brief or summary report-data — report dense with tables and KPIs blog-modern — casual web post or article blog-dark — screen-first dev post on a dark sheet blog-editorial — long-form magazine-style narrative academic-classic — traditional numbered journal paper academic-modern — modern preprint or working paper thesis — thesis or long monograph with chapters docs-light — README, guide, or technical docs docs-dark — terminal-tone docs or notes api-reference — API/endpoint reference corporate — formal company report or memo proposal — proposal, quote, or SOW invoice — invoice or receipt

This endpoint always renders bytes; any query parameter (including ?preview=) is rejected with 400 invalid_input (preview modes resolved/layout live on POST /v1/render/validate). Rules that pass validation but never apply (a set property or selector axis not valid for the selected node type, a heading depth outside 1–6, or a rule that matched zero nodes in the rendered document) are reported non-blockingly via the X-Render-Rule-Warnings response header; resolved set values that render inert (a non-square circle mask, an all-zero table widths) are reported via X-Render-Static-Warnings.