The API that draws your documents

The transport

One endpoint, one method: a POST with a multipart/form-data body. The part named json_data holds the whole description as JSON. Every other part is a named binary the description addresses by that part's name — a PDF used as a template or imported page by page, an image, an ICC profile, an XMP packet, the XML of an invoice. There is no upload step and no asset identifier to keep: a part lives for the call it travelled in.

Authentication is a bearer key checked by the reverse proxy, which resolves it to a client name and forwards that name in a header of its own. A success answers 200 with application/pdf, plus the parse time and the drawing time in milliseconds. A refusal answers a status code and one sentence of plain text. There is no envelope to unwrap and no job to poll.

The model

A request is a flat document: a list of items, and beside it the resources those items name. Fonts, colour spaces, gradients, graphics states, layers and drawings are each declared once under a name, and an item refers to that name. Nothing is positional and nothing is implicit — a name an item calls for and no declaration carries is refused, with the name in the message.

Pages are created by what is drawn on them, not declared up front. An item states which pages it lands on; the default, an empty array, is every page, which is how a footer or a watermark is written once. A table that overflows its box carries on into the next box and creates the pages it needs, and the items keyed to every page follow it there.

Geometry is in typographic points with the origin at the bottom left, as the format itself has it. Any coordinate may be a quoted arithmetic expression over the page dimensions and the current page number, so a right margin is "{page_width} - 56" rather than a number your program had to work out. An item may name itself and another may hang off its edge, which is what keeps a layout right when the height of a block is only known after it is set.

What a request carries beside the drawing

The same request states the document's metadata, the archival standard it claims, the output intent its colours are read against, the compression of its streams, the outline and the named destinations, the article threads, the page labels, the reading preferences a viewer honours, and the invoice XML a Factur-X document carries. One call produces a finished, standards-claiming file: there is no second pass and no post-processing tool.

Failure modes, and what they cost

Validation is total and happens before anything is drawn: the server declines a request rather than producing a document that quietly lost something. A refusal is one sentence naming the key or the name at fault, so it is worth logging verbatim.

Unknown keys are ignored, which makes a request written for a later version safe to send at an earlier one. A key written twice in the same object is declined by name. Combinations that would contradict each other — a matrix together with a rotation, a link with both a short target and a full action, a table cell holding two things — are declined by name as well.

The smallest request that draws something

One declared face, one item, one line of text. Save it, post it, and a one-page PDF comes back.

{
  "standard_fonts": [{ "name": "sans", "face": "helvetica" }],
  "items": [
    {
      "type": "text",
      "rect": { "llx": 56, "lly": 700, "urx": "{page_width} - 56", "ury": 780 },
      "content": ["Invoice 2026-014"],
      "font": "sans",
      "font_size": 24
    }
  ]
}

The same call, written three times

Copy whichever of these matches your stack. Each posts the description and one file it draws on, and writes the answer straight to disk.

From a shell

One part carries the description, one part per file it draws on. The name of a part is the name the description calls that file by.

curl -X POST https://your-server/render \
  -H "Authorization: Bearer $HQF_PDF_KEY" \
  -F "json_data=@invoice.json;type=application/json" \
  -F "letterhead.pdf=@letterhead.pdf" \
  -o invoice.pdf

From Python

The answer is the PDF itself, so write the body straight to a file. The two timing headers are there whenever the drawing succeeded.

import json
import pathlib
import requests

LETTERHEAD = pathlib.Path("letterhead.pdf")

description = {
    "standard_fonts": [{"name": "sans", "face": "helvetica"}],
    "items": [
        {
            "type": "text",
            "rect": {"llx": 56, "lly": 700, "urx": "{page_width} - 56", "ury": 780},
            "content": ["Invoice 2026-014"],
            "font": "sans",
            "font_size": 24,
        }
    ],
}

answer = requests.post(
    "https://your-server/render",
    headers={"Authorization": f"Bearer {KEY}"},
    files={
        "json_data": ("request.json", json.dumps(description), "application/json"),
        "letterhead.pdf": ("letterhead.pdf", LETTERHEAD.read_bytes()),
    },
    timeout=120,
)
answer.raise_for_status()
pathlib.Path("invoice.pdf").write_bytes(answer.content)
print(answer.headers["x-hqf-render-ms"], "ms drawing")

From JavaScript

A form body and the standard fetch, so the same lines run in a browser and in a server-side runtime. A refusal arrives as a sentence of plain text.

const description = {
  standard_fonts: [{ name: "sans", face: "helvetica" }],
  items: [
    {
      type: "text",
      rect: { llx: 56, lly: 700, urx: "{page_width} - 56", ury: 780 },
      content: ["Invoice 2026-014"],
      font: "sans",
      font_size: 24,
    },
  ],
};

const body = new FormData();
const asJson = JSON.stringify(description);
body.append("json_data", new Blob([asJson], { type: "application/json" }));
body.append("letterhead.pdf", letterheadBlob, "letterhead.pdf");

const answer = await fetch("https://your-server/render", {
  method: "POST",
  headers: { Authorization: `Bearer ${key}` },
  body,
});
if (!answer.ok) {
  throw new Error(await answer.text());
}
const pdf = new Uint8Array(await answer.arrayBuffer());

The keys of a request

Thirty-three keys stand at the top level of a request, and one of them is required. Every other key defaults to the value in the column beside it, so a request states what it needs and nothing else.

The twenty-one things an item can be

An item is an object carrying a type. Each type has a page of its own: what it is, what a developer needs to know about it, every key it takes with its default, and a whole request showing it.

Text

• A block of text placed on the page text Set text inside a chosen rectangle, with its font, size and colour, and give one word in the middle of a sentence a style of its own.
• Text in paragraphs, with indents and tab stops flow Lay several paragraphs in a frame, with a first-line indent, space between them, bulleted lists and neat columns of figures.
• A stamp laid across the page stamp Lay one word across an area, at the size that fills the box: draft, paid, copy, cancelled, on the diagonal or flat.

Tables

• A table that carries on from page to page table Rows and columns flowing over as many pages as needed, with a repeated header, rules, coloured backgrounds and merged cells.

Pictures and imported pages

• A picture placed in a rectangle image Place a photo or a logo supplied with the request in a chosen frame, stretched to the edges or kept at its own proportions.
• A page of a supplied PDF, placed on the page pdf_page Take one page of a PDF sent with the request and place it in a frame, at its own proportions, among the other items.

Barcodes and square codes

• A barcode of vertical bars barcode Draw a barcode a scanner reads: Code 128 for text, and EAN-13, UPC-A or EAN-8 for a retail article number.
• A square QR code, read with a phone qr Draw a QR code carrying a web address or a piece of text, read by any phone, with its white margin all around.
• An Aztec code, with no white margin around it aztec Draw an Aztec code, the one on train tickets: square, needing no margin, with the share of safety you choose.
• A Data Matrix code, very small and very sturdy data_matrix Draw a Data Matrix code, the one on parcels and small parts: as much content as a QR code in far less room.
• A PDF417 code, carrying a whole form pdf417 Draw a PDF417 code of stacked bars, the one on boarding passes: it carries a whole form, not merely a number.

Shapes

• A free path: lines, curves and filled shapes path Draw a shape point by point, with straight segments and curves, filled with a colour or a gradient, and outlined with a stroke.
• A rectangle, filled or outlined rect Place a rectangle: a coloured band behind a heading, a frame around an area, or both, with the stroke you choose.
• A straight line between two points line Pull a line from one point to another, at the thickness, colour and dash you want: a divider, an underline, a ruled row.

Form fields

• A box the reader types into text_field Add a box to fill in: a name, an address, a comment over several lines, a hidden password, or a number one box per digit.
• A box the reader ticks check_box Add a tick box: accepting terms, choosing an option, with the mark you pick and the value the form reports.
• A list the reader picks from choice_field Offer a list of answers: an open list, a drop-down menu, or a menu the reader may also type an answer into.
• Several buttons, one answer radio_group Place buttons of which only one stays chosen at a time, each in its own spot, all belonging to the same question.
• The place kept for a signature signature_field Keep a spot on the page where an electronic signature will settle, with its name and its frame.
• A button the reader presses push_button Place a button that acts instead of answering: open an address, go to a page, send the form or reset it.

Navigation

• A patch of page a reader clicks link Make a patch of page clickable: it opens a web address, or takes the reader to another page of the same document.

The shapes every key is built from

A handful of objects recur throughout the format. They are written once here, and every page that uses one names it by these words.

How a request is read

• A key the server does not know is ignored, so a request written for a later version renders at an earlier one.
• A key written twice in the same object is declined, and the message names the key.
• A choice with no payload is written as a bare string — "center", "pdfa4". A choice carrying a payload is a single-key object naming the variant — {"points": 12}, {"page": 3}.
• An absent optional key and an explicit null are read the same way, which is what lets a serialiser emit either.
• The same description, posted twice, yields the same bytes twice: the file identifier is a digest of what was written, so two runs can be compared as files.

The figures the service holds itself to