Work Queues API

Add items, scan barcodes, claim and move work, run stage buttons and read queue reports.

Work Queues track items through a series of stages: boxes arriving at a warehouse, orders being packed, tickets being reviewed. This API puts items into a queue, scans barcodes, lets stations claim work, moves items between stages and reports what is where. Queues themselves (their stages and rules) are normally set up in the app.

If the Work Queues app is switched off in Settings › Apps, these routes answer 404 NOT_FOUND.

Endpoints

Queue ids are UUIDs. Permissions are checked against the queue (its key is the resource), so a role can be limited to one queue.

enqueue and transition are separate on purpose: a scanning station can add work without being able to move it through the pipeline, and a supervisor can move work without being able to invent it.

The queue object

{
  "id": "0190f0ff-…",
  "key": "inbound-boxes",
  "name": "Inbound boxes",
  "object_type": "",
  "enabled": true,
  "stages": [
    { "key": "expected", "label": "Expected", "kind": "start", "position": 0, "from": [], "wip_limit": 0, "sla_seconds": 0, "buttons": [] },
    { "key": "received", "label": "Received", "kind": "normal", "position": 1, "from": ["expected"], "wip_limit": 0, "sla_seconds": 3600, "buttons": [] },
    { "key": "shelved", "label": "Shelved", "kind": "terminal", "position": 2, "from": [], "wip_limit": 0, "sla_seconds": 0, "buttons": [] }
  ],
  "intake": { "enabled": false, "filter": [], "stage": "", "key_field": "", "close_on_unmatch": false },
  "settings": { "on_unknown_scan": "reject", "lease_seconds": 300, "allow_duplicates": false },
  "summary": { "total": 120, "open": 80, "closed": 40, "overdue": 3, "unexpected": 0, "by_stage": { "expected": 20 } }
}

Stage kind is start, normal or terminal. A terminal stage closes the item. from limits which stages may move into this one (empty means any). wip_limit caps how many items may sit in the stage (0 means no cap). sla_seconds marks items overdue after that long.

Creating a queue

POST and PUT take the same body: key (lowercase letters, digits, - or _, up to 60 characters; made from the name when omitted), name, object_type (optional record type to link items to), enabled, stages (up to 40, each with key, label, kind, from, wip_limit, sla_seconds, record_patch, on_enter, buttons), intake and settings. A PUT should echo the stage keys back so items keep their place. The key cannot be changed afterwards. Up to 200 queues per workspace (past that: 400 VALIDATION_ERROR). Errors: 409 KEY_TAKEN, 400 VALIDATION_ERROR.

The item object

{
  "id": "0190f100-…",
  "key": "BOX-000123",
  "stage": "received",
  "status": "open",
  "priority": 0,
  "source": "scan",
  "batch": "2026-10-04-truck-7",
  "record_id": "0190f0aa-…",
  "payload": { "weight_kg": 12.5 },
  "claimed_by": "0190f0a0-…",
  "claim_expires_at": "2026-10-04T09:35:00Z",
  "assignee_id": "",
  "attempts": 0,
  "due_at": "2026-10-04T10:30:00Z",
  "overdue": false,
  "entered_stage_at": "2026-10-04T09:30:00Z",
  "created_at": "2026-10-04T08:00:00Z"
}

status is open, done, failed or cancelled. source is manual, scan, import, intake or function. Items can carry up to 16 KB of payload.

POST /orgs/{orgId}/queues/{queueId}/items

Add items. The key is the item's identity in the queue, so adding a key that is already open is a harmless no-op (unless the queue is set to allow duplicates): a double scan or a retried request does not create duplicates.

curl -s -X POST https://axisiq.co/api/v1/orgs/$ORG/queues/$Q/items \
  -H "Authorization: Bearer $AXIS_KEY" -H "Content-Type: application/json" \
  -d '{"batch": "truck-7", "keys": ["BOX-000123", "BOX-000124", "BOX-000125"]}'

Response 201

{ "data": { "created": 3, "duplicates": 0, "items": [ { "id": "…", "key": "BOX-000123", "stage": "expected", "status": "open" } ] } }

Stage limits (work in progress caps) do not apply when adding items, only when moving them.

POST /orgs/{orgId}/queues/{queueId}/scan

Look an item up by its key and move it on, as a barcode scanner does. It always answers 200; the verdict tells you what happened.

{ "data": { "verdict": "moved", "message": "moved to received", "item": { "id": "…", "key": "BOX-000123", "stage": "received" } } }

POST /orgs/{orgId}/queues/{queueId}/items/{itemId}/move

Response 200 with the item. A move can be refused with 400 VALIDATION_ERROR when the target stage does not accept items from the current stage, or when it is at its limit. If the stage updates a linked record, that update is made first and as you, so a failure there stops the move.

POST /orgs/{orgId}/queues/{queueId}/claim

Take up to count waiting items from a stage for yourself. Used by pickers who each pull their own work. Two callers never receive the same item.

Response 200: { "items": [ … ], "claimed": 2 }. A claim lasts 5 minutes by default (set per queue) and then returns to the pool if not finished.

PATCH /orgs/{orgId}/queues/{queueId}/items/{itemId}

Change an item without moving it: priority, batch, assignee_id (empty string clears), due_at, payload, release (true gives up your claim), note. Only the stage cannot be changed here; use move.

GET /orgs/{orgId}/queues/{queueId}/items

Returns { "items": [ … ], "total": 120, "next_offset": 50 }. next_offset is null on the last page. The "missing items" report is ?stage=expected&status=open.

GET /orgs/{orgId}/queues/{queueId}/summary

Optional batch. Returns the verification report:

{
  "data": {
    "queue": { "id": "…", "key": "inbound-boxes", "name": "Inbound boxes" },
    "summary": { "total": 120, "open": 80, "closed": 40, "overdue": 3, "unexpected": 2, "by_stage": { "expected": 20, "received": 60, "shelved": 40 } }
  }
}

With a batch loaded as a manifest, items still sitting in the starting stage are the ones missing, and items created by a scan that nobody expected are counted as unexpected.

Other reads

• GET …/board?limit=&batch= returns { "queue": {…}, "stages": [ … ] }, each stage with its first items, total and next_offset.
• GET …/stages/{stageKey}/items accepts the same filters as the item list.
• GET …/batches lists batch labels.
• GET …/events?item_id=&limit= returns the movement history (default 100, maximum 500).

POST /orgs/{orgId}/queues/{queueId}/stages/{stageKey}/action

Runs a stage's button, a function, over up to 25 items, as you. Needs functions:invoke as well.

{ "button_id": "…", "item_ids": ["0190f100-…", "0190f101-…"] }

Returns one result per item: [{ "item_id": "…", "ok": true }, { "item_id": "…", "ok": false, "error": "…" }].

Errors

Related

• Functions SDK: axis.queue.* does the same from code, addressing queues by key
• In the product: Work Queues