Skip to content
LabelyardLabelyardLabelyard

Create a sheet, with the cells already used marked by hand

POST
/api/v1/sheets
curl --request POST \
  --url https://example.com/api/v1/sheets \
  --header 'Content-Type: application/json' \
  --header 'X-Label-Hub-Key: <X-Label-Hub-Key>' \
  --data '{ "id_placement": "cell", "note": "example", "printer": "example", "tray": "example", "type": "example", "used_cells": [], "version": 1 }'

id_placement margin (the default) and manual only store the sheet. cell also reserves the first free cell for the sheet ID label and queues an ID-only job on the named page printer; job_id names it. If the job cannot be queued, the sheet stays without a reservation and the ID goes onto the next job’s first free cell; the error names the sheet in error_detail.sheet_code.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
SheetCreate
object
id_placement
Id Placement

Where the sheet ID goes. margin (the default) and manual only store the sheet; the margin ID is printed by the first job that prints onto it. cell needs a page printer: it reserves the first free cell for the ID label and queues an ID-only job (job_id in the response).

string
Allowed values: cell margin manual
note
Note
Any of:
string
<= 500 characters
printer
Printer

Printer slug or UUID. Required for cell, ignored otherwise.

Any of:
string
>= 1 characters <= 100 characters
tray
Tray

Tray of the ID-only job; left out: the printer’s default.

Any of:
string
>= 1 characters <= 100 characters
type
required
Type
string
<= 64 characters /^[a-z0-9][a-z0-9-]{1,62}[a-z0-9]$/
used_cells
Used Cells
Array<object>
default: <= 400 items
MarkedCellIn
object
cell
required
Cell
integer
>= 1
purpose
Purpose

Left out or empty: the cell reads marked by hand.

Any of:

Plain text, at most 120 characters.

string
<= 120 characters
version
Version

Left out: the current version.

Any of:
integer
>= 1 <= 1000000

Responses

Section titled “Responses”

201

Section titled “201”

Successful Response

Media typeapplication/json
SheetCreated

The response of POST /api/v1/sheets: the sheet and the ID-only job of a cell sheet.

object
cells
required
Cells

Every cell that is not free, by cell number.

Array<object>
CellRead
object
cell
required
Cell
integer
is_id_cell
required
Is Id Cell

Whether the cell holds the sheet’s ID label (the hub fills it). Set by the hub; do not infer it from source.

boolean
job_id
required
Job Id
Any of:
string format: uuid
marked_by_hand
required
Marked By Hand
boolean
purpose
required
Purpose
Any of:
string
ref
required
Ref
Any of:
string
source
required
Source
string
state
required
State
string
Allowed values: reserved used unconfirmed
updated_at
required
Updated At
Any of:
string
code
required
Code
string
discarded_at
required
Discarded At
Any of:
string
feed_mark_printed
required
Feed Mark Printed

Whether the feed-direction mark has been printed on this sheet.

boolean
free
required
Free
integer
geometry
required
GeometryMm

Geometry of the version the sheet is pinned to.

object
cols
required
Cols
integer
>= 1 <= 400
corner_radius
Corner Radius
Any of:
number
<= 1000
label_h
required
Label H
number
<= 1000
label_w
required
Label W
number
<= 1000
margin_left
required
Margin Left
number
<= 1000
margin_top
required
Margin Top
number
<= 1000
page_h
Page H
Any of:
number
<= 1000
page_size
required
Page Size
string
Allowed values: A4 Letter
page_w
Page W
Any of:
number
<= 1000
pitch_x
required
Pitch X
number
<= 1000
pitch_y
required
Pitch Y
number
<= 1000
rows
required
Rows
integer
>= 1 <= 400
shape
required
Shape
string
Allowed values: rectangle round
id_placement
required
Id Placement
string
Allowed values: cell margin manual
id_printed
required
Id Printed
boolean
job_id
required
Job Id

The queued ID-only job (id_placement cell); otherwise null.

Any of:
string format: uuid
label_h
required
Label H
number
label_w
required
Label W
number
last_used_at
required
Last Used At
Any of:
string
note
required
Note
Any of:
string
reserved
required
Reserved
integer
state
required
State
string
Allowed values: active discarded
total
required
Total
integer
type_key
required
Type Key
string
type_label
required
Type Label
string
unconfirmed
required
Unconfirmed
integer
used
required
Used
integer
version
required
Version
integer

Example 

{
  "cells": [
    {
      "state": "reserved"
    }
  ],
  "geometry": {
    "page_size": "A4",
    "shape": "rectangle"
  },
  "id_placement": "cell",
  "state": "active"
}

403

Section titled “403”

These credentials may not use the printer.

Media typeapplication/json
object
detail
required
object
error_code
required
string
error_detail
Any of:
object
key
additional properties
any
error_message
required
string

Example generated

{
  "detail": {
    "error_code": "example",
    "error_detail": {},
    "error_message": "example"
  }
}

404

Section titled “404”

Sheet type or printer not found.

Media typeapplication/json
object
detail
required
object
error_code
required
string
error_detail
Any of:
object
key
additional properties
any
error_message
required
string

Example generated

{
  "detail": {
    "error_code": "example",
    "error_detail": {},
    "error_message": "example"
  }
}

409

Section titled “409”

Sheet type is archived, no cell is free for the ID (insufficient_cells), the printer is disabled (printer_disabled) or unknown to the queue.

Media typeapplication/json
object
detail
required
object
error_code
required
string
error_detail
Any of:
object
key
additional properties
any
error_message
required
string

Example generated

{
  "detail": {
    "error_code": "example",
    "error_detail": {},
    "error_message": "example"
  }
}

422

Section titled “422”

A cell number is outside the sheet, or cell without a printer.

Media typeapplication/json
object
detail
required
object
error_code
required
string
error_detail
Any of:
object
key
additional properties
any
error_message
required
string

Example generated

{
  "detail": {
    "error_code": "example",
    "error_detail": {},
    "error_message": "example"
  }
}

502

Section titled “502”

The ID-only job was queued only partly (print_interrupted).

Media typeapplication/json
object
detail
required
object
error_code
required
string
error_detail
Any of:
object
key
additional properties
any
error_message
required
string

Example generated

{
  "detail": {
    "error_code": "example",
    "error_detail": {},
    "error_message": "example"
  }
}