Skip to content

Latest commit

 

History

History
432 lines (353 loc) · 25.3 KB

api.md

File metadata and controls

432 lines (353 loc) · 25.3 KB

HTTP API

All endpoints speak JSON over HTTP. Authentication is a bearer token: Authorization: Bearer <token>.

Roles:

  • client — the bootstrap PRINTAPI_TOKEN, any active issued key (see API keys), or a session token from POST /login. An issued key and a session only ever see their own org; the bootstrap token spans all of them — see Multi-tenancy.
  • manage — root or a session (an account login): the org's keys, users and settings. A machine key is deliberately excluded, so a leaked integration key cannot issue itself a successor — see Accounts and login.
  • root — the bootstrap PRINTAPI_TOKEN only (orgs, and the first user of an org)
  • agent — the per-agent key (bound to the agent name on first contact)

Token comparison is constant-time (hmac.compare_digest).

Endpoints

Method & path Auth Purpose
GET / none Web dashboard (static bundle embedded in the binary; data fetched with the token)
GET /health none Liveness check, plus whether this server offers signup and password_reset
GET /metrics client Prometheus text: job counts by state, agent/printer liveness
POST /jobs client Submit a job → {job_id}
GET|POST /labels, GET|PUT|DELETE /labels/{id} client Label templates: where the content sits on a label; jobs of type label_* render through them
POST /orders client Render an order as a packing slip and print it → {job_id} (e-commerce)
POST /integrations/shopify/orders HMAC Shopify order webhook (key in the URL, signature in the header)
GET /jobs client Recent job history. With retention set, old jobs lose payload and title (title is null), and rows from before the current month disappear after at least 7 days
GET /jobs/{id} client One job's state: queued | claimed | done | failed | cancelled
DELETE /jobs/{id} client Cancel a still-queued job (409 once claimed, 404 if unknown)
GET /printers client Registered printers + online/offline + capabilities
GET /computers client Registered agents + online/offline + printer count
POST /login none E-mail + password → {token, expires_at, org_id, user_id}
POST /signup none Self-serve org + first account + session (403 unless the operator opened it)
POST /password/reset none Mail a one-shot reset token — always {"ok": true}
POST /password/reset/confirm none {token, password} → sets it and logs every browser out
POST /logout session End this session server-side
GET /me any {kind: root|session|key, org_id} (+ email, user_id for a session)
PUT /me/password session {current, new} — changes it and logs every browser out
POST /users manage Add a user to the caller's own org → {id, email, org_id}
GET /users manage Users of the caller's org (root: all orgs)
DELETE /users/{id} manage Remove an account (never your own, never an org's last one)
POST /orgs/{id}/users root Create an org's first user
POST /orgs root Create an org → {id, name}
GET /orgs root List orgs (event_url, shopify_secret_set — never the secret itself)
GET /orgs/{id} manage One org's settings + plan, job_quota and jobs_this_month
PUT /orgs/{id} manage Set/clear event_url, shopify_secret; job_quota and plan are root-only
DELETE /orgs/{id} root Remove an org and everything in it (never the default org)
GET /plans any The billing plan catalogue + the caller's current plan
POST /billing/webhook HMAC The payment provider's callback: this org is on that plan now
POST /apikeys manage Issue a client key → {id, label, org_id, key} (key shown once)
GET /support-access manage The support access grants of the caller's org (root: ?org=)
GET /apikeys manage List keys with their org (never the secret)
DELETE /apikeys/{id} manage Revoke a key
POST /agent/register agent Declare name + printers → {computer_id, printer_ids}
GET /agent/jobs agent Long-poll for a job (204 on timeout)
GET /agent/jobs/{id}/payload agent Download the job's bytes
POST /agent/jobs/{id}/result agent Report {ok, error?}
POST|GET|DELETE /cloudprnt/{key} client key Star CloudPRNT: the printer polls, downloads and confirms here itself

Request bodies are capped at 32 MB.

An Authorization: Basic header instead of Bearer switches the same server to the PrintNode-compatible shapes (/whoami, /printjobs, and PrintNode's JSON for /printers and /computers), so an existing client can be pointed here unchanged. Same keys, same orgs; everything below describes the Bearer API.

Submitting a job

curl -s -X POST localhost:3460/jobs \
     -H 'Authorization: Bearer <client-key>' -H 'Content-Type: application/json' \
     -d '{"printer_id":1,"type":"raw_base64","content":"<base64 ZPL>","title":"Label #4712","copies":2}'
# -> {"job_id": 1}

title is optional and shows up in the dashboard's history.

copies is optional (default 1, integer 1–100) — the agent prints the job that many times. Out of range or non-integer → 400.

callback_url is optional (http(s) only) — the server POSTs the job's outcome there once it reaches a terminal state. See Webhooks. A non-http(s) scheme → 400.

idempotency_key is optional (string, ≤128 chars) — retry-safe submits. Resubmitting the same key inside the same org returns the original job_id and prints nothing extra, so a timed-out or retried POST /jobs (order webhook redelivery, flaky network) can never double-print. Keys are scoped per org. A key is honoured as long as its job row exists: with retention on, at least max(N, 7) days after the job finished (longer than a webhook redelivery window), without retention for ever. Use something stable like the order id.

expire_after is optional (integer seconds, 1–2592000) — a deadline for the job. Past it the job is failed (state: failed, error: "expired") instead of printed, so a stale shipping label doesn't come out hours later when an offline agent reconnects. Without it, jobs wait until an agent takes them, or, with retention set, N days: then the job is failed with error: "retention" and its callback_url still gets the outcome. A job with expire_after waits for its own deadline instead.

options is optional and pdf jobs only (raw ZPL/ESC-POS carries its own layout — 400 on a raw job). The agent maps them onto its backend's native flags (SumatraPDF -print-settings on Windows, lp -o on CUPS):

{"printer_id": 2, "type": "pdf_base64", "content": "<base64 PDF>",
 "options": {"duplex": "long-edge", "paper": "A4", "bin": "Tray 1",
             "color": false, "pages": "1-3,5"}}
Key Values Maps to (Windows / CUPS)
duplex long-edge | short-edge | one-sided duplexlong… / sides=two-sided-long-edge…
paper paper name, e.g. A4, Letter paper= / media=
bin tray name (driver-specific) bin= / InputSlot=
color true | false color/monochrome / print-color-mode=
pages ranges like 1-3,5 print settings / page-ranges=
orientation auto | portrait | landscape portrait/landscape, nothing for auto / no effect

Unknown keys or invalid values → 400. Values are what the printer driver understands — check the printer's capabilities in GET /printers (papers, bins, duplex, color; reported best-effort by the agent at registration via the Windows driver or CUPS lpoptions, null when unavailable) for what it supports. An option the driver doesn't support is silently ignored by it. On CUPS, bin/paper values must not contain spaces.

orientation is for labels that come out turned on Windows. With auto, the default, SumatraPDF turns a page wider than it is tall whenever the driver reports portrait. That is right on a tall sheet. A label driver can report portrait for a wide label too, and then the label comes out sideways and small: send landscape for such a label, or portrait for a tall one. The option has two costs. A wide page on a sheet that really is tall prints at about half the size, and SumatraPDF no longer matches the paper to the page, so the driver's paper has to be right. CUPS reads the real paper size and turns a page only when it does not fit, so the option has no effect there. It needs agent 3.2.0; older agents ignore it. Measured with SumatraPDF 3.4.6, 3.5.2 and 3.6.1.

Content types

type Payload The server…
raw_base64 content: base64 bytes (ZPL/ESC-POS) decodes and queues them
pdf_base64 content: base64 PDF decodes and queues; agent renders
raw_uri url GETs the URL, queues the response bytes
pdf_uri url GETs the URL, queues as PDF
raw_uri_post url + json POSTs json to the URL, queues the response bytes
pdf_uri_post url + json POSTs json to the URL, queues as PDF
label_uri url + template GETs an image, renders it through the label template
label_base64 content + template decodes a base64 image, renders it through the template
label_text text + template renders the text through the template

URL fetches are http(s)-only and sent with a browser User-Agent (WAF/CDN-fronted services reject a default library one such as Python's).

For the types that fetch (raw_uri, pdf_uri, raw_uri_post, pdf_uri_post, label_uri) the server checks the printer, an existing idempotency_key and the quota before it fetches the URL, so a wrong printer (400) or a spent quota (402) never causes an outbound request, and a resubmitted key returns the original job without fetching again. A request whose new idempotency_key is still being fetched by another request answers 409 (a request with this idempotency_key is still in progress, retry shortly); retry it and it returns the job. With open signup each org may also have at most 4 downloads in flight at once, a fifth answers 503 (too many downloads in flight for this org, try again later); PRINTAPI_FETCHES_PER_ORG changes the number, 0 removes the cap (the default without open signup, see server.md).

The label_* types are the odd ones out: the server does not queue the bytes it received but a rendered label, a PDF for a |pdf printer and ZPL for any other. The job's mode follows the printer, so options are accepted on a PDF printer and refused on a ZPL one. The template is named by template (its name or its integer id). Templates, errors and examples: labels.md.

Webhooks

Set callback_url on a job and the server POSTs this JSON once the job reaches a terminal state:

{"job_id": 1, "state": "done", "error": null, "title": "Label #4712", "printer_id": 3}
  • Fires on done, failed, and cancelled (state-based, so agent-reported, cancelled, and reaper-failed jobs all deliver).
  • Best-effort with retries: any non-2xx or connection error is retried a few times by a background dispatcher, then given up (logged). Delivery is not guaranteed — if it matters, treat GET /jobs/{id} as the source of truth.
  • At-least-once: a delivery can arrive more than once (e.g. the POST succeeded but its ack was lost, so it retries). Make your handler idempotent — dedupe on job_id + state.
  • The payload is unsigned and the URL is fetched server-side (http(s) only) — same trust model as the *_uri content types. Point it at a trusted endpoint.

Computers (agents)

curl -s localhost:3460/computers -H 'Authorization: Bearer <client-key>'
# -> {"computers":[{"id":1,"name":"warehouse-pc","online":true,"last_seen_at":1753.., 
#                  "created_at":1750..,"printers":2}]}

online means the agent polled or registered within the liveness window (60 s). Scoped to the key's org, like every other client list.

Agent liveness events

An org can receive a POST whenever one of its agents crosses that window — the fleet-monitoring counterpart to per-job callback_url webhooks:

curl -s -X PUT localhost:3460/orgs/2 -H 'Authorization: Bearer <PRINTAPI_TOKEN>' \
     -d '{"event_url":"https://ops.example/printpapi-events"}'    # null clears it
{"event":"computer_offline","computer_id":1,"name":"warehouse-pc","org_id":2,"last_seen_at":1753..}
  • computer_offline fires once when the agent stops being seen, computer_online once when it comes back. One POST per edge, never a repeat while the state holds.
  • At-most-once, unlike job webhooks: a failed POST is logged and dropped, not retried — the next real transition fires again. Treat GET /computers as the source of truth.
  • http(s) only, unsigned, same trust model as callback_url.
  • An org that sets its event_url later starts from the current state; past transitions are not replayed.

Multi-tenancy

Every agent, printer, job, and key belongs to exactly one org. A key is the org: whatever key a request presents decides what it can see, and nothing else does.

# 1. root creates the org
curl -s -X POST localhost:3460/orgs -H 'Authorization: Bearer <PRINTAPI_TOKEN>' \
     -d '{"name":"acme"}'                       # -> {"id":2,"name":"acme"}

# 2. root issues that org a key (one per agent / per integration)
curl -s -X POST localhost:3460/apikeys -H 'Authorization: Bearer <PRINTAPI_TOKEN>' \
     -d '{"label":"acme-agent","org_id":2}'     # -> {"id":1,"label":"acme-agent","org_id":2,"key":"…"}

# 3. the agent puts that key in agent.ini and registers — it lands in org 2, and so do its
#    printers and every job printed on them.

Rules:

  • An org key never reaches another org. GET /jobs, GET /printers and GET /metrics return only that org's rows; a foreign job id is 404, not 403 (a 403 would confirm it exists); DELETE /jobs/{id} on a foreign job is 404 too, even if that job is claimed (which would otherwise be 409). Printing to a foreign printer_id is 400 unknown printer — the same answer a nonexistent printer gets.
  • Root spans orgs. The bootstrap PRINTAPI_TOKEN reads, submits and cancels across every org (that's what the dashboard uses), and is the only credential that can manage orgs and keys.
  • Agents inherit their key's org. A key issued for org N puts the agent in org N; the root token enrolls into the default org 1. Any other key is 401 since v3 — except one an agent already holds (machines enrolled under v2 keep working), and except with PRINTAPI_OPEN_ENROLLMENT=1, which restores the v2 rule (any key enrolls into org 1). Agent names are unique per org, not globally; an agent key is still bound to its name on first contact. Revoking an issued key also stops the agent that enrolled with it.
  • org_id is optional on POST /apikeys and defaults to 1. An unknown org → 400.

Existing installs need no migration — everything already lives in org 1, root behaves as before, and every issued key resolves to org 1.

Deliberately out of scope for now (# ponytail: in the code): billing, quotas, and org deletion. An agent key doubles as its org's client key; issue one per machine to keep a lost machine's blast radius to that machine.

Accounts and login

An org's people sign in with an e-mail and password instead of pasting the root token. The login mints a session token carried in the same Authorization: Bearer header as everything else, so nothing else about the API changes.

# 1. root seeds the org's first user (or the org signs itself up — see Self-signup below)
curl -s -X POST localhost:3460/orgs/2/users -H 'Authorization: Bearer <PRINTAPI_TOKEN>' \
     -d '{"email":"ops@acme.example","password":"a long passphrase"}'

# 2. that user logs in and gets a session
curl -s -X POST localhost:3460/login \
     -d '{"email":"ops@acme.example","password":"a long passphrase"}'
# -> {"token":"sess_…","expires_at":1787…,"org_id":2,"user_id":2}

# 3. the session acts inside org 2 — and may manage it
curl -s -X POST localhost:3460/apikeys -H 'Authorization: Bearer sess_…' -d '{"label":"n8n"}'
curl -s -X POST localhost:3460/users   -H 'Authorization: Bearer sess_…' \
     -d '{"email":"packer@acme.example","password":"another passphrase"}'

What holds:

  • Three kinds of credential, one header. Root manages every org; a session manages its own org; a machine key prints and reads and nothing more (401 on /apikeys, /users, PUT /orgs/{id}). Which table the credential resolves in is the permission — there is no role column and no roles.
  • Sessions expire after 30 days and can be ended early (POST /logout, or the reaper once expired). Tokens are stored sha256-hashed, like every other credential here.
  • Passwords are scrypt hashes (stdlib, salted per user), minimum 8 characters. Changing a password deletes that user's sessions — a stolen session dies with the password it came from.
  • Login is throttled per e-mail (10 failures / 15 minutes → 429), and a wrong address costs the same time as a wrong password, so the endpoint does not enumerate accounts.
  • E-mails are unique across the whole server (login carries no org), lower-cased and trimmed.
  • Removing an account (DELETE /users/{id}) drops its sessions and any pending reset with it. You cannot remove yourself (400), an org cannot lose its last account (400), and another org's user is a 404. Their jobs stay in the history; their API keys are untouched — revoke those separately.

Not built yet: per-user roles. The throttle counters are per process, in memory and bounded (several server processes count separately, and a large enough spray of invented addresses evicts counters instead of growing memory). Passwords over 1024 characters are rejected rather than hashed.

Self-signup

POST /signup {email, password, org_name?, accept_terms?} creates an org, its first account and a session in one call — the same body a login answers with. It is off unless the operator turns it on (PRINTAPI_SIGNUP=open); otherwise it is a 403, because a self-hosted box on the open internet must not hand an org to whoever finds it. GET /health reports "signup": "open"|"closed" so the dashboard only offers the door when it exists.

Signups are throttled by client address (the same limit as failed logins, but its own counter: a failed login never uses up a signup slot), so one host cannot spray orgs. A password that is too short or too long is a 400 before a slot is taken. IPv6 clients count per /64. Behind a reverse proxy every signup shares the proxy's address unless PRINTAPI_TRUSTED_PROXIES names the proxy, which makes printpapi read the client from X-Forwarded-For (see Behind a reverse proxy). org_name defaults to the e-mail's domain. A taken address is a 409 and leaves no half-made org behind. With PRINTAPI_SIGNUP_QUOTA set, the new org starts with that monthly job quota; without it, it is unlimited.

Consent. With PRINTAPI_TERMS_VERSION set, GET /health adds "terms": {"version", "terms_url", "dpa_url", "privacy_url"} (the last two may be null; the key is absent when consent is not required) and POST /signup needs "accept_terms": "<that version>": missing, false or not a string is a 400 (accept_terms required), another version is a 409 (terms changed, reload: the form was loaded before the terms changed). Both are checked before the throttle slot is spent. The version and the time are stored with the new org and user. The dashboard's form then shows one checkbox ("I act as a business and accept the Terms", plus "and the Data Processing Agreement" when PRINTAPI_DPA_URL is set) that must be ticked.

Password reset

curl -s -X POST localhost:3460/password/reset -d '{"email":"ops@acme.example"}'
# -> {"ok": true}   (the same answer for an address with no account)

curl -s -X POST localhost:3460/password/reset/confirm \
     -d '{"token":"sess_…","password":"a new long passphrase"}'
  • The token is one-shot, valid for an hour, stored hashed, and a second request supersedes the first. Spending it sets the password and logs every browser out.
  • Requests are throttled per address, counted whether or not the account exists — a 429 leaks nothing either.
  • Mail goes out over SMTP (SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASSWORD, SMTP_FROM, SMTP_SSL, SMTP_STARTTLS). With no SMTP_HOST the message is printed to stderr instead, so a self-hosted instance still works — the operator reads the token out of the log.
  • The mail carries a link only if PUBLIC_URL is set (https://…/?reset=<token>). Without it it carries the bare token, because building the link from the Host header would let anyone who can reach this server mail a valid token pointing at a host of their choosing.
  • GET /health reports "password_reset": true once SMTP is configured; the dashboard offers "Forgot password?" only then.

Quotas

An org can be capped at a number of jobs per calendar month (UTC):

curl -s -X PUT localhost:3460/orgs/2 -H 'Authorization: Bearer <PRINTAPI_TOKEN>' \
     -d '{"job_quota": 500}'      # null clears it — unlimited is the default
  • Root sets it, nobody else — a session that could raise its own cap has no cap, so job_quota on PUT /orgs/{id} is a 403 for anything but the bootstrap token. Every other field on that endpoint stays manageable by the org itself.
  • A submit past the cap answers 402 and prints nothing. The guard sits in the enqueue path, so POST /jobs, POST /orders, the Shopify webhook and the PrintNode-compatible POST /printjobs ({"code": "QuotaExceeded"}) are all covered by it.
  • An org the operator has locked answers 403 org locked on all of those submit paths, whatever its quota.
  • An idempotent resubmit spends nothing — it returns the original job, it does not create one.
  • Orgs created through self-signup start with the operator's PRINTAPI_SIGNUP_QUOTA (none if unset); orgs root creates start unlimited.
  • GET /orgs/{id} reports job_quota and jobs_this_month, which is what the dashboard's Settings page shows.

Support access

GET /support-access is what the dashboard's "Support access" card reads: the times the operator of a hosted deployment was granted access to the caller's org, newest first and for the org's current generation only. Every grant that was used is listed; of the unused ones, the 50 newest.

{ "enabled": true,
  "grants": [ { "id": 7, "reason": "ticket 4711", "granted_at": 1.7e9, "expires_at": 1.7e9,
                "ended_at": null, "active": true,
                "listed_job_ids": [12, 13], "opened_job_ids": [12] } ] }

A browser session sees its own org (?org= of another org: 403); root passes ?org= and otherwise reads the default org (404 for an unknown one); an API key is 401. enabled is false, with no grants, while the server has no operator token: nothing can be granted then. The job ids come from the audit log, deduplicated and ascending. The answer is no-store.

Plans and billing

A hosted deployment sells those quotas as plans: PRINTAPI_PLANS is the catalogue, a plan's jobs becomes the org's job_quota, and a signed POST /billing/webhook from the payment provider (via a small adapter) moves an org onto one. GET /plans lists the catalogue with each checkout link already carrying the caller's org id. Root can also set plan on PUT /orgs/{id} by hand, and DELETE /orgs/{id} removes a tenant that leaves. Unconfigured ⇒ off, which is the self-hosted default. Full contract: billing.md.

Metrics

GET /metrics returns Prometheus text (text/plain; version=0.0.4) — printpapi_jobs{state=…} (all five states, including zeros), printpapi_agents_online, printpapi_agents_total, printpapi_printers_total. The numbers cover the presented key's org (all orgs for the bootstrap token). It needs client auth, so point your scraper at it with a bearer token:

scrape_configs:
  - job_name: printpapi
    authorization: { credentials: <client-key> }
    static_configs: [{ targets: ["yourserver:3460"] }]

Job lifecycle

queued → agent claims it (claimed) → agent reports → done or failed. If an agent claims a job and never reports (crash, network), the visibility-timeout reaper requeues it — after a bounded number of retries the job is marked failed.

A job with expire_after whose deadline passes is never handed to an agent (the claim query skips it) and is failed with error: "expired" by the same reaper — a terminal state, so its webhook fires like any other outcome.

DELETE /jobs/{id} moves a job from queued to cancelled (a terminal state the agent never claims). The cancel is state-guarded: once an agent has claimed the job it returns 409 — there is no mid-print interrupt.