Openshelf Integration Relay

Send the provisioned key in X-API-Key; no request body is required. Use the returned token as Authorization: Bearer <access_token> on /v1 requests. expires_in is seconds from issuance. Obtain another token when it expires; there is no refresh-token endpoint. Token exchange is limited to a burst of five requests per source IP, replenishing at five per minute.

Checks the authorized device through its backend. Returns 503 when it cannot serve requests and 404 for unknown or unauthorized device IDs. A successful check is not a reservation or a guarantee that a subsequent command can run.

Returns an offset-based page and the total inventory count. Dimensions are millimeters and weight is grams. Inventory records may exist without a storage location. For bin-managed items, locations is empty and direct retrieval is unavailable. Pagination is not a snapshot: concurrent inventory changes can affect subsequent pages.

Creates an item or updates the record with the same barcode on the device. This changes inventory only; submit a store_item command to move the item physically. Supply positive dimensions in millimeters. For an existing record, prefer the item update endpoint for partial edits. Reserved bin barcodes and forbidden changes to bin-managed items return 409.

Retrieve the item before deleting its record. Returns 409 with item_still_stored for occupied locations or item_in_bin for bin membership. Deletion does not issue a robot command.

Read this before retrieval to obtain a current actionable location. An empty location list may mean the item is not stored or is bin-managed; inspect storage_mode. Returns 404 when the item is absent.

Updates the supplied non-null fields; omitted and null fields are not forwarded and leave their values unchanged. Metadata, when supplied, replaces the metadata object. Does not move the item. Changing a bin-managed item's dimensions is blocked until it is retrieved.

Prints a barcode label through the device, which renders the supplied value as a Code 128 label; any non-empty barcode is accepted. This request does not create an inventory record and has no command idempotency key; retrying can print another label. A mock device accepts the request without producing a physical label.

Acceptance is not completion. Save command_id, then poll the command endpoint or consume a registered webhook for its terminal result. Only store_item and retrieve_item are exposed.

Supply a stable request_id for each logical operation. Retry an uncertain submission with the same ID and payload: the device returns the original command, including its current state. Reusing an ID with different content returns 409; use a new ID for a new attempt after a terminal failure. Device records are retained for seven days.

For storage, create the inventory record first or supply the new item's name and dimensions. For retrieval, use a current direct location from the item endpoint. Bin-managed items require an on-device tray workflow: a direct store or retrieve of a tray member returns 409. 423 comes from device firmware that still locks the device while a workflow owns it; 429 means rate or queue capacity was exceeded. Only retry after addressing the reported condition.

Poll the ID returned by submission. queued and running are nonterminal; succeeded and failed are terminal. result can be null before completion. This durable record is the recovery path if a webhook is missed. An unknown or expired command returns 404. A backend result that does not match the cloud contract returns 502.

Returns the device's current activity, not a command receipt or terminal result. queue_length counts waiting commands. Use command polling to determine a particular operation's outcome. Returns 503 when no current live status is available.

Lists registrations belonging to your partner whose entire device set is accessible to the current API key. Signing secrets are never included. Use the registration ID to delete a receiver.

Registers an HTTPS receiver for the selected authorized devices and events. Save the returned secret immediately; it is only returned at creation. The URL must use a hostname resolving exclusively to public addresses, without credentials or fragments. IP-literal URLs and redirects are not supported.

The callback below describes outbound requests to your receiver. Verify its signature over the original body bytes, deduplicate by event_id, and acknowledge with any 2xx after accepting the event. Delivery is retried up to 12 total attempts: the first retry is immediate, then exponential delays from one second, capped at 300 seconds. Delivery is ordered per registration/device; no global ordering is promised.

Retries preserve the event body and timestamp. Avoid a narrow timestamp window that rejects legitimate retries. Event capture depends on a live device stream and is not replayable through this API; use command polling to recover missed outcomes. Registrations apply to future captured events.

Removes the accessible registration and its pending deliveries. An in-flight HTTP delivery may already have reached the receiver. Returns an empty 204 response; an unknown or inaccessible registration returns 404.

Public liveness check for the relay process. A successful response does not establish that any device is online; use the device health endpoint for that.