The areas a page states

In plain words

Written for anybody. It says what this puts on a sheet of paper, and asks nothing of you beyond that.

When a printer makes a business card, the ink goes onto a larger sheet and the card is cut out afterwards. So that the colour truly reaches the edge, it runs a little past the cutting line: the blade never falls in exactly the same place twice. The page can carry these marks with it: here is where the cut falls, here is how far the ink runs, here is the drawing that really counts. Each mark is a rectangle given by its bottom-left corner, its width and its height.

For a developer

Written for somebody who writes the calling program: the model, the units, and the settings that carry the weight.

page_boxes states, page by page, the four boxes a PDF knows beyond the sheet itself: what a reader shows and prints, the ink overrun, the cutting line, and the useful drawing. Each box stays out of the file until the request writes it, and a reader then takes the whole sheet in its place. A box running off the sheet is accepted: a reader intersects it with the sheet, so it simply says more than it is worth.

Every key, with its default

The reference: which keys are required, which are optional, what each one defaults to and which combinations the server declines.

• page_boxes — array, optional, empty by default.
• page_boxes[].page — integer ≥ 1, required. The page the entry is for.
• page_boxes[].crop — object, optional. What a reader shows and prints. Anything outside stays in the file and stays there for whoever wants it back.
• page_boxes[].bleed — object, optional. What the press lays ink on, ink that runs past the cut.
• page_boxes[].trim — object, optional. Where the blade falls: the page as it leaves the bindery.
• page_boxes[].art — object, optional. What is worth keeping of the page, the drawing without its margins.
• Every box carries x, y, width, height: numbers, all required. x and y are the bottom-left corner.

An entry says what is done with a page, not that there is one: a page named past the end of the document leaves the document as long as it already was. A page named twice takes the last entry, whole.

A whole request that draws it

Post this as it stands and a PDF comes back. Nothing has been left out of it.

{
  "page_boxes": [
    {
      "page": 1,
      "bleed": { "x": 9, "y": 9, "width": 577, "height": 824 },
      "trim": { "x": 18, "y": 18, "width": 559, "height": 806 }
    }
  ],
  "standard_fonts": [{ "name": "sans", "face": "helvetica" }],
  "items": [
    {
      "type": "rect",
      "rect": { "llx": 0, "lly": 0, "urx": 595, "ury": 842 },
      "fill": [0.93, 0.95, 0.98]
    },
    {
      "type": "text",
      "rect": { "llx": 60, "lly": 740, "urx": 535, "ury": 765 },
      "content": ["The colour runs past the cutting line"],
      "font": "sans",
      "font_size": 14
    }
  ]
}

The line that sends it, in three languages

Glossary

CMYK

The four inks a printing press lays down: cyan, magenta, yellow and black. A screen mixes light instead, so a document going to a press states its colours in inks, not in screen colours.

blade

The knife that cuts a printed sheet down to the finished page. It comes down on a whole stack at once, so it lands within a fraction of a millimetre of the line rather than on it — which is the reason a page printed to its edge is drawn larger than it will be.

bleed

The colour that runs past the line the blade will cut, so that a cut a hair out of place still lands in ink rather than beside it. Three millimetres is the usual amount. Without it, a page printed to its edge comes back with a white sliver down one side.

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