REST API v1

Public API v1 (/v1, API keys in Authorization: Bearer jp_live_…), the dashboard API and the agent endpoints. Errors use the A9 format { error: { code, message, retryable, details? }, requestId }; every response has an x-request-id header. Lists return { data, nextCursor }.

Base URL: https://api.jodaprint.dev (or your self-hosted cloud).

Authentication

Create an API key in Dashboard → Developers → API keys and send it as a bearer token:

curl https://api.jodaprint.dev/v1/me -H "Authorization: Bearer jp_live_…"

jp_live_ keys print on real printers. jp_test_ keys use the sandbox: jobs go to a virtual printer in the cloud and GET /v1/jobs/{id}/preview returns the image. Each key has scopes:

Scope	Allows
jobs:write	Create, cancel and reprint jobs; preview receipts
jobs:read	Read jobs and templates
printers:read	List printers
devices:read	List devices
devices:write	Manage devices (dashboard features)
webhooks:write	Manage webhook endpoints

Conventions

• Errors use the format { "error": { "code", "message", "retryable", "details" }, "requestId" }. See Error codes.
• Lists return { "data": [...], "nextCursor": "..." }. Pass cursor to get the next page.
• Idempotency: POST /v1/jobs and reprints accept an Idempotency-Key header. The same key within 24 hours returns the first job and prints nothing.
• Rate limits: 100 requests per second per API key by default. Over the limit, the API answers 429 with RATE_LIMITED and a Retry-After header.

Endpoints

Endpoint	Summary
GET /v1/jobs	List jobs, newest first
POST /v1/jobs	Create a print job
GET /v1/jobs/{id}	Get a job with its state history
GET /v1/jobs/{id}/preview	Preview of a sandbox job
POST /v1/jobs/{id}/cancel	Cancel a queued cloud job
POST /v1/jobs/{id}/reprint	Print a job again
GET /v1/printers	List printers
GET /v1/printers/{id}	Get a printer
GET /v1/devices	List active devices
GET /v1/devices/{id}	Get a device
GET /v1/templates	List templates
GET /v1/templates/{id}	Get a template
GET /v1/webhooks	GET /v1/webhooks
POST /v1/webhooks	POST /v1/webhooks
DELETE /v1/webhooks/{id}	DELETE /v1/webhooks/{id}
POST /v1/receipt/preview	Preview a receipt
GET /v1/me	GET /v1/me

The full OpenAPI document, including the dashboard's internal endpoints, is at /openapi.json.