How a program asks for its pages

A program writes down the document it wants, sends that description over the network, and gets the finished pages back in the same breath. Here is how, in plain words first and then to the letter.

What happens, in plain words

Think of ordering a cake. You write on a slip of paper what you want — the size, the words piped on top, the picture in the middle — you hand the slip across the counter, and a little later the cake comes back. You never see the oven, and you do not need to.

This works the same way. Your program writes down what the document should hold: this paragraph here, this table there, this picture in the corner. It sends that slip across the network to our document server. The server draws the pages and hands the finished PDF straight back, in answer to that one call.

The slip is written in a form every machine agrees on, called JSON. It is ordinary text, made of names and values, and it reads the same whatever your program itself is written in.

There is nothing to install for this. Your program already knows how to send something across the network, and that is the whole of what is being asked of it.

The same thing, for whoever writes the program

Your program posts one form to the server. One part of that form carries the description of the document. Every other part is a file the document draws on: a sheet of headed paper to lay the pages over, a colour profile, the data an electronic invoice carries. What a file is there for is settled by the description that names it, never by the file itself.

The answer is the document. Not a link to fetch it later, not a ticket number to ask about again: the bytes of the finished PDF come back in the answer to that one call.

Two extra lines of the answer say how long the work took — one for reading the description, one for drawing the pages, both to the thousandth of a millisecond. That is how you tell the time spent on the network from the time spent drawing.

One request may run to half a gigabyte, which is a great deal of headed paper, and whoever runs the server may set a smaller size. A request above it is turned away with that size written in the answer.

Who may call, how often, and for how long a document may be drawn are settled in front of the server, by whatever already faces the network. The server itself is given the name of the account and draws what that account is allowed.

The exact names

What the request and its answer are made of
The address that draws a document	`POST /render`
The address that says the service is up	`GET /health`
The shape the request is sent in	`multipart/form-data`
The part of it carrying the description	`json_data`
How the key travels	`Authorization: Bearer <key>`
What comes back	`application/pdf`
How long reading the description took	`X-HQF-Parse-Ms`
How long drawing the pages took	`X-HQF-Render-Ms`

A whole request, as short as one can be

This asks for one page with one line of text on it. Save it beside your program, send it, and a 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
    }
  ]
}

And this is the one line that sends it.

curl -X POST https://your-server/render \
  -H "Authorization: Bearer <your key>" \
  -F "json_data=@hello.json;type=application/json" \
  -o hello.pdf

The round trip, drawn

Between two boxes there are always two arrows: the first says what is asked for, the second says what comes back.

Your own program runs at the customer's
on the way there: the document described as text, and the files it draws on on the way back: the finished PDF, and how long the drawing took
The PDF server on the address you call
on the way there: one call per thing to draw: a paragraph, a table, an image on the way back: the pages, drawn
The PDF library inside the PDF server

Two pieces, and why there are two

The server draws nothing itself. It reads the description, checks it, and then calls the library one instruction at a time: set this paragraph, start this table, place this picture here. The library is what writes the file.

They are two because they do two different jobs. The library knows how to draw and knows nothing of the network. The server knows the network — who is calling, how large a request may be, how many pages an account is allowed — and knows nothing of drawing.

There is a plainer reason still. The library works with lettering already loaded and ready to draw with, while a description arriving over the network holds only its name. Turning that name into lettering the library can use is exactly the server's job, and it is done before the first letter lands on a page.

This is why the library can be bought and used on its own, called straight from a program written in Rust or in Python, with no server and no description travelling anywhere. And it is why the same document comes out the same either way: the same library draws it.

Drawing a document keeps a processor busy from beginning to end, so each one is handed to a worker of its own and the server goes on answering everybody else meanwhile.

What comes back when the request is not right

Every answer says what happened in a sentence, not in a code to look up somewhere. And nothing half-drawn ever comes back: either the pages are there, or the reason is.

A page the document does not have is answered in your own counting. Ask for a link to page nine of a document that has five, and the answer says page nine — the library counts from zero, and the answer does the arithmetic so that you do not have to.

Every answer the server gives, by its number
`200`	The pages are in the answer, and nothing else is.
`400`	Something in the description could not be used: lettering nothing supplies, a position that will not read, a sheet of headed paper that is not a PDF. The answer says which, in a sentence.
`402`	One of the few things a licence key carries. The answer names what was asked for and says that a key covers it.
`413`	The request, or the document it would produce, runs past a size the server was set to allow. The answer names that size.
`500`	Something went wrong on the server's side rather than in your request.

The questions people ask first

Is anything of my document kept?

The pages are not. The finished PDF goes back in the answer to your call, and it is never written to a disk along the way.

The description you sent, and any file you sent with it, are held only for as long as the drawing takes, and only in the machine's own memory. Neither of them is written to a disk, and both are gone the moment the pages leave.

One thing is written down, and only one: lettering. If your account is allowed to send lettering of its own, then a font the drawing really used is kept in a folder belonging to that account, so that you never have to send it a second time — from then on your description simply names it. Lettering that was sent but drawn with nowhere is not kept, and a drawing that failed keeps nothing at all. An account that draws with the lettering already on the server keeps nothing either.

For the bill, four things travel from the document server to this site and nothing else: the name of the account, one identifier standing for that single drawing, the moment it happened, and how many pages came out. Nothing of what is written on those pages goes with them. They wait in a small file until this site has taken them, and leave it as soon as it has.

The server keeps a log, as any program on a machine does. It writes a line when a drawing mentions something it then never used — lettering, a picture, a colour nothing selected — and that line holds the name of the account and the remark. The pages come back either way: it is a remark, not a refusal.

If you run the server on your own machines, none of this reaches us at all. The counting is switched on by naming an address to send it to, and a server that has not been given one sends nothing anywhere.

How is the server called, and in what form?

One address takes the work, and the request is posted to it as a form. One part of that form carries the description of the document, written as ordinary text. Every other part is a file the document draws on. What comes back is the PDF itself.

Anything able to send a form across the network can call it, whatever it is written in. The table above names the address, the shape and the answer exactly, and the short example below is a whole working request.

What does this bring over a free library?

A great many documents are written every day with free libraries, and several of them are very good at what they set out to do. What is sold here is a different thing: one piece that already covers the whole of the ground, and somebody who answers for it.

The ground is wide. Text that flows, tables that carry on over as many pages as they need, pictures, printing colours, barcodes, forms to fill in, files made to still open in twenty years, files made to be read aloud to somebody who cannot see the page, and the room left for a seal. One thing to learn, one thing to keep up to date, and one place to write to when a page does not come out as you expected.

It is checked from outside. There is a free program called veraPDF whose whole job is to open a file and say whether it follows the published rules, and every archival document shown on this site goes through it. We own no part of it, and it knows nothing about who wrote the file in front of it.

The same document is written three ways — a Rust program, a Python program, and a request to the server — and the three are re-run and compared. Where they come out the same to the byte, it is written down beside them; where they come out the same to the eye but not to the byte, that is written down too.

And there is a contract, a company, and a person to write to. Putting several free pieces together is a fine way to work, and it is also work that somebody has to do and go on doing: when two of them disagree, finding out why is yours. Here it is ours.

The library bought outright stays yours: paid once, installed as often as you like, and it does not stop working the day anything runs out.

Do I have to install anything?

On a subscription, no. You call an address across the network and the pages come back. Nothing goes on your machines and nothing has to be kept up to date.

If you buy the server, it is one program to start on your own machines, with a handful of settings: where its lettering lives, where its key lives, and how many pages one document may run to. It listens on the machine itself and sits behind whatever already faces the network at your place.

If you buy the library on its own, it goes inside your program like any other part of it, from Rust or from Python. No server, no network, nothing running beside it.

How am I billed?

By the document and by the page. Each drawing is reported once, with the number of pages it produced, and a month of them is added up into one bill.

A report that could not be sent straight away is not lost: it waits and goes later. And a report that arrives twice is counted once, because each drawing carries an identifier of its own.

Which programming languages can call it?

All of them. The request is ordinary text sent across the network, so anything able to do that can ask for a document — which is every language in everyday use.

The library underneath is written in Rust and is called from Python just as readily, which is what a team buying the library on its own works with.

What does the free version do?

It draws, and it signs its work. Every page it produces carries a notice, and the words on those pages are drawn as shapes rather than as letters, so the pages look right and nothing can be lifted out of them.

A few things are the licence key's own, and a free copy meeting one of them says so plainly and names the key that covers it: setting text in one of the fourteen typefaces every reader already carries, and taking a page from another document that holds more than fifty words of its own. Sending your own lettering with the request is what a free copy draws from.

Which rules are really checked, and by whom?

Files made to stay readable for years, and files made to be read aloud to somebody who cannot see the page, are put through veraPDF, the free checker named above, and it accepts them. It is run by the Open Preservation Foundation and the PDF Association, and we own no part of either.

Files meant for a printing press are held to the four things that trade asks for before a single byte is written, and the file is refused rather than sent out short of one of them. There is a page of this site that says what those four are.

How do I know the service is answering?

There is a second address whose only job is to say so. It draws nothing, costs nothing to ask, and answers for as long as the service is up.

Counting your documents never holds a drawing up. The pages come back first, and the count goes on its own afterwards.

Where to go next

Everything the library puts on a page Files made to still open in twenty years Files a printing works runs without asking

See the prices See the examples

Glossary

PDF library: A piece of software your own programs use to write PDF documents. It has no window and no buttons: your program tells it what to draw, and it hands the finished file back. This site also calls it the engine, which is the same thing under another name. The server is a second program that holds the engine and answers whoever asks it for a document over the network, and the rendering service is that server running on our machines rather than on yours.
byte: The unit a file's weight is counted in, the way a parcel is counted in grams. A thousand of them make a kilobyte, and a million make a megabyte — the size of one photograph taken with a telephone. A one-page PDF here weighs between six thousand and a hundred and twenty thousand, so a hundred of them fit in the space of five photographs.
veraPDF: A free program that checks whether a file really is what it claims to be, against the published rules. It is the tool archives use, so it is the one used here: a document is not called compliant because we say so, but because veraPDF passed it.
Factur-X: An invoice that is a page for a person and a data file for a machine, in one document. The page looks like any invoice; inside, the same amounts are attached in a form accounting software reads without anybody retyping them. French law requires this exchange between companies.
colour profile: A file that says what a colour actually looks like. Without one, the same red is one red on your screen and another on a press. A document meant for print carries the profile its colours were chosen against.
font: The drawing of every letter, digit and mark a document writes, held in a file of its own. A PDF carries the fonts it is set in inside itself, which is why it opens looking the same on a machine that has never had them. Leave them out and a reader puts another font in their place, and the layout moves.
barcode: Black bars and white gaps of different widths, standing for a number a scanner reads back in one pass. The bars carry the number and nothing else: the price, the article and the delivery are looked up from it. A code fetched as a picture and then resized, or trimmed too close, stops being read at all.
request: One call to the service: you send what the document should say, and get the document back. Your bill counts these calls, one for each document. The number of pages inside a document is never counted.

Every word the site explains