The PDF version the file declares

Choose the version the document announces, from 1.4 to 2.0, by what it carries and by the age of the software reading it.

Written at the top level of a request, under "version"

In plain words

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

The PDF format has several generations, the way cars have model years. The first line of the file announces its own, and it is a promise: here is what you need to know how to do in order to show me whole. Software older than the version announced shows what it can and leaves the rest aside, quietly — which is why the choice is worth making rather than inheriting.

For a developer

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

version sets the version the first line of the file declares. Each version brings what the library writes: 1.4 transparency, tagged content and the metadata packet; 1.5 layers, two-page spreads and the sliding transitions; 1.6 opening on the list of attachments and print scaling; 1.7 the wishes a print dialogue reads; 2.0 taking the print size away from the reader. Nothing is raised on the caller's behalf: a document declaring less than what it carries is refused when written, naming the part that asked for more.

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.

  • version — string, optional. Absent, the document is written as 1.7.
  • Five values: "1.4", "1.5", "1.6", "1.7", "2.0".
  • archive settles the version on its own side: pdfa3b imposes 1.7, pdfa4 imposes 2.0. A version written in the request is applied afterwards.
  • Known demands: layers and object streams want 1.5; the print wishes of reading want 1.7; reading.lock_actual_size and the annotations and widgets tab orders want 2.0.

A whole request that draws it

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

{
  "version": "2.0",
  "standard_fonts": [{ "name": "sans", "face": "helvetica" }],
  "items": [
    {
      "type": "text",
      "rect": { "llx": 60, "lly": 740, "urx": 535, "ury": 762 },
      "content": ["This file announces PDF 2.0"],
      "font": "sans",
      "font_size": 14
    }
  ]
}

The line that sends it, in three languages

The document as a whole

The numbers the reader shows A hundred letters in a single file What the document says about itself A file still readable in thirty years An invoice a person and a machine both read The address relative links are read against What an image says about itself

Where to go next

Every key of a request, in one page The other thirty-two settings of a request

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.
the identity card of a file
The block inside a file that says what the file is: its title, who made it, when, and which rules it follows. Search engines and archives read it; a reader never sees it. Its technical name is XMP.
transparency
Paint that lets what is underneath it come back through, by a stated amount. It is what makes a mark laid across a page leave the text under it readable, and a highlight a highlight rather than a blot. The file says how much comes through; whatever draws the page works out the colour that results.
tagged PDF
A PDF that carries the structure of its own text alongside the drawing: this is a heading, this is a table, this cell belongs to that column. It is what lets a reading aid, or a program pulling data back out, make sense of the page.
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.
layer
A named group of things drawn on a page that a reader can switch on and off, like tracing paper laid over a plan. A drawing can hold its measurements on one and its notes on another, and a layer can be set to show on screen and stay off the printer.
annotation
Something laid over a page rather than drawn into it: a clickable rectangle, a box to type in, a button. It sits at its own place on the sheet and is what makes a PDF answer to a click at all.

Every word the site explains