{ "components": { "schemas": { "CommandAcceptedResponse": { "properties": { "command_id": { "title": "Command Id", "type": "string" }, "message": { "const": "success", "title": "Message", "type": "string" }, "status": { "enum": [ "queued", "running", "succeeded", "failed" ], "title": "Status", "type": "string" } }, "required": [ "message", "command_id", "status" ], "title": "CommandAcceptedResponse", "type": "object" }, "CommandStatusResponse": { "properties": { "command": { "enum": [ "store_item", "retrieve_item" ], "title": "Command", "type": "string" }, "command_id": { "title": "Command Id", "type": "string" }, "completed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Completed At" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "request_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Request Id" }, "result": { "anyOf": [ { "$ref": "#/components/schemas/StoreCommandResult" }, { "$ref": "#/components/schemas/RetrieveCommandResult" }, { "$ref": "#/components/schemas/FailedCommandResult" }, { "type": "null" } ], "description": "Terminal outcome, or null before one is available", "title": "Result" }, "started_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Started At" }, "status": { "enum": [ "queued", "running", "succeeded", "failed" ], "title": "Status", "type": "string" } }, "required": [ "command_id", "request_id", "command", "status", "result", "created_at", "started_at", "completed_at" ], "title": "CommandStatusResponse", "type": "object" }, "DeleteItemResponse": { "properties": { "message": { "const": "Item deleted successfully", "title": "Message", "type": "string" } }, "required": [ "message" ], "title": "DeleteItemResponse", "type": "object" }, "Dimensions": { "properties": { "height": { "description": "Height in millimeters", "examples": [ 10 ], "exclusiveMinimum": 0.0, "title": "Height", "type": "number" }, "length": { "description": "Length in millimeters", "examples": [ 10 ], "exclusiveMinimum": 0.0, "title": "Length", "type": "number" }, "width": { "description": "Width in millimeters", "examples": [ 10 ], "exclusiveMinimum": 0.0, "title": "Width", "type": "number" } }, "required": [ "width", "height", "length" ], "title": "Dimensions", "type": "object" }, "FailedCommandResult": { "properties": { "code": { "title": "Code", "type": "string" }, "command": { "anyOf": [ { "enum": [ "store_item", "retrieve_item" ], "type": "string" }, { "type": "null" } ], "title": "Command" }, "command_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Command Id" }, "error": { "title": "Error", "type": "string" }, "message": { "const": "failed", "title": "Message", "type": "string" } }, "required": [ "message", "error", "code" ], "title": "FailedCommandResult", "type": "object" }, "HealthResponse": { "properties": { "status": { "const": "ok", "default": "ok", "title": "Status", "type": "string" } }, "title": "HealthResponse", "type": "object" }, "ItemCreate": { "properties": { "dimensions": { "$ref": "#/components/schemas/Dimensions" }, "metadata": { "additionalProperties": true, "title": "Metadata", "type": "object" }, "name": { "maxLength": 255, "minLength": 1, "title": "Name", "type": "string" }, "upca": { "description": "Inventory barcode identifier. Printing separately requires an 11- or 12-digit UPCA.", "examples": [ "880000000001" ], "maxLength": 255, "minLength": 1, "title": "Upca", "type": "string" }, "weight": { "anyOf": [ { "exclusiveMinimum": 0.0, "type": "number" }, { "type": "null" } ], "description": "Gross item mass in grams; null is not forwarded on writes.", "examples": [ 350 ], "title": "Weight" } }, "required": [ "upca", "name", "dimensions" ], "title": "ItemCreate", "type": "object" }, "ItemDimensionsResponse": { "properties": { "height": { "title": "Height", "type": "number" }, "length": { "title": "Length", "type": "number" }, "width": { "title": "Width", "type": "number" } }, "required": [ "width", "height", "length" ], "title": "ItemDimensionsResponse", "type": "object" }, "ItemListResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/ItemResponse" }, "title": "Items", "type": "array" }, "limit": { "title": "Limit", "type": "integer" }, "skip": { "title": "Skip", "type": "integer" }, "total": { "title": "Total", "type": "integer" } }, "required": [ "items", "total", "skip", "limit" ], "title": "ItemListResponse", "type": "object" }, "ItemLocationResponse": { "properties": { "cell_idx": { "title": "Cell Idx", "type": "integer" }, "shelf_idx": { "title": "Shelf Idx", "type": "integer" }, "side": { "enum": [ "left_module", "right_module" ], "title": "Side", "type": "string" } }, "required": [ "side", "shelf_idx", "cell_idx" ], "title": "ItemLocationResponse", "type": "object" }, "ItemResponse": { "properties": { "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created At" }, "dimensions": { "$ref": "#/components/schemas/ItemDimensionsResponse" }, "id": { "title": "Id", "type": "integer" }, "locations": { "description": "Directly actionable storage locations; always empty for bin-managed items.", "items": { "$ref": "#/components/schemas/ItemLocationResponse" }, "title": "Locations", "type": "array" }, "metadata": { "additionalProperties": true, "title": "Metadata", "type": "object" }, "name": { "title": "Name", "type": "string" }, "storage_mode": { "description": "How the item is stored. Bin-managed items cannot be retrieved directly.", "enum": [ "direct", "bin" ], "title": "Storage Mode", "type": "string" }, "upca": { "title": "Upca", "type": "string" }, "updated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Updated At" }, "weight": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Weight" } }, "required": [ "id", "upca", "name", "dimensions", "storage_mode" ], "title": "ItemResponse", "type": "object" }, "ItemUpdate": { "properties": { "dimensions": { "anyOf": [ { "$ref": "#/components/schemas/Dimensions" }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata" }, "name": { "anyOf": [ { "maxLength": 255, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Name" }, "weight": { "anyOf": [ { "exclusiveMinimum": 0.0, "type": "number" }, { "type": "null" } ], "description": "Gross item mass in grams; null is not forwarded on writes.", "examples": [ 350 ], "title": "Weight" } }, "title": "ItemUpdate", "type": "object" }, "Location": { "properties": { "cell_idx": { "description": "Zero-based cell index", "examples": [ 2 ], "minimum": 0.0, "title": "Cell Idx", "type": "integer" }, "shelf_idx": { "description": "Zero-based shelf index", "examples": [ 0 ], "minimum": 0.0, "title": "Shelf Idx", "type": "integer" }, "side": { "enum": [ "left_module", "right_module" ], "title": "Side", "type": "string" } }, "required": [ "side", "shelf_idx", "cell_idx" ], "title": "Location", "type": "object" }, "PrintLabelResponse": { "properties": { "message": { "const": "success", "title": "Message", "type": "string" }, "printed": { "title": "Printed", "type": "boolean" }, "upca": { "title": "Upca", "type": "string" } }, "required": [ "message", "upca", "printed" ], "title": "PrintLabelResponse", "type": "object" }, "ReducedStatus": { "properties": { "current_command": { "anyOf": [ { "$ref": "#/components/schemas/StoreCommand" }, { "$ref": "#/components/schemas/RetrieveCommand" }, { "type": "null" } ], "title": "Current Command" }, "queue_length": { "description": "Waiting commands, excluding the currently executing command", "minimum": 0.0, "title": "Queue Length", "type": "integer" } }, "required": [ "current_command", "queue_length" ], "title": "ReducedStatus", "type": "object" }, "RelayErrorBody": { "properties": { "code": { "title": "Code", "type": "string" }, "correlation_id": { "title": "Correlation Id", "type": "string" }, "message": { "title": "Message", "type": "string" } }, "required": [ "code", "message", "correlation_id" ], "title": "RelayErrorBody", "type": "object" }, "RetrieveCommand": { "properties": { "command": { "const": "retrieve_item", "title": "Command", "type": "string" }, "location": { "$ref": "#/components/schemas/Location" }, "request_id": { "description": "Stable ID for one logical command. Reuse with identical content for retry; a different payload conflicts.", "examples": [ "store-001" ], "maxLength": 255, "minLength": 1, "title": "Request Id", "type": "string" }, "upca": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Upca" } }, "required": [ "command", "request_id", "location" ], "title": "RetrieveCommand", "type": "object" }, "RetrieveCommandResult": { "properties": { "command": { "const": "retrieve_item", "title": "Command", "type": "string" }, "command_id": { "title": "Command Id", "type": "string" }, "location": { "$ref": "#/components/schemas/Location" }, "message": { "const": "success", "title": "Message", "type": "string" }, "upca": { "title": "Upca", "type": "string" }, "weight": { "description": "Measured item weight in grams", "exclusiveMinimum": 0.0, "title": "Weight", "type": "number" } }, "required": [ "message", "command", "command_id", "upca", "location", "weight" ], "title": "RetrieveCommandResult", "type": "object" }, "StoreCommand": { "properties": { "command": { "const": "store_item", "title": "Command", "type": "string" }, "item": { "$ref": "#/components/schemas/StoreItemPayload" }, "request_id": { "description": "Stable ID for one logical command. Reuse with identical content for retry; a different payload conflicts.", "examples": [ "store-001" ], "maxLength": 255, "minLength": 1, "title": "Request Id", "type": "string" } }, "required": [ "command", "request_id", "item" ], "title": "StoreCommand", "type": "object" }, "StoreCommandResult": { "properties": { "command": { "const": "store_item", "title": "Command", "type": "string" }, "command_id": { "title": "Command Id", "type": "string" }, "location": { "$ref": "#/components/schemas/Location" }, "message": { "const": "success", "title": "Message", "type": "string" }, "upca": { "title": "Upca", "type": "string" }, "weight": { "description": "Measured item weight in grams", "exclusiveMinimum": 0.0, "title": "Weight", "type": "number" } }, "required": [ "message", "command", "command_id", "upca", "location", "weight" ], "title": "StoreCommandResult", "type": "object" }, "StoreItemPayload": { "additionalProperties": false, "properties": { "dimensions": { "anyOf": [ { "$ref": "#/components/schemas/Dimensions" }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata" }, "name": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "title": "Name" }, "upca": { "description": "Inventory barcode identifier. Printing separately requires an 11- or 12-digit UPCA.", "examples": [ "880000000001" ], "maxLength": 255, "minLength": 1, "title": "Upca", "type": "string" }, "weight": { "anyOf": [ { "exclusiveMinimum": 0.0, "type": "number" }, { "type": "null" } ], "description": "Gross item mass in grams; null is not forwarded on writes.", "examples": [ 350 ], "title": "Weight" } }, "required": [ "upca" ], "title": "StoreItemPayload", "type": "object" }, "TokenResponse": { "properties": { "access_token": { "title": "Access Token", "type": "string" }, "expires_in": { "description": "Access-token lifetime in seconds from issuance", "title": "Expires In", "type": "integer" }, "token_type": { "const": "bearer", "default": "bearer", "title": "Token Type", "type": "string" } }, "required": [ "access_token", "expires_in" ], "title": "TokenResponse", "type": "object" }, "WebhookCreate": { "properties": { "device_ids": { "items": { "pattern": "^[0-9a-f]{8}$", "type": "string" }, "minItems": 1, "title": "Device Ids", "type": "array" }, "events": { "items": { "enum": [ "command.succeeded", "command.failed" ], "type": "string" }, "title": "Events", "type": "array" }, "url": { "description": "Public HTTPS hostname URL without credentials or fragments. Redirects and IP literals are not supported.", "examples": [ "https://integrator.example.com/opshelf/events" ], "maxLength": 2048, "minLength": 1, "title": "Url", "type": "string" } }, "required": [ "url", "device_ids" ], "title": "WebhookCreate", "type": "object" }, "WebhookCreatedResponse": { "properties": { "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "device_ids": { "items": { "pattern": "^[0-9a-f]{8}$", "type": "string" }, "title": "Device Ids", "type": "array" }, "events": { "items": { "enum": [ "command.succeeded", "command.failed" ], "type": "string" }, "title": "Events", "type": "array" }, "id": { "title": "Id", "type": "string" }, "secret": { "description": "Webhook HMAC signing key, returned only once at registration creation", "title": "Secret", "type": "string" }, "url": { "title": "Url", "type": "string" } }, "required": [ "id", "url", "device_ids", "events", "created_at", "secret" ], "title": "WebhookCreatedResponse", "type": "object" }, "WebhookEnvelope": { "properties": { "data": { "anyOf": [ { "$ref": "#/components/schemas/StoreCommandResult" }, { "$ref": "#/components/schemas/RetrieveCommandResult" }, { "$ref": "#/components/schemas/FailedCommandResult" } ], "title": "Data" }, "device_id": { "pattern": "^[0-9a-f]{8}$", "title": "Device Id", "type": "string" }, "event": { "enum": [ "command.succeeded", "command.failed" ], "title": "Event", "type": "string" }, "event_id": { "description": "Stable event identifier; use for receiver deduplication", "title": "Event Id", "type": "string" }, "occurred_at": { "format": "date-time", "title": "Occurred At", "type": "string" }, "sequence": { "description": "Monotonically increasing per-device capture sequence; subscription gaps are possible", "title": "Sequence", "type": "integer" }, "version": { "const": "v1", "default": "v1", "title": "Version", "type": "string" } }, "required": [ "event_id", "sequence", "device_id", "event", "occurred_at", "data" ], "title": "WebhookEnvelope", "type": "object" }, "WebhookResponse": { "properties": { "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "device_ids": { "items": { "pattern": "^[0-9a-f]{8}$", "type": "string" }, "title": "Device Ids", "type": "array" }, "events": { "items": { "enum": [ "command.succeeded", "command.failed" ], "type": "string" }, "title": "Events", "type": "array" }, "id": { "title": "Id", "type": "string" }, "url": { "title": "Url", "type": "string" } }, "required": [ "id", "url", "device_ids", "events", "created_at" ], "title": "WebhookResponse", "type": "object" } }, "securitySchemes": { "HTTPBearer": { "scheme": "bearer", "type": "http" }, "PartnerApiKey": { "description": "Provisioned partner key, used only for token exchange.", "in": "header", "name": "X-API-Key", "type": "apiKey" } } }, "info": { "description": "Cloud API for integrating inventory and asynchronous store/retrieve operations\nwith provisioned Openshelf devices. Device IDs and API keys are supplied during onboarding;\nthis API does not expose device administration or low-level hardware controls.\n\nBase URL: `https://api.opshelf.com`. Append the documented `/v1/...` path\n(or `/healthz` for the service health check).\n\n## First integration\n1. Exchange your provisioned `X-API-Key` at `POST /v1/auth/token`.\n2. Send `Authorization: Bearer ` on subsequent `/v1` requests.\n3. Check your device, create/read its inventory item, then submit a command\n with a stable `request_id`.\n4. Save the accepted `command_id` and poll its result, or register a webhook before submission.\n\nInventory records and physical storage are distinct: creating a record does not move an\nitem. Successful submission means acceptance, not completion. Bin-managed items are\nvisible but cannot be retrieved through the direct command API.\n\n## Errors and limits\nErrors contain `code`, `message`, and `correlation_id`. Preserve the response\n`X-Correlation-ID` for support; you may supply a 1\u2013128 character ID using letters, digits,\ndot, underscore, or hyphen. Unknown and unauthorized devices both return `404`.\n\nAuthenticated routes share a per-key limit of five requests/second with a burst of 20.\nToken exchange allows a burst of five per source IP, replenishing at five/minute.\nMutation bodies are limited to 64 KiB. On `429`, honor `Retry-After` when present;\notherwise back off. Retry uncertain commands with the same request ID and payload.\nResolve `409`/`423` state conflicts before retrying; do not blindly replay physical work.\n\nDimensions are millimeters, weight is grams, and location indices are zero-based.\nThe local engineering API is documented separately at\n[Local API](https://api.opshelf.com/docs/local/). Schemas here describe the cloud contract;\nnot every local field or command is exposed.\n", "title": "Openshelf Integration Relay", "version": "1.0.0" }, "openapi": "3.1.0", "paths": { "/healthz": { "get": { "description": "Check relay availability.\n\nPublic liveness check for the relay process. A successful response does not\nestablish that any device is online; use the device health endpoint for that.", "operationId": "healthz_healthz_get", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } }, "description": "Successful Response", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Invalid request", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Authentication failed", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Operation forbidden", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Resource not found", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Request conflicts with current device state", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Request body too large", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Request validation failed", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "423": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Device is temporarily locked by an active workflow", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Rate or queue limit exceeded", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Invalid response from device", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Device or backend unavailable", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } } }, "summary": "Check relay availability", "tags": [ "service" ] } }, "/v1/auth/token": { "post": { "description": "Exchange an API key for an access token.\n\nSend the provisioned key in `X-API-Key`; no request body is required. Use the\nreturned token as `Authorization: Bearer ` on `/v1` requests.\n`expires_in` is seconds from issuance. Obtain another token when it expires; there\nis no refresh-token endpoint. Token exchange is limited to a burst of five requests\nper source IP, replenishing at five per minute.", "operationId": "exchange_token_v1_auth_token_post", "parameters": [ { "description": "Provisioned partner API key; exchange it for a bearer token.", "in": "header", "name": "X-API-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Provisioned partner API key; exchange it for a bearer token.", "title": "X-Api-Key" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenResponse" } } }, "description": "Successful Response", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Invalid request", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Authentication failed", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Operation forbidden", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Resource not found", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Request conflicts with current device state", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Request body too large", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Request validation failed", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "423": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Device is temporarily locked by an active workflow", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Rate or queue limit exceeded", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Invalid response from device", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Device or backend unavailable", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } } }, "security": [ { "PartnerApiKey": [] } ], "summary": "Exchange an API key for an access token", "tags": [ "authentication" ] } }, "/v1/devices/{device_id}/commands": { "post": { "description": "Queue a store or retrieve command.\n\nAcceptance is not completion. Save `command_id`, then poll the command endpoint or\nconsume a registered webhook for its terminal result. Only `store_item` and\n`retrieve_item` are exposed.\n\nSupply a stable `request_id` for each logical operation. Retry an uncertain\nsubmission with the same ID and payload: the device returns the original command,\nincluding its current state. Reusing an ID with different content returns `409`; use\na new ID for a new attempt after a terminal failure. Device records are retained for\nseven days.\n\nFor storage, create the inventory record first or supply the new item's name and\ndimensions. For retrieval, use a current direct location from the item endpoint.\nBin-managed items require an on-device workflow. `423` means another workflow owns\nthe device; `429` means rate or queue capacity was exceeded. Only retry after\naddressing the reported condition.", "operationId": "submit_command_v1_devices__device_id__commands_post", "parameters": [ { "in": "path", "name": "device_id", "required": true, "schema": { "pattern": "^[0-9a-f]{8}$", "title": "Device Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "discriminator": { "mapping": { "retrieve_item": "#/components/schemas/RetrieveCommand", "store_item": "#/components/schemas/StoreCommand" }, "propertyName": "command" }, "oneOf": [ { "$ref": "#/components/schemas/StoreCommand" }, { "$ref": "#/components/schemas/RetrieveCommand" } ], "title": "Command" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommandAcceptedResponse" } } }, "description": "Successful Response", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Invalid request", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Authentication failed", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Operation forbidden", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Resource not found", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Request conflicts with current device state", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Request body too large", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Request validation failed", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "423": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Device is temporarily locked by an active workflow", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Rate or queue limit exceeded", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Invalid response from device", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Device or backend unavailable", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Queue a store or retrieve command", "tags": [ "commands" ] } }, "/v1/devices/{device_id}/commands/{command_id}": { "get": { "description": "Read a command and its result.\n\nPoll the ID returned by submission. `queued` and `running` are nonterminal;\n`succeeded` and `failed` are terminal. `result` can be null before completion. This\ndurable record is the recovery path if a webhook is missed. An unknown or expired\ncommand returns `404`. A backend result that does not match the cloud contract\nreturns `502`.", "operationId": "get_command_v1_devices__device_id__commands__command_id__get", "parameters": [ { "in": "path", "name": "device_id", "required": true, "schema": { "pattern": "^[0-9a-f]{8}$", "title": "Device Id", "type": "string" } }, { "in": "path", "name": "command_id", "required": true, "schema": { "title": "Command Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommandStatusResponse" } } }, "description": "Successful Response", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Invalid request", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Authentication failed", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Operation forbidden", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Resource not found", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Request conflicts with current device state", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Request body too large", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Request validation failed", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "423": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Device is temporarily locked by an active workflow", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Rate or queue limit exceeded", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Invalid response from device", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Device or backend unavailable", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Read a command and its result", "tags": [ "commands" ] } }, "/v1/devices/{device_id}/health": { "get": { "description": "Check device availability.\n\nChecks the authorized device through its backend. Returns `503` when it cannot serve\nrequests and `404` for unknown or unauthorized device IDs. A successful check is not\na reservation or a guarantee that a subsequent command can run.", "operationId": "device_health_v1_devices__device_id__health_get", "parameters": [ { "in": "path", "name": "device_id", "required": true, "schema": { "pattern": "^[0-9a-f]{8}$", "title": "Device Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } }, "description": "Successful Response", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Invalid request", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Authentication failed", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Operation forbidden", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Resource not found", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Request conflicts with current device state", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Request body too large", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Request validation failed", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "423": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Device is temporarily locked by an active workflow", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Rate or queue limit exceeded", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Invalid response from device", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Device or backend unavailable", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Check device availability", "tags": [ "devices" ] } }, "/v1/devices/{device_id}/items": { "get": { "description": "List device inventory.\n\nReturns an offset-based page and the total inventory count. Dimensions are\nmillimeters and weight is grams. Inventory records may exist without a storage\nlocation. For bin-managed items, `locations` is empty and direct retrieval is\nunavailable. Pagination is not a snapshot: concurrent inventory changes can affect\nsubsequent pages.", "operationId": "list_items_v1_devices__device_id__items_get", "parameters": [ { "in": "path", "name": "device_id", "required": true, "schema": { "pattern": "^[0-9a-f]{8}$", "title": "Device Id", "type": "string" } }, { "description": "Number of inventory records to skip", "in": "query", "name": "skip", "required": false, "schema": { "default": 0, "description": "Number of inventory records to skip", "minimum": 0, "title": "Skip", "type": "integer" } }, { "description": "Maximum records in this page", "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "description": "Maximum records in this page", "maximum": 200, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemListResponse" } } }, "description": "Successful Response", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Invalid request", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Authentication failed", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Operation forbidden", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Resource not found", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Request conflicts with current device state", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Request body too large", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Request validation failed", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "423": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Device is temporarily locked by an active workflow", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Rate or queue limit exceeded", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Invalid response from device", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Device or backend unavailable", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "List device inventory", "tags": [ "items" ] }, "post": { "description": "Create or replace an inventory record.\n\nCreates an item or updates the record with the same UPCA on the device. This changes\ninventory only; submit a `store_item` command to move the item physically. Supply\npositive dimensions in millimeters. For an existing record, prefer PUT for partial\nedits. Reserved bin barcodes and changes forbidden by an active workflow return\n`409`.", "operationId": "create_item_v1_devices__device_id__items_post", "parameters": [ { "in": "path", "name": "device_id", "required": true, "schema": { "pattern": "^[0-9a-f]{8}$", "title": "Device Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemCreate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemResponse" } } }, "description": "Successful Response", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Invalid request", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Authentication failed", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Operation forbidden", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Resource not found", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Request conflicts with current device state", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Request body too large", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Request validation failed", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "423": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Device is temporarily locked by an active workflow", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Rate or queue limit exceeded", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Invalid response from device", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Device or backend unavailable", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create or replace an inventory record", "tags": [ "items" ] } }, "/v1/devices/{device_id}/items/{upca}": { "delete": { "description": "Delete an unstored inventory record.\n\nRetrieve the item before deleting its record. Returns `409` with `item_still_stored`\nfor occupied locations or `item_in_bin` for bin membership. Deletion does not issue\na robot command.", "operationId": "delete_item_v1_devices__device_id__items__upca__delete", "parameters": [ { "in": "path", "name": "device_id", "required": true, "schema": { "pattern": "^[0-9a-f]{8}$", "title": "Device Id", "type": "string" } }, { "in": "path", "name": "upca", "required": true, "schema": { "title": "Upca", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteItemResponse" } } }, "description": "Successful Response", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Invalid request", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Authentication failed", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Operation forbidden", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Resource not found", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Request conflicts with current device state", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Request body too large", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Request validation failed", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "423": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Device is temporarily locked by an active workflow", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Rate or queue limit exceeded", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Invalid response from device", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Device or backend unavailable", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete an unstored inventory record", "tags": [ "items" ] }, "get": { "description": "Read an inventory item.\n\nRead this before retrieval to obtain a current actionable location. An empty\nlocation list may mean the item is not stored or is bin-managed; inspect\n`storage_mode`. Returns `404` when the item is absent.", "operationId": "get_item_v1_devices__device_id__items__upca__get", "parameters": [ { "in": "path", "name": "device_id", "required": true, "schema": { "pattern": "^[0-9a-f]{8}$", "title": "Device Id", "type": "string" } }, { "in": "path", "name": "upca", "required": true, "schema": { "title": "Upca", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemResponse" } } }, "description": "Successful Response", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Invalid request", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Authentication failed", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Operation forbidden", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Resource not found", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Request conflicts with current device state", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Request body too large", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Request validation failed", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "423": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Device is temporarily locked by an active workflow", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Rate or queue limit exceeded", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Invalid response from device", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Device or backend unavailable", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Read an inventory item", "tags": [ "items" ] }, "put": { "description": "Update an inventory record.\n\nUpdates the supplied non-null fields; omitted and null fields are not forwarded and\nleave their values unchanged. Metadata, when supplied, replaces the metadata object.\nDoes not move the item. Changing a bin-managed item's dimensions is blocked until it\nis retrieved. An active bin workflow can also return `409`.", "operationId": "update_item_v1_devices__device_id__items__upca__put", "parameters": [ { "in": "path", "name": "device_id", "required": true, "schema": { "pattern": "^[0-9a-f]{8}$", "title": "Device Id", "type": "string" } }, { "in": "path", "name": "upca", "required": true, "schema": { "title": "Upca", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemResponse" } } }, "description": "Successful Response", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Invalid request", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Authentication failed", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Operation forbidden", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Resource not found", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Request conflicts with current device state", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Request body too large", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Request validation failed", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "423": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Device is temporarily locked by an active workflow", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Rate or queue limit exceeded", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Invalid response from device", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Device or backend unavailable", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update an inventory record", "tags": [ "items" ] } }, "/v1/devices/{device_id}/print/{upca}": { "post": { "description": "Print an item barcode.\n\nPrints an 11- or 12-digit UPCA label through the device. This request does not\ncreate an inventory record and has no command idempotency key; retrying can print\nanother label. A mock device accepts the request without producing a physical label.", "operationId": "print_label_v1_devices__device_id__print__upca__post", "parameters": [ { "in": "path", "name": "device_id", "required": true, "schema": { "pattern": "^[0-9a-f]{8}$", "title": "Device Id", "type": "string" } }, { "in": "path", "name": "upca", "required": true, "schema": { "title": "Upca", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrintLabelResponse" } } }, "description": "Successful Response", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Invalid request", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Authentication failed", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Operation forbidden", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Resource not found", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Request conflicts with current device state", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Request body too large", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Request validation failed", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "423": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Device is temporarily locked by an active workflow", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Rate or queue limit exceeded", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Invalid response from device", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Device or backend unavailable", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Print an item barcode", "tags": [ "items" ] } }, "/v1/devices/{device_id}/status": { "get": { "description": "Read current device activity.\n\nReturns the latest cached device activity, not a command receipt or terminal result.\n`queue_length` counts waiting commands. Use command polling to determine a\nparticular operation's outcome. Returns `503` when no current live status is\navailable.", "operationId": "get_status_v1_devices__device_id__status_get", "parameters": [ { "in": "path", "name": "device_id", "required": true, "schema": { "pattern": "^[0-9a-f]{8}$", "title": "Device Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReducedStatus" } } }, "description": "Successful Response", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Invalid request", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Authentication failed", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Operation forbidden", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Resource not found", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Request conflicts with current device state", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Request body too large", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Request validation failed", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "423": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Device is temporarily locked by an active workflow", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Rate or queue limit exceeded", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Invalid response from device", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Device or backend unavailable", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Read current device activity", "tags": [ "commands" ] } }, "/v1/webhooks": { "get": { "description": "List accessible webhook registrations.\n\nLists registrations belonging to your partner whose entire device set is accessible\nto the current API key. Signing secrets are never included. Use the registration ID\nto delete a receiver.", "operationId": "list_webhooks_v1_webhooks_get", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/WebhookResponse" }, "title": "Response List Webhooks V1 Webhooks Get", "type": "array" } } }, "description": "Successful Response", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Invalid request", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Authentication failed", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Operation forbidden", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Resource not found", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Request conflicts with current device state", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Request body too large", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Request validation failed", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "423": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Device is temporarily locked by an active workflow", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Rate or queue limit exceeded", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Invalid response from device", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Device or backend unavailable", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "List accessible webhook registrations", "tags": [ "webhooks" ] }, "post": { "callbacks": { "webhook_callback_contract": { "{$request.body#/url}": { "post": { "description": "Receive a signed command result.\n\nThis is an outbound callback to your registered URL, not an endpoint hosted by Openshelf.\n\nCompute `sha256=` followed by the hexadecimal HMAC-SHA256 of `timestamp + '.' +\nraw_body`, using the registration secret as the UTF-8 key. The timestamp is the exact\n`X-Opshelf-Timestamp` header value; do not parse and reserialize the JSON before\nverification. Compare signatures in constant time.\n\nDeduplicate using `event_id` before applying business effects. `sequence` orders\ncaptured events for a device; gaps do not imply missing deliveries for your\nsubscription. Return any `2xx` response to acknowledge. A timeout, redirect, or non-2xx\nresponse triggers retry.", "operationId": "webhook_callback_contract__request_body__url__post", "parameters": [ { "description": "sha256=", "in": "header", "name": "X-Opshelf-Signature", "required": true, "schema": { "description": "sha256=", "title": "X-Opshelf-Signature", "type": "string" } }, { "description": "Original event capture timestamp in ISO 8601 format, preserved on retries; use the exact header string for signature verification", "in": "header", "name": "X-Opshelf-Timestamp", "required": true, "schema": { "description": "Original event capture timestamp in ISO 8601 format, preserved on retries; use the exact header string for signature verification", "title": "X-Opshelf-Timestamp", "type": "string" } }, { "description": "Device that produced the event", "in": "header", "name": "X-Opshelf-Device-ID", "required": true, "schema": { "description": "Device that produced the event", "title": "X-Opshelf-Device-Id", "type": "string" } }, { "description": "Stable event ID for deduplicating retries", "in": "header", "name": "X-Opshelf-Event-ID", "required": true, "schema": { "description": "Stable event ID for deduplicating retries", "title": "X-Opshelf-Event-Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEnvelope" } } }, "required": true }, "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Callback receiver rejected the webhook delivery." } }, "summary": "Receive a signed command result" } } } }, "description": "Register a command-result webhook.\n\nRegisters an HTTPS receiver for the selected authorized devices and events. Save the\nreturned `secret` immediately; it is only returned at creation. The URL must use a\nhostname resolving exclusively to public addresses, without credentials or\nfragments. IP-literal URLs and redirects are not supported.\n\nThe callback below describes outbound requests to your receiver. Verify its\nsignature over the original body bytes, deduplicate by `event_id`, and acknowledge\nwith any `2xx` after accepting the event. Delivery is retried up to 12 total\nattempts: the first retry is immediate, then exponential delays from one second,\ncapped at 300 seconds. Delivery is ordered per registration/device; no global\nordering is promised.\n\nRetries preserve the event body and timestamp. Avoid a narrow timestamp window that\nrejects legitimate retries. Event capture depends on a live device stream and is not\nreplayable through this API; use command polling to recover missed outcomes.\nRegistrations apply to future captured events.", "operationId": "create_webhook_v1_webhooks_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreatedResponse" } } }, "description": "Successful Response", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Invalid request", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Authentication failed", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Operation forbidden", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Resource not found", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Request conflicts with current device state", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Request body too large", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Request validation failed", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "423": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Device is temporarily locked by an active workflow", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Rate or queue limit exceeded", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Invalid response from device", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Device or backend unavailable", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Register a command-result webhook", "tags": [ "webhooks" ] } }, "/v1/webhooks/{webhook_id}": { "delete": { "description": "Delete a webhook registration.\n\nRemoves the accessible registration and its pending deliveries. An in-flight HTTP\ndelivery may already have reached the receiver. Returns an empty `204` response; an\nunknown or inaccessible registration returns `404`.", "operationId": "delete_webhook_v1_webhooks__webhook_id__delete", "parameters": [ { "in": "path", "name": "webhook_id", "required": true, "schema": { "title": "Webhook Id", "type": "string" } } ], "responses": { "204": { "description": "Successful Response", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Invalid request", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Authentication failed", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Operation forbidden", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Resource not found", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Request conflicts with current device state", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Request body too large", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Request validation failed", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "423": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Device is temporarily locked by an active workflow", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Rate or queue limit exceeded", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Invalid response from device", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayErrorBody" } } }, "description": "Device or backend unavailable", "headers": { "X-Correlation-ID": { "description": "Request correlation ID; retain when reporting failures.", "schema": { "type": "string" } } } } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete a webhook registration", "tags": [ "webhooks" ] } } }, "servers": [ { "description": "Cloud service origin; production: https://api.opshelf.com", "url": "/" } ], "tags": [ { "description": "Exchange a provisioned API key for a short-lived bearer token.", "name": "authentication" }, { "description": "Check availability of a device assigned to your API key.", "name": "devices" }, { "description": "Inventory records, actionable locations, and barcode printing. Inventory edits do not move hardware.", "name": "items" }, { "description": "Asynchronous store/retrieve admission, durable results, and current activity.", "name": "commands" }, { "description": "Signed terminal command results delivered to your HTTPS receiver. Use polling to recover missed outcomes.", "name": "webhooks" }, { "description": "Public relay process liveness.", "name": "service" } ] }