API Reference

REST API

PrintBridge exposes a JSON REST API on http://127.0.0.1:1337. All endpoints bind to localhost only — not reachable from the network.

Authentication

All endpoints except GET /status require your API key. Pass it as a header or Bearer token:

X-PrintBridge-Api-Key: YOUR_KEY
# or
Authorization: Bearer YOUR_KEY

Copy your key from the PrintBridge desktop app. Rotate it at any time — the old key is immediately invalidated.

GET/status

Returns the service state, version, and license info. Public — no API key required. Use this to check if PrintBridge is running before sending jobs.

response

{
  "running": true,
  "port": 1337,
  "version": "1.0.0",
  "silentByDefault": true,
  "apiKeyRequired": true,
  "supportedPrintFormats": ["auto","html","pdf","png","jpeg","zpl","tspl",...],
  "originAllowlistActive": false,
  "originAllowlistCount": 0,
  "entitled": true,
  "trialDaysRemaining": 30,
  "trialActive": true,
  "trialExpired": false,
  "subscriptionExpiresAt": null,
  "deviceHealthScore": 100,
  "wsUrl": "ws://127.0.0.1:1337/ws",
  "appSigned": true
}

GET/printersAuth required

Returns all printers installed on the Windows machine, including health scores. Use the name field as printerName in print requests.

response

[
  {
    "name": "Zebra ZD620",
    "displayName": "Zebra ZD620",
    "isDefault": false,
    "status": 0,
    "description": "",
    "healthScore": 100,
    "healthLabel": "ready"   // ready | offline | error | paper-jam | paper-out | ...
  }
]

POST/printAuth required

Prints a single job. Supports all 14 formats. Returns { "success": true } or a 500 with an error string.

request body

{
  "printerName": "Zebra ZD620",   // required — exact name from GET /printers
  "content":     "^XA...^XZ",     // required — raw language, HTML, or base64
  "format":      "zpl",           // optional — auto-detected if omitted
  "encoding":    "utf8",          // "utf8" (default) or "base64"
  "copies":      1,               // optional — repeat the job N times (max 999)
  "options": {
    "silent":          true,      // skip print dialog (default: true)
    "printBackground": true       // include CSS backgrounds (rendered formats)
  }
}

Printer name matching: PrintBridge validates the name against Chromium's printer list before printing. If the name doesn't match, you get a clear 500 error listing available printers instead of a silent redirect to the default printer.

POST/print-batchAuth required

Prints multiple jobs to the same printer sequentially. Each job can have its own format, encoding, and copy count. Returns per-job results.

request body

{
  "printerName": "Zebra ZD620",
  "delayMs": 200,               // optional pause between jobs (ms)
  "jobs": [
    {
      "content": "^XA...^XZ",
      "format": "zpl",
      "encoding": "utf8",
      "copies": 2,              // optional per-job copies
      "options": { "silent": true }
    },
    {
      "content": "<html>...</html>",
      "format": "html"
    }
  ]
}

response

{
  "success": true,
  "results": [
    { "success": true },
    { "success": true },
    { "error": "Printer offline" }   // per-job errors don't abort the batch
  ]
}

POST/print/batchAuth required

Async multipart batch — upload up to hundreds of image/PDF files and print them all to one printer concurrently (up to 5 at a time). Returns immediately with a batchId; progress arrives via WebSocket events.

Content-Type: multipart/form-data. Files must be uploaded as the files field. PDFs are printed directly; images are recompressed to the target DPI before printing.

form fields

printerName  string   required — exact printer name from GET /printers
files        File[]   required — one or more PDF or image files (jpeg/png/gif/webp)
dpi          number   optional — target DPI for image recompression (default: 203)

response (immediate)

{
  "batchId":          "550e8400-e29b-41d4-a716-446655440000",
  "jobCount":         12,
  "status":           "queued",
  "estimatedSeconds": 8
}

WebSocket events (after response)

// One per file as it completes successfully:
{ "event": "job_complete", "batchId": "...", "jobIndex": 0, "jobId": "..." }

// One per file if it fails:
{ "event": "job_failed",   "batchId": "...", "jobIndex": 1, "error": "Printer offline" }

// After all files finish:
{ "event": "batch_complete", "batchId": "...", "succeeded": 11, "failed": 1 }

GET/settingsAuth required

Returns the current settings.

response

{ "silentByDefault": true }

POST/settingsAuth required

Updates settings.

request body

{ "silentByDefault": false }

GET/originsAuth required

Returns the trusted origin allowlist. When the list is non-empty, browser requests with a non-matching Origin header are rejected with 403.

response

{ "origins": ["https://app.example.com"] }

POST/originsAuth required

Adds a trusted origin. Only https:// origins are permitted (plus http://localhost for dev).

request body

{ "origin": "https://app.example.com" }

POST/origins/removeAuth required

Removes an origin from the allowlist.

request body

{ "origin": "https://app.example.com" }

GET/logsAuth required

Returns the last 200 print job log entries, most recent first. Useful for audit trails and debugging. Log entries contain operational metadata only — no document content.

response

{
  "logs": [
    {
      "timestamp": "2026-04-05T14:32:01.000Z",
      "printerName": "Zebra ZD620",
      "format": "zpl",
      "success": true,
      "durationMs": 142,
      "copies": 1
    }
  ],
  "total": 47
}

WSws://127.0.0.1:1337/wsAuth required

Real-time WebSocket stream of print job events. Authenticate by sending your API key as the first message within 5 seconds of connecting.

authentication message

{ "apiKey": "YOUR_KEY" }

events received

// On auth success:
{ "type": "connected", "port": 1337 }

// After every POST /print or /print-batch job:
{
  "type":        "print_job",
  "timestamp":   "2026-04-05T14:32:01.000Z",
  "printerName": "Zebra ZD620",
  "format":      "zpl",
  "success":     true,
  "durationMs":  142
}

// ── POST /print/batch events ──────────────────────────────────────

// A file in the batch succeeded:
{ "event": "job_complete",   "batchId": "550e8400-...", "jobIndex": 0, "jobId": "..." }

// A file in the batch failed:
{ "event": "job_failed",     "batchId": "550e8400-...", "jobIndex": 1, "error": "Printer offline" }

// All files in the batch have been processed:
{ "event": "batch_complete", "batchId": "550e8400-...", "succeeded": 11, "failed": 1 }

Error responses

401Missing or invalid API key.402Trial expired or subscription required. Open PrintBridge to subscribe.403Origin not in allowlist. Add it via the PrintBridge UI or POST /origins.400Missing required field or invalid format/encoding value.500Print failed — includes an error string. Common: printer not found, offline, or spooler error.