Connect your application to label printing.

Use the contract for your build

This guide reflects the implementation reviewed on 26 September 2026. Check GET /api/v1/version and the supplied build version before integrating. Examples below illustrate requests and response shapes; they are not execution records.

The source contract is split into domain files under api/openapi/, including print.json, runners.json and jobs.json. Shared definitions are bundled by api/buendel.go. With the matching source, make openapi generates the local bundle for tooling. Connected MCP clients can read the bundled contract through the ole://openapi resource.

Use that contract for complete bodies, response schemas and permissions. This page explains integration choices and selected examples.

Authenticate the integration

Have an administrator create a service-account token with the permissions needed by the integration. Send it as Authorization: Bearer SERVICE_TOKEN over your configured HTTPS address. Keep the token in your integration's secret store.

Browser login uses a session cookie and CSRF protection. It is not the token-issuing endpoint. Service tokens are managed through /api/v1/auth/tokens; their creation and revocation require administrator rights. Runner enrollment tokens are separate, one-use credentials.

Request a direct network print

Use POST /api/v1/print when the Center can reach the network target. First create or select an available label, then substitute its reference and version. This example assumes lbl://packing-eval@1 resolves to an available label with the four shown input variables. The host is a documentation placeholder: replace it with your controlled evaluation target.

POST /api/v1/print
Authorization: Bearer SERVICE_TOKEN
Content-Type: application/json
Idempotency-Key: northline-order-1042-label-1

{
  "label_ref": "lbl://packing-eval@1",
  "variables": {
    "product": "Precision bearing 6204",
    "batch": "LOT-260926",
    "partNumber": "BRG-6204",
    "quantity": "24"
  },
  "quantity": 1,
  "target": {
    "host": "192.0.2.10",
    "port": 9100,
    "typ": "zpl-raw"
  }
}

variables contains strings. Its quantity value is the pack quantity on this example label. The top-level quantity is an integer from 1 to 999 and requests label copies; omitting it means one copy.

The Idempotency-Key belongs in the header. Reuse it for the same attempt with the same request. A changed body or an intentional additional print needs a deliberate new request identity; a conflicting reuse is rejected.

A direct request returns a synchronous outcome. For example, a complete transmission to a RAW ZPL target can return:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "jobId": "northline-order-1042-label-1",
  "state": "sent",
  "code": "flow.operator.sent_unconfirmed"
}

This jobId is the idempotency key. It can be matched to the print archive; it is not a Runner job resource ID.

Send work through an Automation Service

Use POST /api/v1/runners/{runnerId}/jobs for a specific enrolled service. This route needs infrastructure permissions. It accepts a label reference, variables, quantity and target, and returns 202 Accepted with a job object.

For network ZPL, use the same target shape as above. For a printer installed on that service's machine, the target uses its exact printer name. For example, a Windows driver target is:

{
  "typ": "os-driver",
  "printer_name": "Packing label printer"
}

This is only the target portion of the request. Use os-raw for an installed RAW queue. Do not combine a local printer name with a network host/port. Check the operating-system and driver requirements.

Save the returned job object's id and inspect GET /api/v1/jobs/{jobId} for its current state and event history. A 202 response establishes acceptance, not delivery. GET /api/v1/runners/{runnerId}/jobs and .../activity provide the service view.

POST /api/v1/jobs/{jobId}/cancel uses that same returned resource ID. Cancellation is conditional on the job state and an available service connection; inspect the response.

Treat outcomes as data

Result	Meaning for your integration
sent	Transmission or local queue handoff succeeded without device acknowledgement.
confirmed	A capable target acknowledged the request. Ordinary RAW and local queue paths do not produce that confirmation.
hold / unknown delivery	The print outcome is uncertain. Preserve the request and investigate before making a replacement decision.
failed / refused	Read the code and parameters to distinguish a failed attempt from a rejected operation.

Direct /print can return HTTP 200 with sent, confirmed, hold or failed. Validation and permission failures use HTTP error responses. Do not turn every 2xx response into a “printed” business status.

When a transport response is lost, retain the original identity and body for reconciliation. Changing the key solely to get past an uncertain result can request additional output.

Match each identifier to the right history

Identifier	Use
Direct print jobId	Matches the request key and the archive's jobId.
Runner job id	Reads or cancels the resource under /api/v1/jobs/{jobId}.
Runner job idempotencyKey	Correlates the request with the print archive's jobId.
Archive entry id	Reads a record under /api/v1/print-archive/{entryId}.

GET /api/v1/print-archive lists recorded print requests and outcomes. Inspect the associated label version, inputs and destination. GET /api/v1/audit-log serves the separate change history.

Label documents and forms

Use /api/v1/labels for labels, /labels/{labelId}/document for the current document, and /labels/{labelId}/versions for history. Document edits use the defined patch contract and stable object IDs.

GET /api/v1/labels/{labelId}/form generates print inputs. Saved forms use /api/v1/forms, and /api/v1/form-assignments controls their use. When printing through a form, include the applicable form_ref so version, label binding and form rules are checked and its reference is recorded.

Automations and runs

/api/v1/flows manages automations. Read /api/v1/flows/registry for node definitions. Form submission uses POST /api/v1/forms/{formId}/submit; configured webhook triggers use their flow and trigger IDs. Consult their contracts for authentication and acceptance behavior.

Run counts and notices explain workflow execution. Reconcile a print node's queued work with the later delivery result. See the integration recipes for database arguments and order processing.

Version distribution

/api/v1/deployments distributes an explicit automation version to a Runner group. Current deployments are pinned; saving a newer version does not update them. Printer mappings and context values have their own deployment, group and service routes. Keep desired version and reported applied state distinct.

Other integration domains

Printers

/api/v1/printers lists configured targets. Discovery and adoption require the appropriate infrastructure permissions; enumeration does not certify a device's output.

Credentials

Manage saved access through /api/v1/credentials. Documents and automation parameters use cred:// references. Keep secret values out of labels, workflow JSON and logs.

Users

/api/v1/users and role routes support account administration. Match the service account's permissions to the operations it needs.

Import

POST /api/v1/import accepts source files and supported sidecars. Read /api/v1/import/formats and preserve conversion diagnostics when adopting the result.

Counters

/api/v1/counters manages numbering definitions. Distinguish allocation from the later print outcome; see serialization.

AI assistance

Label, automation and saved-form proposal APIs use configured providers and permissions. Review the proposed changes before applying them; API availability does not establish that a model is configured in your installation.

Build an integration recipe → · Evaluate a representative workflow →