Openshelf LB Local API

Use cards for up to three active users and identifier entry for four or more.

Exchange email, name, assigned barcode, or scan token plus PIN for tokens.

Returns a logout acknowledgment for the authenticated user. Tokens are not revoked or blacklisted by this endpoint; the client must discard its access and refresh tokens.

Returns the active user, current role permissions, and optional access level. This is the account selected by authentication, including the configured development auto-user when that fallback is active.

Exchanges a valid refresh token for a new access token using the current user role/access settings. Returns the same refresh token, not a rotated token. Expired tokens and inactive or absent users return 401.

Stream short-lived signed tokens for new scanner events without exposing barcodes.

Return active non-system users only while the card experience applies.

Public health check. Reports the operating mode and robot initialization state. Returns 503 with a degraded body when initialization has failed, including when the mock runtime is unavailable. A healthy process may report a disabled robot; inspect robot_status and robot_phase before requesting motion.

Requires robot:control. Returns whether initialization is configured to home the robot; does not move hardware.

Requires robot:control. Persists whether robot initialization should home hardware. Does not home the robot immediately.

Read device identity, alias, release, and network address.

Public device discovery information. device_alias is the operator-assigned alias staged by provisioning, or null when the device has none. release_sha and release_branch identify the release the device is running, staged by the on-device sync scripts, or null when unknown. lan_ip is the IPv4 address of wlan0, or null when that interface cannot be read. This endpoint does not establish robot readiness.

Returns the current production, development, demo, or mock mode. Mode is selected at process startup; the API has no mode-changing endpoint. Use the repository startup tooling to change it.

Schedules a process exit so the container supervisor can restart the service. The response is sent before the restart; active connections can then close. Does not change the operating mode. Reconnect and check health before resuming work.

Removes waiting commands through the worker; requires robot:control. An active bin workflow or laser calibration prevents this mutation. Read durable command results to reconcile interrupted work.

Returns a durable command_id and current state after admission, not after physical completion. Poll /api/robot/commands/{command_id} for the result or subscribe to /api/robot/events before submitting. The status stream is not a command receipt.

For store/retrieve commands, reuse the same request_id and payload after an uncertain submission. Identical replays return the existing record; a different payload returns 409. Records and idempotency are retained for seven days. A terminal failure requires a new ID for a new attempt. Interrupted commands are failed at startup rather than replayed.

Create inventory first, then submit {"command":"store_item","request_id":"store-001","item":{"barcode":"880000000001"}}. New command-enrolled items require positive complete dimensions; include a name for compatibility with mock mode. Existing items use stored dimensions and mass: update inventory before submitting if these must change. Accepted enrollment survives execution failure.

To choose the destination cell, add a top-level location ({"side":"front_module","shelf_idx":0,"cell_idx":0}). The cell must exist in the storage grid, be available, and fit the item; a live bin home stays reserved and is reported unavailable. Omitting location keeps automatic allocation, and demo mode keeps its configured cell mapping.

For retrieval, read the item first and supply its location (side, zero-based shelf_idx, cell_idx). Bin-managed items require the bin workflow. Clear the IO box before retrieving. Home when home_required is reported. An item reserved by a tray interaction returns 409, as does a store or retrieval whose barcode or cell is already targeted by a queued or running command (target_in_flight); a full queue returns 429 with Retry-After.

Mock mode supports only store/retrieve, with one FIFO worker and simulated completion. Hardware modes also accept the engineering commands in the schema. A queued stop is not an emergency stop; use the physical emergency stop for immediate safety-critical stopping.

Available for mock and hardware command records. result is null before a terminal result is persisted and may contain a command-specific success or failure payload afterward. Unknown or expired IDs return 404. For measurement semantics, see the storage group; a successful retrieval does not guarantee a weight reading.

Directly opens, closes, or homes the IO door using the action query parameter. Runs under the manual-motion guard and cannot interrupt an active bin workflow. Hardware failures return 503.

Mock mode only: sets the simulated scale's occupied flag and pushes a status update, so a kiosk can walk through placing an item in the IO box without hardware. The robot clears it when it takes the item for a store. Hardware modes return 409.

Lists motor identifiers and configuration used by the diagnostic routes. Use returned identifiers as motor_name; this endpoint does not command motion.

Performs diagnostic position reads without commanding movement. Returns busy=true and a reason instead of probing when commands, manual motion, or demo cycling own the robot. Each result reports responsiveness independently.

Clears the hardware alarm and matching worker crash state, then refreshes status. This does not home the motor. Unknown names return 404; a failed hardware operation returns 503.

Engineering fault-injection endpoint that sets the selected motor's crash state. The worker can react as it would to a real crash. Unknown motor names return 404.

Runs the selected motor's homing operation with manual-motion guards. This moves hardware and may also position the tool for safe rotation. skip_pre_home_approach=true is restricted to the Y axis in development mode. Unknown names return 404; motion that another operation already holds returns 409.

Moves the selected motor to position_mm using the manual-motion guard. Rotation may require associated stage positioning. Unknown names return 404; motion that another operation already holds returns 409; hardware failures return 503.

Read the four switched power rails.

Reports what each rail feeds, the axes that lose their encoder reference when it is cut, and the current output state. powered is null when the rail cannot be read. Cut power only through the rail cycle operation: driving the output directly drops the drives without reconfiguring or re-homing the axes that lose their reference.

Cut a switched rail for a few seconds, then restore it.

Drive parameters that only latch at power-on need this -- any DI/DO function change stays inert until its drive restarts. Returns once power is back; the hardware is still booting, so re-home the axes it dropped before moving. An active command or queued work returns 409; a tray workflow that is idle between steps does not block the cycle.

Reads current scale weight in grams, stability/validity flags, decimal position, and raw registers. This is live telemetry, not a command-correlated result or inventory update. Mock mode returns a deterministic 350-gram reading. A disabled scale returns 404; communication failure returns 503.

Reads physical scale range, calibration weight, precision, and division settings. These settings belong to the hardware scale, not inventory container-mass fields.

Writes the supplied range, known weight, precision, and division to the physical scale. Inspect success in the response. An active bin workflow prevents mutation; this does not update item mass.

Reads the physical scale calibration status through the worker. A disabled scale returns 404; unavailable hardware or a failed read returns 503.

Sets the scale tare and returns a success flag. This changes the scale reading baseline; it does not set an inventory item's tare_weight. An active bin workflow prevents mutation.

Runs span calibration using the configured known calibration weight. Place the reference weight on the scale before calling. An active bin workflow prevents mutation; this does not change inventory mass.

Runs the hardware zero-calibration operation. Prepare the scale according to the engineering calibration procedure before calling. An active bin workflow prevents mutation. The response reports the hardware calibration result.

Publishes a label_scanned event as if the scanner had read barcode; requires robot:control. Available in mock mode as well as hardware modes. The event can advance a waiting bin workflow, so this is not a read-only scanner test.

Reports scanner connection and enabled state from the initialized worker. This does not trigger a hardware scan. Requires an authenticated user and an enabled robot.

Server-Sent Events; each event carries an id: line with its durable log seq and a data: frame with the event JSON. Events include terminal command results, scanner events, bin-workflow updates, and inventory_changed notices after storage API writes (refetch inventory on these); dispatch by command, message, or kind, rather than assuming every frame is a completion.

A fresh subscription starts live at the top of the log and receives no earlier events. Reconnect with the Last-Event-ID header set to the last id: you processed and the stream replays every event above that seq before resuming live, so a disconnect loses no events. Explicit replay of the log is available at /api/robot/events/log?since=<seq>. An event is forwarded only once its log row is committed; inventory changes commit before the event is forwarded. A terminal result includes command_id; use durable command polling to reconcile after long outages. weight, when present, is the cycle's gross reading in grams, not container net mass; both store and retrieve cycles supply it when a scale reading is available. A cursor above the log top (e.g. after a database reset or from another device) is clamped to the top: the stream starts live at the top and the gap is visible in the log. User tokens can be supplied through the bearer header or ?token=.

Returns events with seq > since, oldest first, at most limit per page. since=0 reads from the start of the log; after a page, request the next with since=next_since until next_since reaches latest_seq for a complete catch-up. next_since stays since for an empty page. This is the reconciliation path for /api/robot/events subscribers after a disconnect.

Performs an immediate authenticated gripper operation using the state query parameter. Changes physical hardware. Blocked while laser auto-calibration runs or another operation holds the manual-motion guard.

Acknowledges the worker safety guard once every interruption source is either clear or one an acknowledgement is enough to clear, such as a weight change that leaves the scale reading permanently shifted. Returns 409 with active_sources while a source that has to clear physically remains active. This does not bypass sensors or home the robot.

Engineering control requiring robot:control. bypass=true disables the worker safety guard; false restores it. Returns the resulting safety state. This changes physical safety behavior and must only be used in a controlled engineering procedure.

Engineering control requiring robot:control. Changes bypass for light_curtain, cabinet_doors or weight_change and returns the resulting safety state. Restore the component after the controlled diagnostic procedure.

Starts worker processing; requires robot:control. This is a worker lifecycle operation, not command submission. Returns 409 while laser auto-calibration is active and 503 if the robot is unavailable.

Server-Sent Events (text/event-stream). Each data: value is a JSON status snapshot with top-level mode; initialization progress may appear before the worker is ready. Database item locations are overlaid on storage occupancy. Subscribe for current state rather than durable command outcomes.

Supports bearer authentication or the user access token in ?token= for clients unable to set headers. Sends heartbeat comments while connected. Reconnect to obtain current status; the stream does not provide historical replay. Mock mode uses the same transport with simulated hardware state.

Waits for worker shutdown; requires robot:control. This differs from submitting a queued stop command and is not a physical emergency stop. Unavailable during laser auto-calibration.

Chooses storage for the requested item and operation. A storage_mode=direct response with workflow=null means no tray workflow was started; submit an ordinary command separately. A tray result starts delivery to the IO box. Retrieval requires access to every item in that bin. Clear the IO box first; a tray or item already in use, or an unavailable robot worker, returns 409.

List unfinished take, place, and return interactions. Outside trays do not reserve the robot; completed interactions are omitted, and so are import trays, which the import screen drives.

List tray motions a crash or emergency stop interrupted whose tray is still marked outside. The crash dialog names these trays and their home cells so the operator can put them back.

Mark trays from interrupted motions as home after the operator confirmed them on their shelves in the crash dialog. An interrupted return records the contents confirmed before it started. Does not move hardware. A tray whose state conflicts with being home stays outside and is listed as unresolved.

Resolve a tray barcode and open contents selection without moving hardware. Known contents are selected by default; an item just taken out is listed but unselected. An already stored tray returns 409.