API reference · RocketPrint

Authentication

Pass your key in the X-API-Key header on every request. Keys belong to one account, start with rp_live_, and stored only as a hash — if you lose one, revoke it and create another.

bash

curl https://rocketprint.io/api/v1/printers \
  -H "X-API-Key: $ROCKETPRINT_KEY"

Endpoints

Endpoint	What it does
POST`/v1/print-jobs`	Create a print job and send it if the printer is online.
GET`/v1/print-jobs`	List jobs, newest first. Filter by status and printer.
GET`/v1/print-jobs/:id`	Fetch one job and its current status.
DELETE`/v1/print-jobs/:id`	Cancel a job that is still pending.
GET`/v1/printers`	List registered printers with presence and station.
GET`/v1/printers/:id`	Fetch one printer.
GET`/v1/scales`	List connected scales and their latest readings.
GET`/v1/scales/:id`	Read one scale and its measurement state.

Create a print job

POST /v1/print-jobs — returns 201 with the created job, or 200 with the original job if this is an idempotent replay.

Field	Type	Notes
`printerId`	`string`	Required. An ID from `GET /v1/printers`.
`contentType`	`enum`	Required. One of `raw_base64`, `pdf_base64`, `text`, `raw_uri`, `pdf_uri`. The URI variants are disabled by default and return a validation error.
`content`	`string`	Required. Base64 payload, plain text, or a URL. Maximum 10 MiB.
`title`	`string`	The name shown in your account. Defaults to "Untitled".
`source`	`string`	Free-form origin tag, e.g. your service name. Useful for filtering later.
`options.copies`	`integer`	Number of copies, minimum 1. Copies are one job, and bill as one job.
`expiresInSeconds`	`integer`	How long the job may wait in the queue before it becomes `expired`. 10 to 86400; the default is 3600. See job statuses.

bash

curl -X POST https://rocketprint.io/api/v1/print-jobs \
  -H "X-API-Key: $ROCKETPRINT_KEY" \
  -H "Idempotency-Key: order-1042-label" \
  -H "Content-Type: application/json" \
  -d '{
    "printerId": "6a4738f7462183c7f5d70598",
    "title": "Order #1042 label",
    "contentType": "raw_base64",
    "content": "XlhBLi4uXlha",
    "source": "my-shop",
    "options": { "copies": 1 }
  }'

Idempotency

Send an Idempotency-Key header on every create. It is tied to your account and API key, and can be up to 200 characters — build it from your own order or shipment ID.

An identical retry returns 200 with the original job and the header Idempotency-Replayed: true. Nothing prints twice.
A different payload under a key you already used returns 409 rather than printing something unexpected.
Replays do not count as billable jobs.

The job object

Field	Type	Notes
`id`	`string`	Opaque job ID. Store it against your own record.
`organizationId`	`string`	The account that owns it.
`printerId`	`string`	The target printer.
`stationId`	`string`	The station assigned when the job was created.
`status`	`enum`	One of `pending`, `dispatching`, `sent`, `printing`, `completed`, `failed`, `canceled`, `expired`, `unknown`. Every value is defined in the job statuses table below.
`error`	`string`	Present when status is `failed`, `expired`, or `unknown`.
`idempotencyKey`	`string`	Present when the create supplied one.
`title`	`string`	As supplied at creation.
`contentType`	`string`	As supplied at creation.
`source`	`string`	As supplied at creation.
`createdAt`	`date-time`	When we accepted and persisted the job.
`sentAt`	`date-time`	When it was delivered to the Station app.
`completedAt`	`date-time`	When the Station app reported the result.

Job statuses

This is the complete set of status values. A job only moves forward, and the last five are final. The one exception is unknown, which a later Station report can settle to completed or failed. The reliability page walks through the same lifecycle in more depth.

Status	Final	What it proves
`pending`	`no`	Checked and saved, not yet delivered. A job waits here while its computer is offline. This is the queue.
`dispatching`	`no`	Claimed by one of our servers so the same job can never be sent twice.
`sent`	`no`	Delivered to the Station app attached to that printer.
`printing`	`no`	Your computer's print system accepted the job.
`completed`	`yes`	The print command succeeded through the operating system's print path. It does not prove paper came out, and it cannot see an empty roll, a jam, or a faded printhead.
`failed`	`yes`	Not printed. `error` says why. Failed jobs are never billed.
`canceled`	`yes`	You canceled it before it was sent.
`expired`	`yes`	Not dispatched before its queue deadline, so it was never sent. Set the deadline with `expiresInSeconds` when you create the job.
`unknown`	`yes`	The print was interrupted and the outcome was not confirmed. It may or may not have printed. Inspect the printer before creating another job. A later Station acknowledgment can settle it to `completed` or `failed`.

List and fetch jobs

GET /v1/print-jobs returns jobs newest first under a printJobs key.

Query	Type	Notes
`status`	`enum`	Filter to one value from the job statuses table.
`printerId`	`string`	Filter to one printer.
`limit`	`integer`	Default 50, maximum 200.

Cancel a job

DELETE /v1/print-jobs/:id cancels a job that is still pending. Once dispatched, a job is no longer cancelable and the request returns 409.

Printers

GET /v1/printers lists everything your stations have registered.

Field	Type	Notes
`id`	`string`	Use this as `printerId` when creating jobs.
`name`	`string`	Display name.
`systemName`	`string`	The OS queue name on the station.
`status`	`enum`	`online` or `offline`.
`stationId`	`string`	The station that owns this queue.
`isDefault`	`boolean`	Whether it is the station's default printer.
`agentName`	`string`	Name of the station that reported it.
`agentHostname`	`string`	Hostname of that computer.
`lastSeenAt`	`date-time`	Last presence report.

A printer being offline does not mean you cannot print to it — jobs queue and print when it returns.

OpenAPI

The public API is described by an OpenAPI 3.1 document, which you can use to generate a client or load into your own tooling. It is the same description this page is written from.

Handling failures?

Every error code, what causes it, and what to do about it.

Errors and limits

Printer defaults and queue deadlines

Jobs inherit defaults saved in Setup & print. Override copies (1–100), paperSize (A4, Letter, Legal, or 4x6), color, duplex, or landscape in options. RAW jobs accept copies only; encode other settings in the printer language. Unsupported settings return HTTP 400.

Set expiresInSeconds from 10 to 86400; the default is 3600. Jobs that remain queued past the deadline become expired and are never dispatched. Cancel a pending job with DELETE. A job with an unconfirmed Station outcome becomes unknown; inspect the printer before creating another job. Both are defined in the job statuses table.