API: getting started
Switch the API on, make the first call and render a preview, in five minutes.
Switch it on
- Open the “API” tab in PenBlitz and tick “Start the API server together with the app”.
- The API then listens on http://127.0.0.1:8787, reachable from this computer only.
- 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"}