Skip to content
PenBlitz
← Developers

API: getting started

Switch the API on, make the first call and render a preview, in five minutes.

Switch it on

  1. Open the “API” tab in PenBlitz and tick “Start the API server together with the app”.
  2. The API then listens on http://127.0.0.1:8787, reachable from this computer only.
  3. Open http://127.0.0.1:8787/docs for the Swagger page, where every call can be tried in the browser.

Without the app, the same API runs as a background program: penblitz-server serve. Add --mock to try it without a printer.

First call

The health check needs no key and tells you the API is up:

curl http://127.0.0.1:8787/api/v1/health

{"status":"ok","version":"0.2.0","open_jobs":0,"queue_paused":false}

Render a preview

Nothing is printed. You get the sheet as SVG, warnings and how long it would take:

curl -X POST http://127.0.0.1:8787/api/v1/render \
  -H 'Content-Type: application/json' \
  -d '{"template_id": "letter", "record": {"text": "Dear Anna,\nthank you for your order!"}}'

Print it

The same content as a job. One record is one sheet:

curl -X POST http://127.0.0.1:8787/api/v1/jobs \
  -H 'Content-Type: application/json' \
  -d '{"template_id": "letter", "records": [{"text": "Dear Anna,\nthank you for your order!"}]}'

Protect it with a key

Generate a key in the “API” tab. Every call except the health check must then send it:

curl http://127.0.0.1:8787/api/v1/jobs -H 'X-API-Key: YOUR_KEY'
# or
curl http://127.0.0.1:8787/api/v1/jobs -H 'Authorization: Bearer YOUR_KEY'

Opening the API to the network (0.0.0.0) without a key lets any device in the network start print jobs. Set a key first.

Errors

Failed calls answer with a fitting HTTP status and a message. The text follows the language chosen in the app; the status code and the machine-readable states never change.

HTTP/1.1 400 Bad Request

{"error": "Template 'lettr' not found"}