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.
orders
Simple order facade for shop/CRM integrations
/api/v1/ordersCreate an order: one handwritten piece for one recipient.
Request body: NewOrder (10)
callback_urlstring- – Receives a `POST` when the order is printed, failed or cancelled.
external_idstring- – Your own order number. Sending the same `external_id` again returns the existing order instead of printing twice.
productstring- – `postcard`, `letter` or `card` (see `GET /products`).
qr_datastring- – Add an individual QR code below the text (placeholders allowed).
recipientRecipientscheduled_atstringtemplate_idstring- – Use this template instead of the product's default.
textstring- – The finished text. May still contain placeholders that are filled from `variables`.
variablesBTreeMap- – Extra placeholder values (e.g. `sender`, `code`).
with_envelopeboolean- – Also write a DL envelope with the recipient's address.
→ 200 Order
/api/v1/orders/{id}Order status. `id` may be the order id or your `external_id`.
idpath- Order id or external_id
→ 200 Order
/api/v1/orders/{id}Cancel an order that has not been written yet.
idpath- Order id or external_id
→ 200 Order
/api/v1/productsProducts that can be ordered.
→ 200 Product[]
jobs
Print jobs and mail merge
/api/v1/jobsList jobs, oldest first.
statequery- Filter: `open` (not finished), `finished`, or a state such as `printing`.
external_idquery- Filter by the caller's reference.
→ 200 JobSummary[]
/api/v1/jobsCreate 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_documentsDocument[]- – Further documents printed after the main one for every record (e.g. the matching envelope).
additional_template_idsstring[]- – Stored templates appended to `additional_documents`.
callback_urlstringconfirm_each_pagebooleancopiesinteger- – Copies per record.
documentDocumentexternal_idstringholdboolean- – Do not print until a person approves the job in the app (used for jobs from AI assistants).
metaobjectnamestring- – Display name. Defaults to the document name.
recordsBTreeMap[]- – Mail-merge data: one sheet per record. Empty = a single sheet.
scheduled_atstring- – Do not start before this time.
seedinteger- – Fixed seed for reproducible handwriting. Random if omitted.
strictboolean- – Reject the job if a placeholder has no value in some record.
strict_layoutboolean- – Reject the job if a sheet draws outside the page margins or into an area the post office needs free.
template_idstring- – Use a stored template instead of an inline `document`.
csvstring- – Mail-merge data as CSV text (alternative to `records`).
→ 201 Job
/api/v1/jobs/{id}One job with all pages.
idpath- Job id
→ 200 Job
/api/v1/jobs/{id}Delete a job that is not printing.
idpath- Job id
→ 204
/api/v1/jobs/{id}/cancelCancel a job. A printing job stops and the pen is lifted.
idpath- Job id
→ 200 JobSummary
/api/v1/jobs/{id}/pages/{page}/preview.svgSVG preview of one page of a job (0-based page number).
idpath- Job id
pagepath- Page index, starting at 0
→ 200
/api/v1/jobs/{id}/pausePause a job (a printing job pauses after the current page).
idpath- Job id
→ 200 JobSummary
/api/v1/jobs/{id}/resumeContinue a paused job, confirm the paper change, or retry a failed or cancelled job from the first unprinted page.
idpath- Job id
→ 200 JobSummary
/api/v1/queueQueue overview.
→ 200 QueueInfo
/api/v1/queue/clear-finishedRemove all finished, failed and cancelled jobs from the list.
→ 200 Done
/api/v1/queue/pauseHold the whole queue: no new page starts (the current page finishes).
→ 200 QueueInfo
/api/v1/queue/resumeRelease the queue.
→ 200 QueueInfo
templates
Stored documents with placeholders
/api/v1/templatesList stored templates.
→ 200 Template[]
/api/v1/templatesCreate a template.
Request body: TemplateInput (4)
descriptionstringdocumentDocumentidstring- – Optional fixed id when creating (letters, digits, `-`, `_`).
namestring
→ 201 Template
/api/v1/templates/{id}One template.
idpath- Template id
→ 200 Template
/api/v1/templates/{id}Replace a template (creates it if missing).
idpath- Template id
Request body: TemplateInput (4)
descriptionstringdocumentDocumentidstring- – Optional fixed id when creating (letters, digits, `-`, `_`).
namestring
→ 200 Template
/api/v1/templates/{id}Delete a template.
idpath- Template id
→ 204
/api/v1/templates/{id}/variablesPlaceholders used by a template.
idpath- Template id
→ 200 Variables
render
Previews without printing
/api/v1/data/csvParse CSV text (`;`, `,` or tab separated, first line = column names) into records that can be passed to `POST /jobs`.
→ 200 CsvResult
/api/v1/renderRender a preview without printing: SVG, warnings, statistics, optional G-code.
Request body: RenderRequest (5)
documentDocumentinclude_gcodeboolean- – Include the G-code program (upload format) in the response.
recordBTreeMap- – Placeholder values.
seedinteger- – Seed of the handwriting variation (same seed = same result).
template_idstring
→ 200 RenderResponse
/api/v1/render/svgSame as `/render`, but returns the SVG image directly.
Request body: RenderRequest (5)
documentDocumentinclude_gcodeboolean- – Include the G-code program (upload format) in the response.
recordBTreeMap- – Placeholder values.
seedinteger- – Seed of the handwriting variation (same seed = same result).
template_idstring
→ 200
printer
Direct printer control
/api/v1/printerPrinter state (online, idle/printing/error).
→ 200 PrinterStatus
/api/v1/printer/ejectLift the pen, park and eject the sheet.
→ 200 Done
/api/v1/printer/feedPull one sheet from the tray (`M998`).
→ 200 Done
/api/v1/printer/penMove the pen holder: `install` lowers it for a pen change, `up` lifts it again.
Request body: PenRequest (1)
positionPenPosition- – `install` = pen change position, `up` = lifted, `down` = writing height.
→ 200 Done
/api/v1/printer/settingsSettings reported by the printer's WiFi module (feed rate, offsets, WiFi, ...).
→ 200 object
/api/v1/printer/stopEmergency stop: cancels the printing job (if any), stops the printer and lifts the pen.
→ 200 Done
system
Health, settings, fonts
/api/v1/configCurrent settings.
→ 200 Config
/api/v1/configReplace 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)
apiApiConfiglanguagestring- – Language of the app: `auto` (system language) or a code such as `en` or `de`.
machineMachineConfigmcpMcpConfigprinterPrinterConfigthemestring- – Appearance of the app: `auto` (follow the system), `light` or `dark`.
→ 200 Config
/api/v1/fontsThe fonts: built-in ones and imported handwriting (`own`).
→ 200 FontInfo[]
/api/v1/healthLiveness check (no authentication).
→ 200 Health
/api/v1/page-presetsPaper format presets.
→ 200 PagePreset[]