API reference¶

The REST API of the print server (tavletta serve), for programs that print labels: every request with its role, fields, answers and error codes. A walkthrough for an inventory tool, with code in Python and C#, is Connecting an inventory tool; installing the server is Server installation.

This page is made from the OpenAPI 3.1 description of the server (tools/openapi_docs.py). Programs and code generators read the same description: docs/openapi.yaml in the source, or GET /api/v1/openapi.json from a running server.

Basics¶

• Address: http://<server>:8790/api/v1, or the HTTPS address of the reverse proxy. The examples use $TAVLETTA for it and $TOKEN for the access token:

TAVLETTA=https://labels.example.com/api/v1
TOKEN=tav_0123456789ab_...

• JSON in and out (UTF-8). Requests with a body need Content-Type: application/json and a Content-Length.
• Every request but GET /api/v1/health needs the header Authorization: Bearer <token>.
• Messages come in the language of Accept-Language (e.g. de-CH), English by default. Codes never change with the language: programs check the code, people read the message.
• Unknown fields are refused (unknown_field): a typo never prints something else than meant.

Roles¶

Each access token has a role (tokens.toml, made with tavletta token new). A role may do what the roles above it may.

A token can be limited to some printers of printers.toml: the others are then "not found" (404 printer_not_found) for it.

Errors¶

Every error is JSON with a stable code and a message for people:

{"error": {"code": "label_not_found", "message": "No such label: asset-tag.tavletta"}}

printer_<code>: the printer's problem, one of generic, not_found, timeout, stalled, port_closed, busy, paused, cover_open, head_open, jam, media_jam, out_of_labels, out_of_paper, label_not_found, wrong_media, paper_size, page_too_large, too_long, too_wide, code_too_large, ribbon, ribbon_out, ribbon_direct, no_cassette, bad_cassette, supplies, format, resolution, queue_paused, job_held, job_canceled, usb_not_found, usb_permission, serial_permission, battery, overheat, unsupported_model, unknown_model, editor_lite.

A job that fails tells why in its error, with these codes:

Limits¶

Requests¶

Besides the answers listed with each request, every request can get the general errors of the table above: 401, 403, 405, 408, 421, 429 (too_many_requests), 500 and 503, and one with a body 411, 413 (too_large) and 415.

GET /api/v1/health¶

Is the server running; no token needed (for health checks).

• Role: none (no token)

curl "$TAVLETTA/health"

GET /api/v1/openapi.json¶

This description (OpenAPI 3.1); a token of any role.

• Role: preview

curl -H "Authorization: Bearer $TOKEN" \
     "$TAVLETTA/openapi.json"

GET /api/v1/printers¶

The printers of printers.toml the token may use, with their state; without it the printer models, the address set for each and the printers found (--discover).

• Role: preview

curl -H "Authorization: Bearer $TOKEN" \
     "$TAVLETTA/printers"

GET /api/v1/printers/{id}/status¶

Ask a printer for its state: media, problems, resolution.

• Role: preview

curl -H "Authorization: Bearer $TOKEN" \
     "$TAVLETTA/printers/it-cab/status"

GET /api/v1/labels¶

The label files in the labels folder and its subfolders.

• Role: preview

curl -H "Authorization: Bearer $TOKEN" \
     "$TAVLETTA/labels"

GET /api/v1/labels/{name}¶

What a label can be filled in with: elements, variables, data columns, size, counter.

• Role: preview

curl -H "Authorization: Bearer $TOKEN" \
     "$TAVLETTA/labels/asset-tag"

POST /api/v1/preview¶

The label filled in, as an image; nothing is printed.

• Role: preview

Body fields:

curl -H "Authorization: Bearer $TOKEN" \
     -H 'Content-Type: application/json' \
     -d '{"label": "asset-tag", "printer": "it-cab", "data_rows": [{"AssetNumber": "100001"}], "format": "png"}' \
     -o preview.png \
     "$TAVLETTA/preview"

POST /api/v1/print¶

Print: the request is checked, then queued; each printer prints one job at a time.

• Role: print

Body fields:

curl -H "Authorization: Bearer $TOKEN" \
     -H 'Content-Type: application/json' \
     -d '{"label": "asset-tag", "printer": "it-cab", "data_rows": [{"AssetNumber": "100001"}], "wait": 30}' \
     "$TAVLETTA/print"

GET /api/v1/jobs/{id}¶

State of a print job (a print token: its own jobs; admin: all). Kept 24 hours after it finished.

• Role: print

curl -H "Authorization: Bearer $TOKEN" \
     "$TAVLETTA/jobs/$JOB"

DELETE /api/v1/jobs/{id}¶

Cancel a job: at once while it waits, after the current label while it prints.

• Role: print

curl -H "Authorization: Bearer $TOKEN" \
     -X DELETE \
     "$TAVLETTA/jobs/$JOB"

Answers¶

Job¶

Label¶

NamedPrinter¶

A printer of printers.toml.

PrinterStatus¶

Preview¶

Example of a job:

{
  "id": "HxIwYqXuV4qYRBM7",
  "state": "done",
  "printer": "cab",
  "printer_name": "it-cab",
  "host": "cab-it.example.com",
  "owner": "inventory-tool",
  "label": "asset-tag.tavletta",
  "printed": 20,
  "total": 20,
  "rows_printed": 20,
  "cancel_requested": false,
  "error": null,
  "remark": null,
  "warnings": [],
  "created": "2026-11-12T15:34:45+00:00",
  "started": "2026-11-12T15:34:45+00:00",
  "finished": "2026-11-12T15:35:04+00:00"
}