Docs

Runtime API

The local HTTP + WebSocket surface the SDK talks to — same host/port you pass to new Portix() (default 127.0.0.1:17321). Most developers never call this directly; it's here for when you do. Source: runtime/src/api/.

Authentication

Send the API key in the x-portix-api-key header. The runtime's admin key (PORTIX_LOCAL_API_KEY, defaults to dev-local-key) sees every job on the runtime; a token from a completed pairing only sees its own tenant/app's jobs.

HTTP endpoints

Method	Path	Auth	Description
GET	/health	None	Liveness + version. { status, version, defaultPrinter? }.
GET	/ping	None	Cheaper liveness check. { pong: true }.
POST	/print	API key	Enqueues a print job. Body: { content, printerName?, copies? }.
GET	/printers	API key	Every printer the runtime can see.
GET	/printers/:name	API key	One printer by name. 404 if not found.
GET	/jobs	API key	Jobs visible to this caller — all of them for the admin key, only the caller's own once paired.
POST	/jobs/:id/cancel	API key	Cancels a job that hasn't started printing.
POST	/pairing/request	None	Body: { tenant, appId }. Returns { code, expiresAt }. Auto-approved with no human involved if the Origin is localhost or a private-network address.
GET	/pairing/status?code=...	None	Poll target for pair() — { status, token?, deviceId?, permissions? }.
POST	/pairing/approve	Admin key	Approves a pending pairing code — normally driven by a human, not the SDK.
GET	/pairings	Admin key	Every approved pairing, with lastUsedAt and recentJobCount per app.
DELETE	/pairings/:deviceId	Admin key	Revokes an app's access immediately — its token stops working on the next request.
GET	/pairing/pending	Admin key	Pairing codes awaiting approval.
GET	/metrics	Admin key	RuntimeMetrics — see below.

WebSocket events

Same host/port, upgraded to a WebSocket connection. Every message is { event, data }. Sent on connect: a status event. Broadcast as jobs move through the queue:

statusjob:queuedjob:printingjob:printedjob:errorjob:cancelled

The SDK's portix.on(event, handler) subscribes to these for you — see the SDK reference.

GET /metrics response shape

{
  uptimeMs: number,
  jobs: {
    total: number,
    byStatus: { pending, printing, completed, failed, cancelled },
    avgDurationMs?: number,   // queued -> completed, completed jobs only
    lastDurationMs?: number,
  },
  pairing: {
    totalApproved: number,
    avgPairingDurationMs?: number,  // request -> human approval
  },
  websocket: {
    activeConnections: number,
    totalDisconnects: number,  // disconnects, not reconnections (see FAQ)
  },
}

Every error response is { error: CODE, message } — see the FAQ for what each error code means.