API reference

Every endpoint, request and response field, error code and limit of the API. How the bins are chosen is explained in How slotting decides; the components' API is in Embedding the components and in slotting-components.d.ts.

Conventions#

• JSON in and out, Content-Type: application/json. Request bodies up to 25 MB.
• Units. Lengths are in the layout's unit and weights in its weightUnit, also in wave requests. The service never converts. Dimensions are 0.01 to 1,000,000.
• Ids. Layout and wave ids: 1 to 100 of A-Z a-z 0-9 . _ : -, starting with a letter or digit. Wall, bin and order ids and SKUs: 1 to 100 characters after trimming, without control characters and without #. Encode ids in URL paths.
• Wave ids are unique on the install, across layouts, so /api/waves/{waveId} finds a wave without its layout.
• Optional fields can be left out. null is not accepted where a value is expected.
• Trial license. Responses of successful changes have a top-level "license": { "trial": true } on an evaluation license (License).
• Never blocked by the license: every GET, /healthz, /v1/info, /docs/, /widget/, / and CORS preflights.

Layouts#

GET /api/layouts#

The layouts of the install: [{ "id": "PUTWALL-A", "name": "Put wall A", "walls": 1, "bins": 6 }].

POST /api/layouts#

Creates a layout. The body is a Layout: walls with bins (id, x, y, width, height, depth, and optional maxWeight, maxUnits, disabled and lightAddress). Answers 201 with the saved layout (ids trimmed). 409 duplicate_id if the id exists; 422 invalid_layout with issues if the layout is not valid (overlapping bins, duplicate ids, limits).

GET, PUT, DELETE /api/layouts/{layoutId}#

• GET: the layout.
• PUT: replaces it; the body is the whole layout (its id may be left out; if given, it must match the path). Walls and bins may be added; removing, shrinking or disabling a bin that an active wave holds answers 409 layout_in_use.
• DELETE: deletes it and answers { "id": "PUTWALL-A", "deleted": true }. 409 layout_in_use while a wave of the layout is not closed (complete waves still hold bins: close them first).

PATCH /api/layouts/{layoutId}/walls/{wallId}#

Moves a wall (typically a mobile one): { "position": { "x": 1200, "y": 300 }, "rotation": 90 }, either field optional. Allowed while waves run; it changes only the choice of bins from then on. Answers the updated wall.

GET /api/layouts/{layoutId}/bins#

The occupancy of every bin: an array of BinState.

GET /api/layouts/{layoutId}/lights#

The desired put-to-light state of the layout, whatever SLOTTING_LIGHTS is: an array of LightState, in layout order. Bins that are not listed are off.

Waves#

POST /api/waves#

Creates and plans a wave. Answers 201 with { "wave": WaveState, "plan": Plan }.

{
  "id": "WAVE-0815",
  "layoutId": "PUTWALL-A",
  "wallIds": ["A"],
  "orders": [
    { "id": "ORD-1001", "priority": 1, "lines": [{ "sku": "MUG", "quantity": 2 }, { "sku": "POSTER", "quantity": 1, "item": { "weight": 0.2 } }] }
  ],
  "items": { "MUG": { "length": 12, "width": 9, "height": 10, "weight": 0.4 } },
  "options": { "allocation": "complete-first", "maxBinsPerOrder": 8, "fillFactor": 0.85, "wallChangePenalty": 100 }
}

Order: id (unique in the wave), lines (at least one), priority (number, default 0; higher goes first). Line: sku, quantity (a whole number, 1 to 1,000,000), item (ItemDims, overrides items[sku] for this line). Several lines of one SKU in an order are added up (the first line's item applies). ItemDims: length, width, height, weight, each optional. An item without all three dimensions has no volume and skips the opening check (why that matters).

WaveOptions:

Plan:

WaveState (also GET /api/waves/{waveId}):

OrderState:

GET /api/waves#

The waves of the install, or of one layout with ?layoutId=PUTWALL-A: { "waves": [{ "id", "layoutId", "status", "createdAt", "closedAt", "stats" }] } (closedAt only for closed waves).

GET, DELETE /api/waves/{waveId}#

• GET: the WaveState. ?layoutId= is needed only if two layouts have a wave with this id.
• DELETE: deletes a closed wave and answers { "id": "WAVE-0815", "deleted": true }. A wave that is not closed answers 409 wave_active: close it first.

Every /api/waves/{waveId}... path takes ?layoutId= too; it is needed only when two layouts have a wave with this id.

Scanning#

POST /api/waves/{waveId}/scan#

One scan: which bin the unit goes into.

ScanResult:

Put-aside answers: 422 sku_not_in_wave, 409 sku_fully_slotted, 409 no_bin_available (with details.orderId, the order that needed the unit), 422 item_too_large. A closed wave answers 409 wave_closed.

POST /api/waves/{waveId}/confirm#

Confirms a pending put (waves with confirmPuts): the operator scanned the bin's label after putting the unit in.

ConfirmResult:

A put split over several bins needs one confirmation per bin. 409 wrong_bin when the scan's units went to other bins (details.expected: those bins, id and wallId; nothing changes), 409 not_pending when nothing waits for a confirmation there (or the scan has nothing pending any more), 404 unknown_scan for an unknown scanId, 409 wave_closed for a closed wave.

GET /api/waves/{waveId}/pending#

The puts of the wave still waiting for their confirmation, oldest scan first (an empty array for a wave without confirmPuts):

POST /api/waves/{waveId}/undo#

{ "scanId": "..." }: takes that scan's units back out (for a pending put: cancels it). Answers the WaveState. 404 unknown_scan for an unknown or already undone scan, 409 order_released when the scan's order was already released. After an undo, the same scanId is a new scan.

GET /api/waves/{waveId}/orders/{orderId}#

The order's OrderState.

POST /api/waves/{waveId}/orders/{orderId}/complete#

Completes the order short (units missing): short: true, and its reserved bins without units are freed. Answers the OrderState.

POST /api/waves/{waveId}/release#

{ "orderId": "ORD-1001" } or { "binId": "A-01-01" }: the order was packed out, its bins are free. With binId, the order holding that bin is released. Answers { "orderIds": [...], "bins": [{ "id", "wallId" }] }. Only complete orders: 409 order_not_complete otherwise, and 409 order_released for an order that was already released.

POST /api/waves/{waveId}/close#

Closes the wave: every bin it holds is freed, further scans answer 409 wave_closed. Answers the WaveState. Closing a closed wave changes nothing. Closed waves older than SLOTTING_WAVE_RETENTION_HOURS (default 72) are deleted when the next wave is created on the same layout.

Lights and webhooks#

POST /api/lights/press#

{ "layoutId": "PUTWALL-A", "address": "A-01-01" }: a button press on a bin's light, sent by a light gateway (or the wall component's simulator). address is the bin's lightAddress, else its id. The bin decides (Button presses):

• a pending put there: it is confirmed. Answers { "action": "confirmed", "result": ConfirmResult };
• the bin holds a complete order: the order is released. Answers { "action": "released", "orderIds": [...], "bins": [...] };
• the same bin pressed again within SLOTTING_PRESS_RELEASE_GUARD_MS (default 3000) of a press that confirmed a put there, or of its order completing: nothing changes. Answers 200 { "action": "ignored", "reason": "duplicate" } or "too_soon";
• anything else: 409 not_pending, nothing changes. 404 unknown_layout for an unknown layout.

GET /api/webhooks/dead-letters#

The webhook events given up after SLOTTING_WEBHOOK_MAX_ATTEMPTS, newest first: an array of { layoutId, event?, raw?, dropped?, reason, at }. event is the event given up; a corrupt outbox entry has raw (its text, redacted and clamped) instead, and events dropped over SLOTTING_OUTBOX_MAX_PER_LAYOUT are one entry with dropped (how many; the reason names the first and last ids) and no event. ?max= (1 to 1000, default 100) sets how many; the install keeps the last 1000.

POST /api/plan#

Plans without storing anything, for what-if questions ("does this wave fit the wall?"): { "layout": Layout, "orders": Order[], "items"?, "options"?, "wallIds"? }. Answers the Plan, as in POST /api/waves, as if the wall were empty.

POST /api/import/...#

Each import answers { "layout": Layout, "warnings": string[] }: a draft, never saved. The photo import also answers provider and model. The bodies and options are in Bin setups:

Errors: 422 invalid_import (unreadable content, missing options; CSV row errors in details.errors), 422 invalid_layout (the draft isn't valid, for example overlapping rectangles), 503 ai_not_configured, 502 ai_failed.

GET /healthz#

{ "status": "ok", "store": "redis", "storeOk": true }. While the store can't be reached it answers 503 with "status": "degraded" and "storeOk": false, so a load balancer takes the instance out of rotation. store is memory or redis. Never blocked.

GET /v1/info#

The version, the license, photo import, lights and webhooks of this install (it never contains a key, nor why a key was rejected: that is only in the server log). The Status page shows it. Never blocked, also without a license.

{"name":"slotting","version":"1.0.0","license":{"status":"valid","trial":false,"source":"configured","allowed":{"slotting":true},"products":["slotting"],"licensee":"Acme Corp","id":"LIC-0007","expires":"2027-10-31","daysLeft":375,"maxInstances":2,"instanceId":"sl-3f9a51c0d2e47b8a16c5e0f1"},"ai":{"configured":true,"provider":"anthropic","model":"claude-opus-5-5"}}

Fields that don't apply are absent.

Errors#

Every error is { "error": "<message>", "code": "<code>" }, with issues for invalid input and details where noted.

Limits#

• Layouts: at most 200 walls and 10,000 bins; dimensions 0.01 to 1,000,000; coordinates within ±10,000,000.
• Imports: DXF and CSV up to 20 MB of text; DXF up to 1,000,000 entities; photos JPEG, PNG or WebP up to 15 MB, up to 2,000 bins per photo.
• Waves: at most 5,000 orders per wave, 500 lines per order, 50,000 entries in the item master; quantities 1 to 1,000,000.
• Request bodies up to 25 MB; the photo's base64 text up to 20 MB.
• Planning is fast: 1,000 orders on 1,000 bins plan in well under a second, 5,000 on 5,000 in a few seconds.