Submit a print job

POST

/api/v1/print

curl --request POST \
  --url https://example.com/api/v1/print \
  --header 'Content-Type: application/json' \
  --header 'X-Label-Hub-Key: <X-Label-Hub-Key>' \
  --data '{ "content_type": "qr_only", "data": { "items": [], "primary_id": "example", "qr_payload": "example", "secondary": [], "title": "example" }, "lookup": { "app": "example", "identifier": "example" }, "options": { "auto_cut": true, "copies": 1, "half_cut": false, "high_resolution": false, "last_page": true } }'

Submit a label-print job. The job is queued and dispatched asynchronously by the queue worker. Returns 202 with the new job’s UUID and state queued. Returns 4xx/5xx on printer errors (tape mismatch, offline, cover open, etc.).

Authorizations

• APIKeyHeader

Request Body^required

Media typeapplication/json

PrintRequest

POST /api/v1/print body.

Either data (RawLabelData) or lookup (PrintLookupRequest) is provided. Exactly one of the two must be present.

object

content_type

required

ContentType

Tape-independent semantic content types for label rendering.

string

Allowed values: qr_only qr_one_line qr_two_lines qr_three_lines text_one_line text_two_lines qr_with_listing

data

Any of:

RawLabelData

RawLabelData

Raw label payload accepted when the client supplies data directly.

Mirrors LabelData minus source_app (set server-side to ‘manual’). All content fields are optional — ContentType-specific validation happens in LayoutEngine._validate_data.

Every free text is bounded at the request (the same caps as sheet items): 512 characters per text and QR payload, at most 10 secondary lines and 100 items. A label shows far less; the renderer shortens what does not fit (#258 security review).

object

items

Items

Array<object>

default: <= 100 items

RawListingItem

One listing row of raw label data, with bounded text.

object

item

required

Item

string

<= 512 characters

qr_payload

Qr Payload

Any of:

string

string

<= 512 characters

null

null

primary_id

Primary Id

Any of:

string

string

<= 512 characters

null

null

qr_payload

Qr Payload

Any of:

string

string

<= 512 characters

null

null

secondary

Secondary

Array<string>

default: <= 10 items

title

Title

Any of:

string

string

<= 512 characters

null

null

null

null

lookup

Any of:

PrintLookupRequest

PrintLookupRequest

Resolve label data via an integration plugin.

object

app

required

App

string

identifier

required

Identifier

string

null

null

options

PrintOptions

Per-print options — copies, cut behaviour, resolution, layout.

object

auto_cut

Auto Cut

boolean

default: true

copies

Copies

integer

default: 1 >= 1 <= 10

half_cut

Half Cut

boolean

high_resolution

High Resolution

boolean

last_page

Last Page

boolean

default: true

layout_preset

Any of:

QlLayoutPreset

QlLayoutPreset

The built-in QL 62 mm across-width layouts (docs/design/ql-layout-presets).

string

Allowed values: compact small_qr standard

null

null

orientation

Any of:

LabelOrientation

LabelOrientation

How the label content runs on endless tape.

string

Allowed values: across along

null

null

Responses

202

Successful Response

Media typeapplication/json

PrintJobResponse

POST /api/v1/print 202 body — queue accepted.

object

job_id

required

Job Id

string

status

required

Status

string

Allowed value: queued

Example

{
  "status": "queued"
}

422

Validation Error

Media typeapplication/json

HTTPValidationError

object

detail

Detail

Array<object>

ValidationError

object

ctx

Context

object

input

Input

loc

required

Location

Array

msg

required

Message

string

type

required

Error Type

string

Example ^generated

{
  "detail": [
    {
      "ctx": {},
      "input": "example",
      "loc": [
        "example"
      ],
      "msg": "example",
      "type": "example"
    }
  ]
}