Authentication
Pass your key in the X-API-Key header on every request. Keys are organization-scoped, prefixed rp_live_, and stored only as a hash — if you lose one, revoke it and create another.
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 dispatch 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 | Display name in the console. 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. |
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 scoped to your organization and API key, and can be up to 200 characters — derive it from your own order or shipment ID.
- An identical retry returns
200with the original job and the headerIdempotency-Replayed: true. Nothing prints twice. - A different payload under a key you already used returns
409rather 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 owning organization. |
printerId | string | The target printer. |
stationId | string | The station assigned when the job was created. |
status | enum | pending, dispatching, sent, printing, completed, failed, canceled. See the state model. |
error | string | Present when status is failed. |
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 agent. |
completedAt | date-time | When the agent reported the outcome. |
List and fetch jobs
GET /v1/print-jobs returns jobs newest first under a printJobs key.
| Query | Type | Notes |
|---|---|---|
status | enum | Filter to one status. |
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 agents 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 | Agent identifier. |
agentHostname | string | Hostname of the station machine. |
lastSeenAt | date-time | Last presence report. |
A printer being offline does not mean you cannot print to it — jobs queue and dispatch 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.