Print Jobs API

Create Job

POST /v1/print-jobs

Request:

Use printer_code from GET /v1/printers to target the printer. Legacy printer_id is still accepted for existing integrations.

Send either content as base64 or content_url as a public HTTP/HTTPS URL.

Base64 content:

{
  "printer_code": 1000000,
  "content_type": "pdf",
  "content": "JVBERi0xLjQK...",
  "copies": 1,
  "options": { "duplex": false }
}

Public URL:

{
  "printer_code": 1000000,
  "content_type": "pdf",
  "content_url": "https://example.com/label.pdf",
  "copies": 1,
  "options": { "duplex": false }
}

Response:

{ "id": "job_abc", "status": "queued" }

Local Agent Printing

When the desktop agent enables local web printing, it listens on the loopback address http://127.0.0.1:17891. Browser code can call the same path and request shape:

POST http://127.0.0.1:17891/v1/print-jobs

The local agent prints immediately on the user's machine. After the local print finishes, the agent records the job back to the cloud asynchronously, so the browser request is not blocked by the cloud record call.

The local request body matches the cloud create request:

{
  "printer_code": 1000000,
  "content_type": "pdf",
  "content_url": "https://example.com/label.pdf",
  "copies": 1,
  "options": { "source": "dashboard_url" }
}

The local response uses a local job id and a completed status when the system spooler accepted the job:

{
  "id": "local_1nk5ajf4zq",
  "status": "completed",
  "printer_code": 1000000,
  "delivery_mode": "local_agent"
}

Record Local Job

POST /v1/print-jobs/local-records

This endpoint is for trusted PrintBase agents only. It creates cloud history for a job that was already printed locally and does not enqueue the cloud dispatcher. Normal integrations should use POST /v1/print-jobs.

Get Job

GET /v1/print-jobs/{id}

Example response:

{
  "id": "job_abc",
  "status": "printing",
  "printer_id": "printer_123",
  "printer_code": 1000000,
  "content_type": "pdf",
  "content_url": "https://example.com/label.pdf",
  "copies": 1,
  "options": { "duplex": false },
  "created_at": "2026-06-17T11:55:27Z",
  "updated_at": "2026-06-17T11:55:29Z"
}

The response does not include inline base64 content.

Job status state machine

queued -> dispatched -> printing -> completed

Possible failure status:

• AGENT_OFFLINE
• PRINTER_OFFLINE
• DOWNLOAD_FAILED
• PRINT_ERROR
• INVALID_CONTENT