Options and paper sizes

Control copies, paper, duplex, color, trays and more.

Options tune how a PDF prints. Every option is optional: anything you omit is filled from the printer’s defaults in the dashboard, and options the printer does not support are ignored and listed as warnings in the job’s stateMessage.

{ "options": { "copies": 2, "paper": "A4", "duplex": "long-edge", "color": false, "pages": "1-3,5" } }

Option	Values	What it does
copies	integer, 1 to 999	Number of copies of each page range
paper	a name from the printer’s papers or customPapers	Paper size, for example A4 or Letter
duplex	long-edge, short-edge, one-sided	Two-sided printing. long-edge flips on the long side (portrait books), short-edge on the short side (calendars)
color	true or false	false prints in grayscale
dpi	text such as 600x600	Print resolution, from the printer’s dpis
bin	a name from the printer’s bins	Paper tray or output bin
media	a name from the printer’s medias	Media type, for example Plain or Photo
collate	true or false	Keep multiple copies in page order
fit_to_page	true or false	Scale the page to fit the paper
rotate	0, 90, 180, 270	Rotate the page in degrees
pages	text such as 1-3,5	Pages to print, as numbers and ranges separated by commas
nup	integer, 1 to 16	Pages per sheet, from the printer’s nup

Unknown option names are rejected with 400 invalid_request. Raw jobs ignore options (see Raw printing).

If an option has a value the printer cannot honour, the job still prints and stateMessage explains what was dropped, for example duplex ignored: printer cannot print two-sided. Read stateMessage on the finished job if the output differs from what you asked for.

Reading capabilities

GET /v1/printers/{id} returns what the printer supports in capabilities. The agent reads it from the operating system, so it reflects the installed driver.

{
  "id": "PRINTER_ID",
  "name": "Test A4 Laser",
  "capabilities": {
    "papers": { "A4": [2100, 2970], "Letter": [2159, 2794], "80mm Receipt": [800, null] },
    "bins": ["Tray 1", "Tray 2"],
    "dpis": ["600x600"],
    "duplex": true,
    "color": false,
    "collate": true,
    "copies": 99,
    "extent": [[900, 1480], [2970, 4200]],
    "medias": ["Plain"],
    "nup": [1, 2, 4],
    "printrate": { "unit": "ppm", "rate": 30 },
    "supports_custom_paper_size": false
  },
  "defaultOptions": { "paper": "A4", "duplex": "long-edge" },
  "customPapers": []
}

papers maps each paper name to [width, height] in tenths of a millimetre, so "A4": [2100, 2970] is 210 by 297 mm. bins, dpis and medias list the values you can pass to bin, dpi and media. A paper dimension can be null when the driver does not report it, as for a roll of receipt paper ("80mm Receipt": [800, null], 80 mm wide with no fixed length). extent is [[minWidth, minHeight], [maxWidth, maxHeight]] in the same unit and gives the range of custom paper sizes the printer accepts, or null. printrate is the printer’s rated speed, for example 30 pages per minute, or null. duplex, color and collate say whether the printer supports them, copies is the largest copy count it accepts, and nup lists the pages per sheet it offers.

Printer defaults and custom paper sizes

Set defaults once and send only what differs per job. In the dashboard, open the printer and edit its defaults. Over the API, use PATCH /v1/printers/{id} with the admin scope:

curl -X PATCH https://api.inkrelay.app/v1/printers/PRINTER_ID \
  -H "Authorization: Bearer $INKRELAY_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "defaultOptions": { "paper": "A4", "duplex": "long-edge", "color": false },
    "customPapers": [{ "name": "Label 100x150", "width": 1000, "height": 1500 }]
  }'

customPapers adds paper sizes the printer does not list, such as label stock. width and height use the same unit as papers, tenths of a millimetre, so the example above is 100 by 150 mm. Once saved, pass the name as paper. A printer accepts up to 50 custom papers. Sending customPapers replaces the whole list.

PATCH /v1/printers/{id} also sets displayName, enabled (the live switch) and remarks.

Platform notes

• nup works on macOS and Linux only.
• On Windows, PDFs print through SumatraPDF. pages, copies, fit_to_page, rotate (90 and 270), color, duplex, paper and bin are honoured. dpi, media, collate, nup and rotate 180 are ignored, so a job that asks for rotate 180 prints without rotation. Each ignored option adds a warning to stateMessage.
• dpi, media and collate apply on macOS and Linux.
• Paper names come from the operating system and the driver. Read papers before you hard-code a name.