Zum Inhalt springen
PenBlitz
← Entwickler

API-Referenz

Jeder Aufruf der REST-API, erzeugt aus ihrer OpenAPI-Beschreibung. Die Beschreibungen der einzelnen Aufrufe sind auf Englisch.

Grundlagen

  • Basisadresse: http://127.0.0.1:8787 (Port und Erreichbarkeit werden im Tab „API“ eingestellt).
  • Gesendet und empfangen wird JSON. Ist ein Schlüssel eingerichtet, wird er als X-API-Key oder als Authorization: Bearer mitgesendet.
  • Die interaktive Fassung dieser Seite ist die Swagger-Seite deiner eigenen Installation unter /docs.
OpenAPI-Beschreibung herunterladen openapi.json

orders

Simple order facade for shop/CRM integrations

POST/api/v1/orders

Create an order: one handwritten piece for one recipient.

Request body: NewOrder (10)
callback_url string
– Receives a `POST` when the order is printed, failed or cancelled.
external_id string
– Your own order number. Sending the same `external_id` again returns the existing order instead of printing twice.
product string
– `postcard`, `letter` or `card` (see `GET /products`).
qr_data string
– Add an individual QR code below the text (placeholders allowed).
recipient Recipient
scheduled_at string
template_id string
– Use this template instead of the product's default.
text string
– The finished text. May still contain placeholders that are filled from `variables`.
variables BTreeMap
– Extra placeholder values (e.g. `sender`, `code`).
with_envelope boolean
– Also write a DL envelope with the recipient's address.

→ 200 Order

GET/api/v1/orders/{id}

Order status. `id` may be the order id or your `external_id`.

id path
Order id or external_id

→ 200 Order

DELETE/api/v1/orders/{id}

Cancel an order that has not been written yet.

id path
Order id or external_id

→ 200 Order

GET/api/v1/products

Products that can be ordered.

→ 200 Product[]

jobs

Print jobs and mail merge

GET/api/v1/jobs

List jobs, oldest first.

state query
Filter: `open` (not finished), `finished`, or a state such as `printing`.
external_id query
Filter by the caller's reference.

→ 200 JobSummary[]

POST/api/v1/jobs

Create a job. One sheet per record (times `copies`); placeholders in text and QR codes are filled per record. The job is queued immediately unless `scheduled_at` lies in the future.

Request body: JobRequest (17)
additional_documents Document[]
– Further documents printed after the main one for every record (e.g. the matching envelope).
additional_template_ids string[]
– Stored templates appended to `additional_documents`.
callback_url string
confirm_each_page boolean
copies integer
– Copies per record.
document Document
external_id string
hold boolean
– Do not print until a person approves the job in the app (used for jobs from AI assistants).
meta object
name string
– Display name. Defaults to the document name.
records BTreeMap[]
– Mail-merge data: one sheet per record. Empty = a single sheet.
scheduled_at string
– Do not start before this time.
seed integer
– Fixed seed for reproducible handwriting. Random if omitted.
strict boolean
– Reject the job if a placeholder has no value in some record.
strict_layout boolean
– Reject the job if a sheet draws outside the page margins or into an area the post office needs free.
template_id string
– Use a stored template instead of an inline `document`.
csv string
– Mail-merge data as CSV text (alternative to `records`).

→ 201 Job

GET/api/v1/jobs/{id}

One job with all pages.

id path
Job id

→ 200 Job

DELETE/api/v1/jobs/{id}

Delete a job that is not printing.

id path
Job id

→ 204

POST/api/v1/jobs/{id}/cancel

Cancel a job. A printing job stops and the pen is lifted.

id path
Job id

→ 200 JobSummary

GET/api/v1/jobs/{id}/pages/{page}/preview.svg

SVG preview of one page of a job (0-based page number).

id path
Job id
page path
Page index, starting at 0

→ 200

POST/api/v1/jobs/{id}/pause

Pause a job (a printing job pauses after the current page).

id path
Job id

→ 200 JobSummary

POST/api/v1/jobs/{id}/resume

Continue a paused job, confirm the paper change, or retry a failed or cancelled job from the first unprinted page.

id path
Job id

→ 200 JobSummary

GET/api/v1/queue

Queue overview.

→ 200 QueueInfo

POST/api/v1/queue/clear-finished

Remove all finished, failed and cancelled jobs from the list.

→ 200 Done

POST/api/v1/queue/pause

Hold the whole queue: no new page starts (the current page finishes).

→ 200 QueueInfo

POST/api/v1/queue/resume

Release the queue.

→ 200 QueueInfo

templates

Stored documents with placeholders

GET/api/v1/templates

List stored templates.

→ 200 Template[]

POST/api/v1/templates

Create a template.

Request body: TemplateInput (4)
description string
document Document
id string
– Optional fixed id when creating (letters, digits, `-`, `_`).
name string

→ 201 Template

GET/api/v1/templates/{id}

One template.

id path
Template id

→ 200 Template

PUT/api/v1/templates/{id}

Replace a template (creates it if missing).

id path
Template id
Request body: TemplateInput (4)
description string
document Document
id string
– Optional fixed id when creating (letters, digits, `-`, `_`).
name string

→ 200 Template

DELETE/api/v1/templates/{id}

Delete a template.

id path
Template id

→ 204

GET/api/v1/templates/{id}/variables

Placeholders used by a template.

id path
Template id

→ 200 Variables

render

Previews without printing

POST/api/v1/data/csv

Parse CSV text (`;`, `,` or tab separated, first line = column names) into records that can be passed to `POST /jobs`.

→ 200 CsvResult

POST/api/v1/render

Render a preview without printing: SVG, warnings, statistics, optional G-code.

Request body: RenderRequest (5)
document Document
include_gcode boolean
– Include the G-code program (upload format) in the response.
record BTreeMap
– Placeholder values.
seed integer
– Seed of the handwriting variation (same seed = same result).
template_id string

→ 200 RenderResponse

POST/api/v1/render/svg

Same as `/render`, but returns the SVG image directly.

Request body: RenderRequest (5)
document Document
include_gcode boolean
– Include the G-code program (upload format) in the response.
record BTreeMap
– Placeholder values.
seed integer
– Seed of the handwriting variation (same seed = same result).
template_id string

→ 200

printer

Direct printer control

GET/api/v1/printer

Printer state (online, idle/printing/error).

→ 200 PrinterStatus

POST/api/v1/printer/eject

Lift the pen, park and eject the sheet.

→ 200 Done

POST/api/v1/printer/feed

Pull one sheet from the tray (`M998`).

→ 200 Done

POST/api/v1/printer/pen

Move the pen holder: `install` lowers it for a pen change, `up` lifts it again.

Request body: PenRequest (1)
position PenPosition
– `install` = pen change position, `up` = lifted, `down` = writing height.

→ 200 Done

GET/api/v1/printer/settings

Settings reported by the printer's WiFi module (feed rate, offsets, WiFi, ...).

→ 200 object

POST/api/v1/printer/stop

Emergency stop: cancels the printing job (if any), stops the printer and lifts the pen.

→ 200 Done

system

Health, settings, fonts

GET/api/v1/config

Current settings.

→ 200 Config

PUT/api/v1/config

Replace the settings. API bind/port changes take effect after a restart. Send `api.api_key` as `********` to keep the current key.

Request body: Config (6)
api ApiConfig
language string
– Language of the app: `auto` (system language) or a code such as `en` or `de`.
machine MachineConfig
mcp McpConfig
printer PrinterConfig
theme string
– Appearance of the app: `auto` (follow the system), `light` or `dark`.

→ 200 Config

GET/api/v1/fonts

The fonts: built-in ones and imported handwriting (`own`).

→ 200 FontInfo[]

GET/api/v1/health

Liveness check (no authentication).

→ 200 Health

GET/api/v1/page-presets

Paper format presets.

→ 200 PagePreset[]