> ## Documentation Index
> Fetch the complete documentation index at: https://docs.inkrelay.app/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`.

```json theme={null}
{ "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](/guides/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.

```json theme={null}
{
  "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:

```bash theme={null}
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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.