{ "openapi": "3.1.0", "info": { "title": "WXS Public API", "version": "3.0.0", "description": "Warehouse execution system public API. Authenticate with an API key using the `Authorization: Bearer wxs_pk_...` header." }, "servers": [ { "url": "/api/v3" } ], "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API Key", "description": "API key (wxs_pk_...)" } }, "schemas": { "Wall": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "rows": { "type": "number" }, "cols": { "type": "number" }, "dualSided": { "type": "boolean" }, "sideAName": { "type": "string" }, "sideBName": { "type": "string" }, "binId": { "type": [ "string", "null" ] }, "operationalEnabled": { "type": "boolean" }, "cubbies": { "type": "array", "items": {} }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "rows", "cols", "dualSided", "sideAName", "sideBName", "binId", "operationalEnabled", "cubbies", "createdAt", "updatedAt" ] }, "Error": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "Order": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orderNumber": { "type": "string" }, "clientId": { "type": [ "string", "null" ], "format": "uuid" }, "locationId": { "type": [ "string", "null" ], "format": "uuid" }, "status": { "type": "string", "enum": [ "planned", "pending", "processing", "picking", "packing", "shipped", "delivered", "cancelled" ] }, "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ] }, "customerName": { "type": "string" }, "customerEmail": { "type": [ "string", "null" ] }, "totalItems": { "type": "number" }, "pickedItems": { "type": "number" }, "lineCount": { "type": "number" }, "waveId": { "type": [ "string", "null" ], "format": "uuid" }, "containerId": { "type": [ "string", "null" ], "format": "uuid" }, "orderDate": { "type": [ "string", "null" ] }, "shipBy": { "type": [ "string", "null" ] }, "releaseAt": { "type": [ "string", "null" ] }, "carrier": { "type": [ "string", "null" ] }, "service": { "type": [ "string", "null" ] }, "externalRef": { "type": [ "string", "null" ] }, "skipWave": { "type": "boolean" }, "prioritySwapCount": { "type": "number" }, "notes": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "shippedAt": { "type": [ "string", "null" ] } }, "required": [ "id", "orderNumber", "clientId", "locationId", "status", "priority", "customerName", "customerEmail", "totalItems", "pickedItems", "lineCount", "waveId", "containerId", "orderDate", "shipBy", "releaseAt", "carrier", "service", "externalRef", "skipWave", "prioritySwapCount", "notes", "createdAt", "updatedAt", "shippedAt" ] }, "OrderError": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "OrderBatchResult": { "type": "object", "properties": { "created": { "type": "number" }, "updated": { "type": "number" }, "failed": { "type": "number" }, "results": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "number" }, "orderNumber": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "created", "updated", "error" ] }, "id": { "type": [ "string", "null" ], "format": "uuid" }, "ignoredFields": { "type": "array", "items": { "type": "string" } }, "error": { "type": [ "string", "null" ] } }, "required": [ "index", "orderNumber", "status", "id", "ignoredFields", "error" ] } } }, "required": [ "created", "updated", "failed", "results" ] }, "OrderLine": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orderId": { "type": "string", "format": "uuid" }, "lineNo": { "type": "number" }, "sku": { "type": "string" }, "productId": { "type": [ "string", "null" ], "format": "uuid" }, "productName": { "type": [ "string", "null" ] }, "qty": { "type": "number" }, "pickedQty": { "type": "number" } }, "required": [ "id", "orderId", "lineNo", "sku", "productId", "productName", "qty", "pickedQty" ] }, "Product": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "clientId": { "type": [ "string", "null" ], "format": "uuid", "description": "Owning 3PL client id; null = house-owned." }, "sku": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "category": { "type": [ "string", "null" ] }, "weight": { "type": [ "string", "null" ] }, "length": { "type": [ "string", "null" ] }, "width": { "type": [ "string", "null" ] }, "height": { "type": [ "string", "null" ] }, "imageUrl": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "customFields": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Custom field values keyed by field name. Every defined product field is present; null when unset." } }, "required": [ "id", "clientId", "sku", "name", "description", "category", "weight", "length", "width", "height", "imageUrl", "createdAt", "updatedAt", "customFields" ] }, "InventoryError": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "Client": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "contactName": { "type": [ "string", "null" ] }, "contactEmail": { "type": [ "string", "null" ] }, "contactPhone": { "type": [ "string", "null" ] }, "billingEmail": { "type": [ "string", "null" ] }, "currency": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "code", "name", "contactName", "contactEmail", "contactPhone", "billingEmail", "currency", "address", "notes", "isActive", "createdAt", "updatedAt" ] }, "ClientError": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "Asn": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "asnNumber": { "type": "string" }, "clientId": { "type": [ "string", "null" ], "format": "uuid" }, "poId": { "type": [ "string", "null" ], "format": "uuid" }, "status": { "type": "string" }, "carrier": { "type": [ "string", "null" ] }, "trackingNumber": { "type": [ "string", "null" ] }, "expectedArrival": { "type": [ "string", "null" ] }, "arrivedAt": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "asnNumber", "clientId", "poId", "status", "carrier", "trackingNumber", "expectedArrival", "arrivedAt", "notes", "createdAt", "updatedAt" ] }, "AsnWithLines": { "allOf": [ { "$ref": "#/components/schemas/Asn" }, { "type": "object", "properties": { "lines": { "type": "array", "items": { "$ref": "#/components/schemas/AsnLine" } } }, "required": [ "lines" ] } ] }, "AsnLine": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "lineNumber": { "type": "number" }, "productId": { "type": [ "string", "null" ], "format": "uuid" }, "sku": { "type": "string" }, "expectedQty": { "type": "number" }, "receivedQty": { "type": "number" }, "lotNumber": { "type": [ "string", "null" ] }, "expirationDate": { "type": [ "string", "null" ] } }, "required": [ "id", "lineNumber", "productId", "sku", "expectedQty", "receivedQty", "lotNumber", "expirationDate" ] }, "AsnError": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "PurchaseOrder": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "poNumber": { "type": "string" }, "clientId": { "type": [ "string", "null" ], "format": "uuid" }, "status": { "type": "string" }, "supplierName": { "type": [ "string", "null" ] }, "supplierRef": { "type": [ "string", "null" ] }, "expectedDate": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "closedAt": { "type": [ "string", "null" ] } }, "required": [ "id", "poNumber", "clientId", "status", "supplierName", "supplierRef", "expectedDate", "notes", "createdAt", "updatedAt", "closedAt" ] }, "PurchaseOrderWithLines": { "allOf": [ { "$ref": "#/components/schemas/PurchaseOrder" }, { "type": "object", "properties": { "lines": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseOrderLine" } } }, "required": [ "lines" ] } ] }, "PurchaseOrderLine": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "lineNumber": { "type": "number" }, "productId": { "type": [ "string", "null" ], "format": "uuid" }, "sku": { "type": "string" }, "orderedQty": { "type": "number" }, "receivedQty": { "type": "number" }, "unitOfMeasure": { "type": "string" } }, "required": [ "id", "lineNumber", "productId", "sku", "orderedQty", "receivedQty", "unitOfMeasure" ] }, "PoError": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "Invoice": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "clientId": { "type": "string", "format": "uuid" }, "invoiceNumber": { "type": [ "string", "null" ] }, "periodKey": { "type": "string" }, "periodStart": { "type": "string" }, "periodEnd": { "type": "string" }, "status": { "type": "string" }, "currency": { "type": "string" }, "subtotal": { "type": "string" }, "total": { "type": "string" }, "finalizedAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" } }, "required": [ "id", "clientId", "invoiceNumber", "periodKey", "periodStart", "periodEnd", "status", "currency", "subtotal", "total", "finalizedAt", "createdAt" ] }, "InvoiceWithLines": { "allOf": [ { "$ref": "#/components/schemas/Invoice" }, { "type": "object", "properties": { "lines": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceLine" } } }, "required": [ "lines" ] } ] }, "InvoiceLine": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "chargeType": { "type": "string" }, "description": { "type": "string" }, "quantity": { "type": "string" }, "unitLabel": { "type": "string" }, "unitRate": { "type": "string" }, "amount": { "type": "string" }, "sortOrder": { "type": "number" } }, "required": [ "id", "chargeType", "description", "quantity", "unitLabel", "unitRate", "amount", "sortOrder" ] }, "InvoiceError": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "Zone": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "code": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "locationId": { "type": "string", "format": "uuid" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "code", "description", "locationId", "createdAt", "updatedAt" ] }, "ZoneError": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "Container": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "barcode": { "type": "string" }, "type": { "type": "string", "enum": [ "tote", "pallet", "carton", "bin", "shelf" ] }, "status": { "type": "string", "enum": [ "available", "in_use", "in_transit", "maintenance", "retired" ] }, "binId": { "type": [ "string", "null" ], "format": "uuid" }, "zoneId": { "type": [ "string", "null" ], "format": "uuid" }, "notes": { "type": [ "string", "null" ] }, "currentConveyorId": { "type": [ "string", "null" ], "format": "uuid" }, "currentPathId": { "type": [ "string", "null" ] }, "currentDistance": { "type": [ "number", "null" ] }, "lastScanPointId": { "type": [ "string", "null" ], "format": "uuid" }, "lastSeenAt": { "type": [ "string", "null" ] }, "simulationStatus": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "customFields": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Custom field values keyed by field name. Every defined container field is present; null when unset." } }, "required": [ "id", "barcode", "type", "status", "binId", "zoneId", "notes", "currentConveyorId", "currentPathId", "currentDistance", "lastScanPointId", "lastSeenAt", "simulationStatus", "createdAt", "updatedAt", "customFields" ] }, "ContainerError": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "Wave": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "build", "queued", "ready", "active", "closed" ] }, "origin": { "type": "string", "enum": [ "system", "user" ] }, "orderCount": { "type": "number" }, "totalItems": { "type": "number" }, "pickedItems": { "type": "number" }, "putItems": { "type": "number" }, "createdById": { "type": [ "string", "null" ], "format": "uuid" }, "closedAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "status", "origin", "orderCount", "totalItems", "pickedItems", "putItems", "createdById", "closedAt", "createdAt", "updatedAt" ] }, "WaveError": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "WavePlan": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "locationId": { "type": "string", "format": "uuid" }, "planDate": { "type": "string" }, "horizonStart": { "type": "string" }, "horizonEnd": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "committed", "superseded" ] }, "source": { "type": "string", "enum": [ "manual", "scheduled", "api" ] }, "assumptions": { "type": "object", "additionalProperties": {} }, "summary": { "type": "object", "additionalProperties": {} }, "diagnostics": { "type": "object", "additionalProperties": {} }, "accuracy": { "type": [ "object", "null" ], "additionalProperties": {} }, "committedAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "locationId", "planDate", "horizonStart", "horizonEnd", "status", "source", "assumptions", "summary", "diagnostics", "accuracy", "committedAt", "createdAt", "updatedAt" ] }, "WavePlanWave": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sequence": { "type": "number" }, "proposedName": { "type": "string" }, "zoneId": { "type": [ "string", "null" ], "format": "uuid" }, "groupKey": { "type": "string" }, "orderIds": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "orderCount": { "type": "number" }, "lineCount": { "type": "number" }, "unitCount": { "type": "number" }, "estimatedMinutes": { "type": "number" }, "scheduledStart": { "type": [ "string", "null" ] }, "scheduledEnd": { "type": [ "string", "null" ] }, "laborByZone": { "type": "object", "additionalProperties": { "type": "number" } }, "committedWaveId": { "type": [ "string", "null" ], "format": "uuid" } }, "required": [ "id", "sequence", "proposedName", "zoneId", "groupKey", "orderIds", "orderCount", "lineCount", "unitCount", "estimatedMinutes", "scheduledStart", "scheduledEnd", "laborByZone", "committedWaveId" ] }, "WavePlanError": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "Webhook": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "url": { "type": "string" }, "secret": { "type": "string" }, "events": {}, "headers": {}, "enabled": { "type": "boolean" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "url", "secret", "enabled", "createdAt", "updatedAt" ] }, "Location": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "code": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "code", "description", "isActive", "createdAt", "updatedAt" ] }, "LocationError": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "Bin": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "zoneId": { "type": [ "string", "null" ], "format": "uuid" }, "aisle": { "type": [ "string", "null" ] }, "rack": { "type": [ "string", "null" ] }, "level": { "type": [ "string", "null" ] }, "position": { "type": [ "string", "null" ] }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "code", "name", "zoneId", "aisle", "rack", "level", "position", "isActive", "createdAt", "updatedAt" ] }, "InductArrival": { "type": "object", "properties": { "container": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "barcode": { "type": "string" }, "type": { "type": "string", "enum": [ "tote", "pallet", "carton", "bin", "shelf" ] }, "status": { "type": "string", "enum": [ "available", "in_use", "in_transit", "maintenance", "retired" ] }, "currentConveyorId": { "type": [ "string", "null" ], "format": "uuid" }, "currentPathId": { "type": [ "string", "null" ] }, "currentDistance": { "type": [ "number", "null" ] }, "lastSeenAt": { "type": [ "string", "null" ] } }, "required": [ "id", "barcode", "type", "status", "currentConveyorId", "currentPathId", "currentDistance", "lastSeenAt" ] }, "induct": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "conveyorId": { "type": "string", "format": "uuid" } }, "required": [ "id", "conveyorId" ] } }, "required": [ "container", "induct" ] }, "InductError": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "InductArrivalBody": { "type": "object", "properties": { "barcode": { "type": "string", "minLength": 1, "example": "TOTE-000123" }, "type": { "type": "string", "enum": [ "tote", "pallet", "carton", "bin", "shelf" ] }, "notes": { "type": "string" } }, "required": [ "barcode" ] }, "CustomFieldValue": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "fieldId": { "type": "string", "format": "uuid" }, "entityType": { "type": "string", "enum": [ "product", "container" ] }, "entityId": { "type": "string", "format": "uuid" }, "value": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "fieldId", "entityType", "entityId", "value", "createdAt", "updatedAt" ] }, "CustomFieldValueError": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "SortationSingleResult": { "type": "object", "properties": { "lanes": { "type": "array", "items": { "type": "number" } }, "laneName": { "type": "string" }, "matchedCriteriaName": { "type": "string" }, "reason": { "type": "string" }, "meta": { "$ref": "#/components/schemas/SortationMeta" } }, "required": [ "lanes", "laneName", "matchedCriteriaName", "reason", "meta" ] }, "SortationMeta": { "type": "object", "properties": { "requestId": { "type": "string" }, "endpoint": { "type": "string" }, "sorter": { "type": [ "string", "null" ] }, "code": { "type": "string" }, "mode": { "type": [ "string", "null" ] }, "durationMs": { "type": "number" }, "path": { "type": "array", "items": { "type": "object", "additionalProperties": {} } } }, "required": [ "requestId", "endpoint", "sorter", "mode", "durationMs" ] }, "SortationMultiResult": { "type": "object", "properties": { "lanes": { "type": "array", "items": { "type": "number" } }, "laneNames": { "type": "array", "items": { "type": "string" } }, "matchedCriteriaNames": { "type": "array", "items": { "type": "string" } }, "reason": { "type": "string" }, "meta": { "$ref": "#/components/schemas/SortationMeta" } }, "required": [ "lanes", "laneNames", "matchedCriteriaNames", "reason", "meta" ] }, "SortationLanesList": { "type": "object", "properties": { "lanes": { "type": "array", "items": { "type": "number" } }, "meta": { "$ref": "#/components/schemas/SortationMeta" } }, "required": [ "lanes", "meta" ] }, "SortationLaneStatus": { "type": "object", "properties": { "lanes": { "type": "array", "items": { "type": "object", "properties": { "number": { "type": "number" }, "enabled": { "type": "boolean" }, "available": { "type": "boolean" } }, "required": [ "number", "enabled", "available" ] } }, "meta": { "$ref": "#/components/schemas/SortationMeta" } }, "required": [ "lanes", "meta" ] }, "SortationMode": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "STANDARD", "FILL_FIRST", "ROUND_ROBIN" ] }, "number_of_sorts": { "type": [ "number", "null" ] }, "meta": { "$ref": "#/components/schemas/SortationMeta" } }, "required": [ "mode", "number_of_sorts", "meta" ] }, "RateShopResult": { "type": "object", "properties": { "strategy": { "type": "string", "enum": [ "cheapest", "fastest", "best_value" ] }, "best": { "$ref": "#/components/schemas/RateQuote" }, "quotes": { "type": "array", "items": { "$ref": "#/components/schemas/RateQuote" } }, "constraintMet": { "type": "boolean" }, "failures": { "type": "array", "items": { "type": "object", "properties": { "accountId": { "type": "string" }, "accountName": { "type": "string" }, "carrier": { "type": "string", "enum": [ "ups", "fedex", "usps", "dhl_express", "amazon_shipping" ] }, "mode": { "type": "string", "enum": [ "emulated", "sandbox", "live" ] }, "error": { "type": "string" } }, "required": [ "accountId", "accountName", "carrier", "mode", "error" ] } }, "meta": { "$ref": "#/components/schemas/RatesMeta" } }, "required": [ "strategy", "best", "quotes", "constraintMet", "failures", "meta" ] }, "RateQuote": { "type": [ "object", "null" ], "properties": { "accountId": { "type": "string" }, "accountName": { "type": "string" }, "carrier": { "type": "string", "enum": [ "ups", "fedex", "usps", "dhl_express", "amazon_shipping" ] }, "mode": { "type": "string", "enum": [ "emulated", "sandbox", "live" ] }, "serviceCode": { "type": "string" }, "serviceName": { "type": "string" }, "rateType": { "type": "string", "enum": [ "account", "list" ] }, "currency": { "type": "string" }, "totalCharge": { "type": "number" }, "customerPrice": { "type": "number" }, "billableWeight": { "type": "object", "properties": { "value": { "type": "number" }, "unit": { "type": "string", "enum": [ "lb", "kg" ] } }, "required": [ "value", "unit" ] }, "transitDays": { "type": "number" }, "estimatedDeliveryAt": { "type": "string" }, "guaranteed": { "type": "boolean" }, "purchaseRef": { "type": "object", "properties": { "requestToken": { "type": "string" }, "rateId": { "type": "string" } }, "required": [ "requestToken", "rateId" ] } }, "required": [ "accountId", "accountName", "carrier", "mode", "serviceCode", "serviceName", "rateType", "currency", "totalCharge", "customerPrice", "guaranteed" ] }, "RatesMeta": { "type": "object", "properties": { "requestId": { "type": "string" }, "durationMs": { "type": "number" } }, "required": [ "requestId", "durationMs" ] }, "RateShopRequest": { "type": "object", "properties": { "shipment": { "type": "object", "properties": { "shipFrom": { "type": "object", "properties": { "countryCode": { "type": "string", "minLength": 2, "maxLength": 2 }, "postalCode": { "type": "string", "minLength": 1 }, "city": { "type": "string" }, "stateOrProvinceCode": { "type": "string" }, "residential": { "type": "boolean" } }, "required": [ "countryCode", "postalCode" ] }, "shipTo": { "type": "object", "properties": { "countryCode": { "type": "string", "minLength": 2, "maxLength": 2 }, "postalCode": { "type": "string", "minLength": 1 }, "city": { "type": "string" }, "stateOrProvinceCode": { "type": "string" }, "residential": { "type": "boolean" } }, "required": [ "countryCode", "postalCode" ] }, "packages": { "type": "array", "items": { "type": "object", "properties": { "weight": { "type": "number", "exclusiveMinimum": 0 }, "length": { "type": "number", "exclusiveMinimum": 0 }, "width": { "type": "number", "exclusiveMinimum": 0 }, "height": { "type": "number", "exclusiveMinimum": 0 } }, "required": [ "weight" ] }, "minItems": 1, "maxItems": 200 }, "shipDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "units": { "type": "string", "enum": [ "imperial", "metric" ] } }, "required": [ "shipFrom", "shipTo", "packages" ] }, "options": { "type": "object", "properties": { "strategy": { "type": "string", "enum": [ "cheapest", "fastest", "best_value" ] }, "deliverBy": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "maxTransitDays": { "type": "integer", "exclusiveMinimum": 0 }, "guaranteedOnly": { "type": "boolean" }, "carriers": { "type": "array", "items": { "type": "string", "enum": [ "ups", "fedex", "usps", "dhl_express", "amazon_shipping" ] } } } } }, "required": [ "shipment" ] }, "CarrierAccountSummary": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "carrier": { "type": "string", "enum": [ "ups", "fedex", "usps", "dhl_express", "amazon_shipping" ] }, "carrierLabel": { "type": "string" }, "mode": { "type": "string", "enum": [ "emulated", "sandbox", "live" ] }, "enabled": { "type": "boolean" }, "services": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" } }, "required": [ "code", "name" ] } } }, "required": [ "id", "name", "carrier", "carrierLabel", "mode", "enabled", "services" ] }, "IngestionAccepted": { "type": "object", "properties": { "accepted": { "type": "boolean", "enum": [ true ] }, "type": { "type": "string" } }, "required": [ "accepted", "type" ] }, "IngestionError": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "IngestionEventInput": { "type": "object", "properties": { "type": { "type": "string", "example": "scan", "description": "Event type — see GET /events/types." }, "data": { "type": "object", "additionalProperties": {}, "default": {}, "description": "Type-specific payload, validated against the event's schema." } }, "required": [ "type" ] }, "IngestionBatchResult": { "type": "object", "properties": { "accepted": { "type": "number" }, "rejected": { "type": "number" }, "results": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "number" }, "type": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "accepted", "rejected" ] }, "error": { "type": [ "string", "null" ] } }, "required": [ "index", "type", "status", "error" ] } } }, "required": [ "accepted", "rejected", "results" ] }, "IngestionBatchInput": { "type": "object", "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/IngestionEventInput" }, "minItems": 1, "maxItems": 1000 } }, "required": [ "events" ] }, "ExportDataset": { "type": "object", "properties": { "name": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" }, "source": { "type": "string", "enum": [ "postgres", "clickhouse" ] }, "group": { "type": "string", "enum": [ "warehouse", "activity" ] }, "permission": { "type": "string" }, "timeColumn": { "type": [ "string", "null" ] } }, "required": [ "name", "label", "description", "source", "group", "permission", "timeColumn" ] }, "ExportColumn": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" }, "nullable": { "type": "boolean" }, "enumValues": { "type": "array", "items": { "type": "string" } } }, "required": [ "name", "type", "nullable" ] }, "ExportRequest": { "type": "object", "properties": { "where": { "type": "object", "additionalProperties": {} }, "columns": { "type": "array", "items": { "type": "string" } }, "orderBy": { "type": "array", "items": { "type": "object", "properties": { "column": { "type": "string" }, "direction": { "type": "string", "enum": [ "asc", "desc" ] } }, "required": [ "column" ] } }, "since": { "type": "string", "format": "date-time" }, "until": { "type": "string", "format": "date-time" }, "limit": { "type": "integer", "minimum": 1, "maximum": 10000 }, "offset": { "type": "integer", "minimum": 0 }, "format": { "type": "string", "enum": [ "json", "ndjson", "csv", "xlsx" ] }, "groupBy": { "type": "string" }, "aggregate": { "type": "string", "enum": [ "count", "sum", "avg", "min", "max" ] }, "aggregateField": { "type": "string" }, "timezone": { "type": "string", "enum": [ "site", "utc" ] }, "filename": { "type": "string" } }, "example": { "where": { "status": "shipped", "lineCount": 1 }, "columns": [ "orderNumber", "status", "carrier", "createdAt" ], "orderBy": [ { "column": "createdAt", "direction": "desc" } ], "since": "2026-09-01T00:00:00Z", "limit": 1000, "format": "csv" } }, "PrintResult": { "type": "object", "properties": { "printed": { "type": "boolean" }, "pandaId": { "type": "string" }, "pandaName": { "type": [ "string", "null" ] } }, "required": [ "printed", "pandaId", "pandaName" ] }, "PrintErrorBody": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "PrintRequest": { "type": "object", "properties": { "groupId": { "type": "string", "format": "uuid", "description": "Printer group ID. Group mode picks the printer." }, "groupName": { "type": "string", "minLength": 1, "description": "Printer group name (alternative to groupId)." }, "pandaId": { "type": "string", "format": "uuid", "description": "Send directly to one printer (no group logic)." }, "zpl": { "type": "string", "minLength": 1, "description": "Raw ZPL to print." } }, "required": [ "zpl" ], "description": "Exactly one of `groupId`, `groupName`, or `pandaId` must be provided." } }, "parameters": {} }, "paths": { "/auth/token": { "post": { "tags": [ "Auth" ], "summary": "Exchange a workload identity token for an access token", "description": "Workload identity federation. Send the JWT your identity provider (Okta, Entra ID, GitHub Actions, a cloud workload identity pool, …) issued to your workload; if a trusted identity provider configured under Configuration → API Access matches its issuer and audience and its subject/claims pass that provider's rules, you receive a short-lived `wxs_ft_…` bearer token carrying that provider's permissions. Use it like an API key until it expires, then exchange a new JWT. Nothing secret needs to be stored on your side.", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "grant_type": { "type": "string", "enum": [ "urn:ietf:params:oauth:grant-type:token-exchange" ] }, "subject_token": { "type": "string", "description": "The identity provider's JWT" }, "subject_token_type": { "type": "string", "enum": [ "urn:ietf:params:oauth:token-type:jwt" ] }, "scope": { "type": "string", "description": "Space-separated permission names to narrow the token to", "example": "orders:ListOrders data_ops:ListDatasets" } }, "required": [ "grant_type", "subject_token" ] } }, "application/json": { "schema": { "type": "object", "properties": { "grant_type": { "type": "string", "enum": [ "urn:ietf:params:oauth:grant-type:token-exchange" ] }, "subject_token": { "type": "string" }, "subject_token_type": { "type": "string", "enum": [ "urn:ietf:params:oauth:token-type:jwt" ] }, "scope": { "type": "string" } }, "required": [ "grant_type", "subject_token" ] } } } }, "responses": { "200": { "description": "A short-lived access token", "content": { "application/json": { "schema": { "type": "object", "properties": { "access_token": { "type": "string" }, "issued_token_type": { "type": "string" }, "token_type": { "type": "string", "enum": [ "Bearer" ] }, "expires_in": { "type": "number" }, "scope": { "type": "string" } }, "required": [ "access_token", "issued_token_type", "token_type", "expires_in", "scope" ] } } } }, "400": { "description": "Malformed request" }, "401": { "description": "Token not accepted by any trusted identity provider" } } } }, "/walls": { "get": { "tags": [ "Walls" ], "summary": "List all walls", "responses": { "200": { "description": "List of walls", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Wall" } } }, "required": [ "data" ] } } } } } }, "post": { "tags": [ "Walls" ], "summary": "Create a wall", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "rows": { "type": "number" }, "cols": { "type": "number" }, "dualSided": { "type": "boolean" }, "sideAName": { "type": "string" }, "sideBName": { "type": "string" }, "binId": { "type": [ "string", "null" ] }, "operationalEnabled": { "type": "boolean" }, "operationalConfig": { "type": "object", "properties": { "controlsEnabled": { "type": "boolean", "default": false }, "buttons": { "type": "array", "items": { "type": "string", "enum": [ "long", "short", "ack", "resend", "clear" ] }, "default": [ "long", "short", "ack", "resend", "clear" ] }, "plusResetsQty": { "type": "boolean", "default": false }, "skuCompleteEnabled": { "type": "boolean", "default": false }, "wallCompleteEnabled": { "type": "boolean", "default": true } } }, "cubbies": { "type": "array", "items": {} } }, "required": [ "name", "rows", "cols", "dualSided", "sideAName", "sideBName", "binId", "cubbies" ] } } } }, "responses": { "201": { "description": "Created wall", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Wall" } } } } } } }, "/walls/{id}": { "get": { "tags": [ "Walls" ], "summary": "Get a wall by ID", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Wall details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Wall" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Walls" ], "summary": "Update a wall", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "rows": { "type": "number" }, "cols": { "type": "number" }, "dualSided": { "type": "boolean" }, "sideAName": { "type": "string" }, "sideBName": { "type": "string" }, "binId": { "type": [ "string", "null" ] }, "operationalEnabled": { "type": "boolean" }, "operationalConfig": { "type": "object", "properties": { "controlsEnabled": { "type": "boolean", "default": false }, "buttons": { "type": "array", "items": { "type": "string", "enum": [ "long", "short", "ack", "resend", "clear" ] }, "default": [ "long", "short", "ack", "resend", "clear" ] }, "plusResetsQty": { "type": "boolean", "default": false }, "skuCompleteEnabled": { "type": "boolean", "default": false }, "wallCompleteEnabled": { "type": "boolean", "default": true } } }, "cubbies": { "type": "array", "items": {} } } } } } }, "responses": { "200": { "description": "Updated wall", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Wall" } } } } } }, "delete": { "tags": [ "Walls" ], "summary": "Delete a wall", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean" } }, "required": [ "id", "deleted" ] } } } } } } }, "/orders": { "get": { "tags": [ "Orders" ], "summary": "List orders", "parameters": [ { "schema": { "type": [ "number", "null" ], "default": 1 }, "required": false, "name": "page", "in": "query" }, { "schema": { "type": [ "number", "null" ], "default": 25 }, "required": false, "name": "pageSize", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "status", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "search", "in": "query" } ], "responses": { "200": { "description": "Paginated list of orders", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } }, "total": { "type": "number" }, "page": { "type": "number" }, "pageSize": { "type": "number" }, "totalPages": { "type": "number" } }, "required": [ "data", "total", "page", "pageSize", "totalPages" ] } } } } } }, "post": { "tags": [ "Orders" ], "summary": "Create an order", "description": "Creates one order with its lines. Client and location are referenced by code. `status` is `planned` for orders that are known but not yet actionable (tomorrow's work), `pending` for orders to wave now. Lines are the SKUs on the order; when present they set the unit and line counts. Fails if the order number already exists; use POST /orders/batch for idempotent re-sends. Wave business rules run on every API create and may override status or priority or mark the order to skip automatic waving.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "orderNumber": { "type": "string", "minLength": 1 }, "clientId": { "type": [ "string", "null" ], "format": "uuid" }, "clientCode": { "type": "string", "minLength": 1 }, "locationId": { "type": [ "string", "null" ], "format": "uuid" }, "locationCode": { "type": "string", "minLength": 1 }, "customerName": { "type": "string", "default": "" }, "customerEmail": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "planned", "pending" ] }, "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ] }, "orderDate": { "type": [ "string", "null" ] }, "shipBy": { "type": [ "string", "null" ] }, "releaseAt": { "type": [ "string", "null" ] }, "carrier": { "type": [ "string", "null" ] }, "service": { "type": [ "string", "null" ] }, "externalRef": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "lineNo": { "type": "integer", "minimum": 1 }, "sku": { "type": "string", "minLength": 1 }, "qty": { "type": "integer", "minimum": 1, "default": 1 } }, "required": [ "sku" ] }, "default": [] }, "totalItems": { "type": "integer", "minimum": 0 } }, "required": [ "orderNumber" ] } } } }, "responses": { "201": { "description": "Created order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "400": { "description": "Invalid order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderError" } } } } } } }, "/orders/batch": { "post": { "tags": [ "Orders" ], "summary": "Upsert a batch of orders", "description": "Creates or updates up to 1000 orders keyed on order number, one transaction each, so a bad record never rolls back the good ones. This is the endpoint for an ERP that re-sends: while an order is still unwaved and planned/pending the whole record (lines included) is replaced; once it is in work only priority, notes and shipBy are applied and the rest is reported in `ignoredFields`. Always 200 when the batch is well-formed; per-record outcomes are in `results`.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "orders": { "type": "array", "items": { "type": "object", "properties": { "orderNumber": { "type": "string", "minLength": 1 }, "clientId": { "type": [ "string", "null" ], "format": "uuid" }, "clientCode": { "type": "string", "minLength": 1 }, "locationId": { "type": [ "string", "null" ], "format": "uuid" }, "locationCode": { "type": "string", "minLength": 1 }, "customerName": { "type": "string", "default": "" }, "customerEmail": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "planned", "pending" ] }, "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ] }, "orderDate": { "type": [ "string", "null" ] }, "shipBy": { "type": [ "string", "null" ] }, "releaseAt": { "type": [ "string", "null" ] }, "carrier": { "type": [ "string", "null" ] }, "service": { "type": [ "string", "null" ] }, "externalRef": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "lineNo": { "type": "integer", "minimum": 1 }, "sku": { "type": "string", "minLength": 1 }, "qty": { "type": "integer", "minimum": 1, "default": 1 } }, "required": [ "sku" ] }, "default": [] }, "totalItems": { "type": "integer", "minimum": 0 } }, "required": [ "orderNumber" ] }, "minItems": 1, "maxItems": 1000 } }, "required": [ "orders" ] } } } }, "responses": { "200": { "description": "Per-order result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderBatchResult" } } } } } } }, "/orders/release": { "post": { "tags": [ "Orders" ], "summary": "Release planned orders", "description": "Moves planned orders to pending so they become eligible for waving. Pass `ids`, or `due: true` for every order whose releaseAt has passed, or `shipDay` (YYYY-MM-DD, site timezone) for every planned order shipping that day.", "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 5000 } }, "required": [ "ids" ] }, { "type": "object", "properties": { "due": { "type": "boolean", "enum": [ true ] } }, "required": [ "due" ] }, { "type": "object", "properties": { "shipDay": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "locationId": { "type": "string", "format": "uuid" } }, "required": [ "shipDay" ] } ] } } } }, "responses": { "200": { "description": "Released orders", "content": { "application/json": { "schema": { "type": "object", "properties": { "released": { "type": "number" }, "ids": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, "required": [ "released", "ids" ] } } } } } } }, "/orders/{id}": { "get": { "tags": [ "Orders" ], "summary": "Get an order by ID", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Order details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderError" } } } } } }, "patch": { "tags": [ "Orders" ], "summary": "Update an order", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "waveId": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "planned", "pending", "processing", "picking", "packing", "shipped", "delivered", "cancelled" ] }, "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ] }, "shippedAt": { "type": "string" }, "shipBy": { "type": [ "string", "null" ] }, "releaseAt": { "type": [ "string", "null" ] }, "carrier": { "type": [ "string", "null" ] }, "service": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "customerName": { "type": "string" }, "customerEmail": { "type": [ "string", "null" ] }, "locationId": { "type": [ "string", "null" ], "format": "uuid" } } } } } }, "responses": { "200": { "description": "Updated order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } } } } }, "/orders/{id}/lines": { "get": { "tags": [ "Orders" ], "summary": "List an order's lines", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Order lines in line-number order", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OrderLine" } } }, "required": [ "data" ] } } } } } } }, "/products": { "get": { "tags": [ "Inventory" ], "summary": "List all products", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Filter to one 3PL client's catalog." }, "required": false, "description": "Filter to one 3PL client's catalog.", "name": "clientId", "in": "query" } ], "responses": { "200": { "description": "List of products", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } } }, "required": [ "data" ] } } } } } }, "post": { "tags": [ "Inventory" ], "summary": "Upsert a product by SKU", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "sku": { "type": "string" }, "clientId": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "category": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "weight": { "type": [ "string", "null" ] }, "length": { "type": [ "string", "null" ] }, "width": { "type": [ "string", "null" ] }, "height": { "type": [ "string", "null" ] }, "imageUrl": { "type": [ "string", "null" ] } }, "required": [ "sku", "name" ] } } } }, "responses": { "200": { "description": "Upserted product", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } } } } } }, "/products/{id}": { "get": { "tags": [ "Inventory" ], "summary": "Get a product by ID", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Product details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryError" } } } } } }, "delete": { "tags": [ "Inventory" ], "summary": "Delete a product", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean" } }, "required": [ "id", "deleted" ] } } } } } } }, "/clients": { "get": { "tags": [ "Clients" ], "summary": "List all 3PL clients", "responses": { "200": { "description": "List of clients", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Client" } } }, "required": [ "data" ] } } } } } }, "post": { "tags": [ "Clients" ], "summary": "Upsert a client by code", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "contactName": { "type": [ "string", "null" ] }, "contactEmail": { "type": [ "string", "null" ] }, "contactPhone": { "type": [ "string", "null" ] }, "billingEmail": { "type": [ "string", "null" ] }, "currency": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "isActive": { "type": "boolean", "default": true } }, "required": [ "code", "name" ] } } } }, "responses": { "200": { "description": "Upserted client", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Client" } } } } } } }, "/clients/{id}": { "get": { "tags": [ "Clients" ], "summary": "Get a client by ID", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Client details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Client" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } }, "delete": { "tags": [ "Clients" ], "summary": "Delete a client", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean" } }, "required": [ "id", "deleted" ] } } } }, "409": { "description": "Client still referenced by products or orders", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } } } }, "/asns": { "get": { "tags": [ "Inbound" ], "summary": "List ASNs", "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "status", "in": "query" } ], "responses": { "200": { "description": "List of ASNs", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Asn" } } }, "required": [ "data" ] } } } } } }, "post": { "tags": [ "Inbound" ], "summary": "Create an ASN with lines", "description": "Lines reference products by SKU within the client's catalog (clientId omitted = house catalog). Unknown SKUs are rejected with 422.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "asnNumber": { "type": "string", "minLength": 1 }, "clientId": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "expected", "in_transit", "arrived", "receiving", "received", "closed", "cancelled" ] }, "carrier": { "type": [ "string", "null" ] }, "trackingNumber": { "type": [ "string", "null" ] }, "expectedArrival": { "type": [ "string", "null" ], "format": "date-time" }, "notes": { "type": [ "string", "null" ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": [ "string", "null" ] }, "sku": { "type": "string", "minLength": 1 }, "expectedQty": { "type": "integer", "exclusiveMinimum": 0 }, "lotNumber": { "type": [ "string", "null" ] }, "expirationDate": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "sku", "expectedQty" ] } }, "poNumber": { "type": "string", "description": "Reference an existing PO by number instead of id." } }, "required": [ "asnNumber" ] } } } }, "responses": { "201": { "description": "Created ASN", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsnWithLines" } } } }, "422": { "description": "Unknown SKU or PO number", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsnError" } } } } } } }, "/asns/{id}": { "get": { "tags": [ "Inbound" ], "summary": "Get an ASN with its lines", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "ASN details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsnWithLines" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsnError" } } } } } }, "patch": { "tags": [ "Inbound" ], "summary": "Update an ASN (header fields or status)", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "asnNumber": { "type": "string", "minLength": 1 }, "clientId": { "type": [ "string", "null" ] }, "poId": { "type": [ "string", "null" ] }, "carrier": { "type": [ "string", "null" ] }, "trackingNumber": { "type": [ "string", "null" ] }, "expectedArrival": { "type": [ "string", "null" ], "format": "date-time" }, "notes": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "expected", "in_transit", "arrived", "receiving", "received", "closed", "cancelled" ] } } } } } }, "responses": { "200": { "description": "Updated ASN", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Asn" } } } }, "422": { "description": "Invalid update", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsnError" } } } } } }, "delete": { "tags": [ "Inbound" ], "summary": "Cancel an ASN", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Cancelled", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "cancelled": { "type": "boolean" } }, "required": [ "id", "cancelled" ] } } } }, "422": { "description": "Cannot cancel", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsnError" } } } } } } }, "/purchase-orders": { "get": { "tags": [ "Inbound" ], "summary": "List purchase orders", "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "status", "in": "query" } ], "responses": { "200": { "description": "List of purchase orders", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseOrder" } } }, "required": [ "data" ] } } } } } }, "post": { "tags": [ "Inbound" ], "summary": "Create a purchase order with lines", "description": "Lines reference products by SKU within the client's catalog (clientId omitted = house catalog). Unknown SKUs are rejected with 422.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "poNumber": { "type": "string", "minLength": 1 }, "clientId": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "open", "partially_received", "received", "closed", "cancelled" ] }, "supplierName": { "type": [ "string", "null" ] }, "supplierRef": { "type": [ "string", "null" ] }, "expectedDate": { "type": [ "string", "null" ], "format": "date-time" }, "notes": { "type": [ "string", "null" ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": [ "string", "null" ] }, "sku": { "type": "string", "minLength": 1 }, "orderedQty": { "type": "integer", "exclusiveMinimum": 0 }, "unitOfMeasure": { "type": "string" } }, "required": [ "sku", "orderedQty" ] } } }, "required": [ "poNumber" ] } } } }, "responses": { "201": { "description": "Created purchase order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseOrderWithLines" } } } }, "422": { "description": "Unknown SKU or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PoError" } } } } } } }, "/purchase-orders/{id}": { "get": { "tags": [ "Inbound" ], "summary": "Get a purchase order with its lines", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Purchase order details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseOrderWithLines" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PoError" } } } } } }, "patch": { "tags": [ "Inbound" ], "summary": "Update a purchase order", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "poNumber": { "type": "string", "minLength": 1 }, "clientId": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "open", "partially_received", "received", "closed", "cancelled" ] }, "supplierName": { "type": [ "string", "null" ] }, "supplierRef": { "type": [ "string", "null" ] }, "expectedDate": { "type": [ "string", "null" ], "format": "date-time" }, "notes": { "type": [ "string", "null" ] } } } } } }, "responses": { "200": { "description": "Updated purchase order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseOrder" } } } }, "422": { "description": "Invalid update", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PoError" } } } } } }, "delete": { "tags": [ "Inbound" ], "summary": "Cancel a purchase order", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Cancelled", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "cancelled": { "type": "boolean" } }, "required": [ "id", "cancelled" ] } } } }, "422": { "description": "Cannot cancel", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PoError" } } } } } } }, "/invoices": { "get": { "tags": [ "Billing" ], "summary": "List invoices", "parameters": [ { "schema": { "type": "string", "enum": [ "draft", "finalized", "void" ] }, "required": false, "name": "status", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "periodKey", "in": "query" }, { "schema": { "type": "string", "format": "uuid" }, "required": false, "name": "clientId", "in": "query" } ], "responses": { "200": { "description": "List of invoices", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Invoice" } } }, "required": [ "data" ] } } } } } } }, "/invoices/{id}": { "get": { "tags": [ "Billing" ], "summary": "Get an invoice with its lines", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Invoice details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceWithLines" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceError" } } } } } } }, "/zones": { "get": { "tags": [ "Zones" ], "summary": "List all zones", "responses": { "200": { "description": "List of zones", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Zone" } } }, "required": [ "data" ] } } } } } }, "post": { "tags": [ "Zones" ], "summary": "Create a zone", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "locationId": { "type": "string" }, "isActive": { "type": "boolean" } }, "required": [ "name", "locationId" ] } } } }, "responses": { "201": { "description": "Created zone", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Zone" } } } } } } }, "/zones/{id}": { "get": { "tags": [ "Zones" ], "summary": "Get a zone by ID", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Zone details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Zone" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ZoneError" } } } } } }, "patch": { "tags": [ "Zones" ], "summary": "Update a zone", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "locationId": { "type": "string" }, "isActive": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Updated zone", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Zone" } } } } } }, "delete": { "tags": [ "Zones" ], "summary": "Delete a zone", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean" } }, "required": [ "id", "deleted" ] } } } } } } }, "/containers": { "get": { "tags": [ "Containers" ], "summary": "List all containers", "responses": { "200": { "description": "List of containers", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Container" } } }, "required": [ "data" ] } } } } } }, "post": { "tags": [ "Containers" ], "summary": "Upsert a container by barcode", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "barcode": { "type": "string" }, "type": { "type": "string", "enum": [ "tote", "pallet", "carton", "bin", "shelf" ] }, "status": { "type": "string", "enum": [ "available", "in_use", "in_transit", "maintenance", "retired" ] }, "binCode": { "type": "string" }, "notes": { "type": [ "string", "null" ] } }, "required": [ "barcode", "type", "status" ] } } } }, "responses": { "200": { "description": "Upserted container", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Container" } } } } } } }, "/containers/{id}": { "get": { "tags": [ "Containers" ], "summary": "Get a container by ID", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Container details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Container" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContainerError" } } } } } }, "patch": { "tags": [ "Containers" ], "summary": "Update a container", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "barcode": { "type": "string" }, "type": { "type": "string", "enum": [ "tote", "pallet", "carton", "bin", "shelf" ] }, "status": { "type": "string", "enum": [ "available", "in_use", "in_transit", "maintenance", "retired" ] }, "notes": { "type": [ "string", "null" ] }, "currentConveyorId": { "type": [ "string", "null" ] }, "currentPathId": { "type": [ "string", "null" ] }, "currentDistance": { "type": [ "number", "null" ] }, "lastScanPointId": { "type": [ "string", "null" ] }, "lastSeenAt": { "type": [ "string", "null" ] }, "simulationStatus": { "type": [ "string", "null" ], "enum": [ "moving", "stuck", "audit", "removed", null ] } } } } } }, "responses": { "200": { "description": "Updated container", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Container" } } } } } }, "delete": { "tags": [ "Containers" ], "summary": "Delete a container", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean" } }, "required": [ "id", "deleted" ] } } } } } } }, "/containers/by-barcode/{barcode}/status-override": { "post": { "tags": [ "Containers" ], "summary": "Override a container's status by barcode", "description": "Hospital endpoint: set the container status and/or record a carton status. At least one of `status` / `cartonStatus` is required. `cartonStatus` is stored as the `carton_status` custom field.", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "barcode", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "available", "in_use", "in_transit", "maintenance", "retired" ] }, "cartonStatus": { "type": "string", "minLength": 1 } } } } } }, "responses": { "200": { "description": "Updated container", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Container" } } } }, "400": { "description": "Invalid override", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContainerError" } } } }, "404": { "description": "Container not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContainerError" } } } } } } }, "/containers/by-barcode/{barcode}/weight-override": { "post": { "tags": [ "Containers" ], "summary": "Override a container's weight by barcode", "description": "Hospital endpoint: record a manual weight reading. Stored as the `weight` / `weight_unit` custom fields with `weight_source` set to `scale_override`.", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "barcode", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "weight": { "type": "number", "exclusiveMinimum": 0 }, "unit": { "type": "string", "enum": [ "kg", "lb" ], "default": "lb" } }, "required": [ "weight" ] } } } }, "responses": { "200": { "description": "Updated container", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Container" } } } }, "400": { "description": "Invalid override", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContainerError" } } } }, "404": { "description": "Container not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContainerError" } } } } } } }, "/waves": { "get": { "tags": [ "Waves" ], "summary": "List all waves", "responses": { "200": { "description": "List of waves", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Wave" } } }, "required": [ "data" ] } } } } } }, "post": { "tags": [ "Waves" ], "summary": "Create a wave", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "build", "queued", "ready", "active", "closed" ], "default": "build" }, "origin": { "type": "string", "enum": [ "system", "user" ], "default": "user" }, "locationId": { "type": "string" }, "zoneId": { "type": [ "string", "null" ] }, "orderCount": { "type": "number", "default": 0 }, "totalItems": { "type": "number", "default": 0 }, "pickedItems": { "type": "number", "default": 0 }, "putItems": { "type": "number", "default": 0 } }, "required": [ "locationId" ] } } } }, "responses": { "201": { "description": "Created wave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Wave" } } } } } } }, "/waves/{id}": { "get": { "tags": [ "Waves" ], "summary": "Get a wave by ID", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Wave details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Wave" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WaveError" } } } } } }, "patch": { "tags": [ "Waves" ], "summary": "Update a wave", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "status": { "type": "string", "enum": [ "build", "queued", "ready", "active", "closed" ] }, "origin": { "type": "string", "enum": [ "system", "user" ] }, "zoneId": { "type": [ "string", "null" ] }, "orderCount": { "type": "number" }, "totalItems": { "type": "number" }, "pickedItems": { "type": "number" }, "putItems": { "type": "number" }, "closedAt": { "type": [ "string", "null" ] } } } } } }, "responses": { "200": { "description": "Updated wave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Wave" } } } } } }, "delete": { "tags": [ "Waves" ], "summary": "Delete a wave", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean" } }, "required": [ "id", "deleted" ] } } } } } } }, "/plans": { "get": { "tags": [ "Plans" ], "summary": "List wave plans", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": false, "name": "locationId", "in": "query" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "required": false, "name": "planDate", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "required": false, "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Plans, newest day first", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WavePlan" } } }, "required": [ "data" ] } } } } } }, "post": { "tags": [ "Plans" ], "summary": "Run a wave plan", "description": "Plans a day's orders at a location into waves and forecasts the labor. Defaults to tomorrow in the site timezone. Nothing is built until the plan is committed.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "locationId": { "type": "string", "format": "uuid" }, "planDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "headcountOverrides": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } }, "rateSource": { "type": "string", "enum": [ "standard", "observed" ] } }, "required": [ "locationId" ] } } } }, "responses": { "201": { "description": "The plan and its proposed waves", "content": { "application/json": { "schema": { "type": "object", "properties": { "plan": { "$ref": "#/components/schemas/WavePlan" }, "waves": { "type": "array", "items": { "$ref": "#/components/schemas/WavePlanWave" } } }, "required": [ "plan", "waves" ] } } } }, "400": { "description": "Could not plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WavePlanError" } } } } } } }, "/plans/{id}": { "get": { "tags": [ "Plans" ], "summary": "Get a wave plan with its waves", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Plan detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "plan": { "$ref": "#/components/schemas/WavePlan" }, "waves": { "type": "array", "items": { "$ref": "#/components/schemas/WavePlanWave" } } }, "required": [ "plan", "waves" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WavePlanError" } } } } } }, "delete": { "tags": [ "Plans" ], "summary": "Delete a draft plan", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" } }, "required": [ "id" ] } } } }, "400": { "description": "Could not delete", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WavePlanError" } } } } } } }, "/plans/{id}/commit": { "post": { "tags": [ "Plans" ], "summary": "Commit a plan's waves to the board", "description": "Turns proposed waves into real waves (Build, orders attached, then Queued). Orders that changed since planning are dropped and reported. Pass `waveIds` to commit a subset.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "waveIds": { "type": "array", "items": { "type": "string", "format": "uuid" } } } } } } }, "responses": { "200": { "description": "Per-wave outcome", "content": { "application/json": { "schema": { "type": "object", "properties": { "planId": { "type": "string", "format": "uuid" }, "outcomes": { "type": "array", "items": { "type": "object", "properties": { "planWaveId": { "type": "string", "format": "uuid" }, "proposedName": { "type": "string" }, "waveId": { "type": [ "string", "null" ], "format": "uuid" }, "waveName": { "type": [ "string", "null" ] }, "committedOrders": { "type": "number" }, "droppedOrders": { "type": "array", "items": { "type": "object", "properties": { "orderId": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "orderId", "reason" ] } } }, "required": [ "planWaveId", "proposedName", "waveId", "waveName", "committedOrders", "droppedOrders" ] } } }, "required": [ "planId", "outcomes" ] } } } }, "400": { "description": "Could not commit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WavePlanError" } } } } } } }, "/webhooks": { "get": { "tags": [ "Webhooks" ], "summary": "List all webhooks", "responses": { "200": { "description": "List of webhooks", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } } }, "required": [ "data" ] } } } } } }, "post": { "tags": [ "Webhooks" ], "summary": "Create a webhook", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "secret": { "type": "string", "default": "" }, "events": { "type": "array", "items": { "type": "string" }, "default": [ "*" ] }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "default": {} }, "enabled": { "type": "boolean", "default": true } }, "required": [ "name", "url" ] } } } }, "responses": { "201": { "description": "Created webhook", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } } } } }, "/webhooks/{id}": { "patch": { "tags": [ "Webhooks" ], "summary": "Update a webhook", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "secret": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "enabled": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Updated webhook", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } } } }, "delete": { "tags": [ "Webhooks" ], "summary": "Delete a webhook", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean" } }, "required": [ "id", "deleted" ] } } } } } } }, "/webhooks/{id}/test": { "post": { "tags": [ "Webhooks" ], "summary": "Test a webhook", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "string" } } } } } }, "responses": { "200": { "description": "Test result", "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "string" }, "deliveryId": { "type": "string" }, "success": { "type": "boolean" }, "status": { "type": [ "number", "null" ] }, "durationMs": { "type": "number" }, "error": { "type": [ "string", "null" ] }, "responseBody": { "type": [ "string", "null" ] } }, "required": [ "event", "deliveryId", "success", "status", "durationMs", "error" ] } } } } } } }, "/locations": { "get": { "tags": [ "Locations" ], "summary": "List all locations", "responses": { "200": { "description": "List of locations", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Location" } } }, "required": [ "data" ] } } } } } }, "post": { "tags": [ "Locations" ], "summary": "Create a location", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string", "minLength": 1 }, "description": { "type": [ "string", "null" ] } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Created location", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Location" } } } } } } }, "/locations/{id}": { "get": { "tags": [ "Locations" ], "summary": "Get a location by ID", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Location details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Location" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocationError" } } } } } }, "patch": { "tags": [ "Locations" ], "summary": "Update a location", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": [ "string", "null" ] }, "isActive": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Updated location", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Location" } } } } } }, "delete": { "tags": [ "Locations" ], "summary": "Delete a location", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean" } }, "required": [ "id", "deleted" ] } } } } } } }, "/bins": { "get": { "tags": [ "Bins" ], "summary": "List all bins", "responses": { "200": { "description": "List of bins", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Bin" } } }, "required": [ "data" ] } } } } } }, "post": { "tags": [ "Bins" ], "summary": "Upsert a bin by code", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "zoneId": { "type": [ "string", "null" ] }, "aisle": { "type": "string" }, "rack": { "type": "string" }, "level": { "type": "string" }, "position": { "type": "string" }, "isActive": { "type": "boolean" } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Upserted bin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bin" } } } } } } }, "/bins/{code}": { "delete": { "tags": [ "Bins" ], "summary": "Delete a bin by code", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "code", "in": "path" } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "deleted": { "type": "boolean" } }, "required": [ "code", "deleted" ] } } } } } } }, "/inducts/{code}/arrivals": { "post": { "tags": [ "Inducts" ], "summary": "Report a container arriving at an induct point", "description": "Called by middleware/PLC integration when a box is detected at an induct. The induct code is configured per induct point in the 3D overview editor. The container is upserted by barcode and placed at the induct's position on the conveyor, which makes it appear live in the 3D view.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "INDUCT-01" }, "required": true, "name": "code", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InductArrivalBody" } } } }, "responses": { "200": { "description": "Arrival recorded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InductArrival" } } } }, "404": { "description": "Induct code not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InductError" } } } } } } }, "/custom-field-values": { "get": { "tags": [ "Custom Field Values" ], "summary": "List custom field values for an entity", "parameters": [ { "schema": { "type": "string", "enum": [ "product", "container" ] }, "required": true, "name": "entityType", "in": "query" }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "entityId", "in": "query" } ], "responses": { "200": { "description": "Custom field values for the entity", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CustomFieldValue" } } }, "required": [ "data" ] } } } } } }, "put": { "tags": [ "Custom Field Values" ], "summary": "Bulk set custom field values for an entity", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "entityType": { "type": "string", "enum": [ "product", "container" ] }, "entityId": { "type": "string", "format": "uuid" }, "values": { "type": "array", "items": { "type": "object", "properties": { "fieldId": { "type": "string", "format": "uuid" }, "value": { "type": [ "string", "null" ] } }, "required": [ "fieldId", "value" ] } } }, "required": [ "entityType", "entityId", "values" ] } } } }, "responses": { "200": { "description": "Resulting custom field values", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CustomFieldValue" } } }, "required": [ "data" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomFieldValueError" } } } } } }, "post": { "tags": [ "Custom Field Values" ], "summary": "Upsert a single custom field value", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "entityType": { "type": "string", "enum": [ "product", "container" ] }, "entityId": { "type": "string", "format": "uuid" }, "fieldId": { "type": "string", "format": "uuid" }, "value": { "type": [ "string", "null" ] } }, "required": [ "entityType", "entityId", "fieldId", "value" ] } } } }, "responses": { "200": { "description": "Upserted value", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomFieldValue" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomFieldValueError" } } } } } } }, "/custom-field-values/{id}": { "delete": { "tags": [ "Custom Field Values" ], "summary": "Clear a custom field value", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean" } }, "required": [ "id", "deleted" ] } } } } } } }, "/sortation/lanes/get-lanes": { "get": { "tags": [ "Sortation" ], "summary": "Route a package to a single lane", "description": "Runs the lane-selection algorithm for one package on the named sorter and returns the destination lane. Mirrors the wxs-2.0 `get-lanes` endpoint.", "parameters": [ { "schema": { "type": "string", "example": "Sorter1" }, "required": true, "name": "sorter", "in": "query" }, { "schema": { "type": "string", "example": "1Z999AA10123456784" }, "required": false, "name": "code", "in": "query" } ], "responses": { "200": { "description": "Selected lane", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SortationSingleResult" } } } }, "400": { "description": "Invalid code, or no lanes configured on the sorter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SortationSingleResult" } } } } } } }, "/sortation/lanes/multi/get-lanes": { "get": { "tags": [ "Sortation" ], "summary": "Route a package, returning all eligible lanes", "description": "Like `get-lanes`, but returns the full eligible lane group (chosen lane first) with per-lane names and matched criteria. Mirrors the wxs-2.0 `multi/get-lanes` endpoint.", "parameters": [ { "schema": { "type": "string", "example": "Sorter1" }, "required": true, "name": "sorter", "in": "query" }, { "schema": { "type": "string", "example": "1Z999AA10123456784" }, "required": false, "name": "code", "in": "query" } ], "responses": { "200": { "description": "Selected lanes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SortationMultiResult" } } } }, "400": { "description": "Invalid code or invalid sorter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SortationMultiResult" } } } } } } }, "/sortation/lanes/get-enabled": { "get": { "tags": [ "Sortation" ], "summary": "List enabled lane numbers for a sorter", "parameters": [ { "schema": { "type": "string", "example": "Sorter1" }, "required": true, "name": "sorter", "in": "query" } ], "responses": { "200": { "description": "Enabled lane numbers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SortationLanesList" } } } } } } }, "/sortation/lanes/get-hospital": { "get": { "tags": [ "Sortation" ], "summary": "Get the hospital lane number for a sorter", "parameters": [ { "schema": { "type": "string", "example": "Sorter1" }, "required": true, "name": "sorter", "in": "query" } ], "responses": { "200": { "description": "Hospital lane (empty array if none assigned)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SortationLanesList" } } } }, "400": { "description": "Missing sorter", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/sortation/lanes/get-status": { "get": { "tags": [ "Sortation" ], "summary": "Get per-lane enabled + PLC availability status", "parameters": [ { "schema": { "type": "string", "example": "Sorter1" }, "required": true, "name": "sorter", "in": "query" } ], "responses": { "200": { "description": "Lane status list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SortationLaneStatus" } } } } } } }, "/sortation/get-mode": { "get": { "tags": [ "Sortation" ], "summary": "Get a sorter's mode", "description": "Returns the sorter's mode (stored `NONE` is surfaced as `STANDARD` for v1 compatibility) and round-robin container count.", "parameters": [ { "schema": { "type": "string", "example": "Sorter1" }, "required": true, "name": "sorter", "in": "query" } ], "responses": { "200": { "description": "Sorter mode", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SortationMode" } } } }, "404": { "description": "Sorter not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/sortation/update-mode": { "get": { "tags": [ "Sortation" ], "summary": "Set a sorter's mode", "description": "Sets the sorter's mode (query params, matching the wxs-2.0 signature). `STANDARD` is aliased to the stored `NONE`. For `ROUND_ROBIN`, `number_of_sorts` must be 1–99.", "parameters": [ { "schema": { "type": "string", "example": "Sorter1" }, "required": true, "name": "sorter", "in": "query" }, { "schema": { "type": "string", "enum": [ "STANDARD", "NONE", "FILL_FIRST", "ROUND_ROBIN" ], "example": "ROUND_ROBIN" }, "required": true, "name": "mode", "in": "query" }, { "schema": { "type": "string", "example": "3" }, "required": false, "name": "number_of_sorts", "in": "query" } ], "responses": { "200": { "description": "Updated mode", "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string" }, "number_of_sorts": { "type": [ "number", "null" ] }, "meta": { "$ref": "#/components/schemas/SortationMeta" } }, "required": [ "mode", "number_of_sorts", "meta" ] } } } }, "400": { "description": "Invalid number_of_sorts", "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" } }, "required": [ "reason" ] } } } }, "404": { "description": "Sorter not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" } }, "required": [ "reason" ] } } } } } } }, "/sortation/get-sorter-config": { "get": { "tags": [ "Sortation" ], "summary": "Get a sorter's full configuration", "description": "Returns the sorter's full 3.0-native configuration (config + lanes). Unlike v1 (which returned the raw Prisma row), this returns the current 3.0 shape.", "parameters": [ { "schema": { "type": "string", "example": "Sorter1" }, "required": true, "name": "sorter", "in": "query" } ], "responses": { "200": { "description": "Sorter configuration", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {} } } } }, "404": { "description": "Sorter not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/rates/shop": { "post": { "tags": [ "Rate Shopping" ], "summary": "Shop shipping rates across all enabled carrier accounts", "description": "Queries every enabled carrier account in parallel, normalizes the quotes, applies each account's service allow-list and markup, filters by the given constraints, and returns all surviving quotes sorted best-first per the strategy. Carriers that fail or time out are reported per-account in `failures` without blocking the shop.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateShopRequest" } } } }, "responses": { "200": { "description": "Shop result (quotes sorted best-first)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateShopResult" } } } }, "400": { "description": "Invalid shipment input", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/rates/carriers": { "get": { "tags": [ "Rate Shopping" ], "summary": "List configured carrier accounts and their shoppable services", "responses": { "200": { "description": "Carrier accounts (credentials are never included)", "content": { "application/json": { "schema": { "type": "object", "properties": { "carriers": { "type": "array", "items": { "$ref": "#/components/schemas/CarrierAccountSummary" } }, "meta": { "$ref": "#/components/schemas/RatesMeta" } }, "required": [ "carriers", "meta" ] } } } } } } }, "/events/types": { "get": { "tags": [ "Events" ], "summary": "List ingestable event types", "description": "Returns the catalog of every event type the ingestion API accepts, with its category, description, and target store.", "responses": { "200": { "description": "Event type catalog", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "category": { "type": "string" }, "description": { "type": "string" }, "table": { "type": "string" } }, "required": [ "type", "category", "description", "table" ] } } }, "required": [ "data" ] } } } } } } }, "/events": { "post": { "tags": [ "Events" ], "summary": "Ingest a single event", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IngestionEventInput" } } } }, "responses": { "202": { "description": "Event accepted and persisted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IngestionAccepted" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IngestionError" } } } } } } }, "/events/batch": { "post": { "tags": [ "Events" ], "summary": "Ingest a batch of events", "description": "Validates and persists up to 1000 events in one request. Partial success is allowed: each event's outcome is reported individually in `results`. The response is 200 whenever the batch was well-formed, even if some events failed validation.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IngestionBatchInput" } } } }, "responses": { "200": { "description": "Per-event ingestion result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IngestionBatchResult" } } } }, "400": { "description": "Malformed batch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IngestionError" } } } } } } }, "/export/datasets": { "get": { "tags": [ "Export" ], "summary": "List exportable datasets", "description": "Returns every dataset this caller may export — every warehouse entity (orders, products, containers, …) and every activity log table — with its backing store and the read permission that gates it. Pass `columns=1` to include each dataset's column names (for search / discovery).", "parameters": [ { "schema": { "type": "string", "example": "1" }, "required": false, "name": "columns", "in": "query" } ], "responses": { "200": { "description": "Dataset catalog", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/ExportDataset" }, { "type": "object", "properties": { "columns": { "type": "array", "items": { "type": "string" } } } } ] } } }, "required": [ "data" ] } } } } } } }, "/export/datasets/{dataset}": { "get": { "tags": [ "Export" ], "summary": "Describe a dataset", "parameters": [ { "schema": { "type": "string", "example": "orders" }, "required": true, "name": "dataset", "in": "path" } ], "responses": { "200": { "description": "Dataset metadata and columns", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ExportDataset" }, { "type": "object", "properties": { "columns": { "type": "array", "items": { "$ref": "#/components/schemas/ExportColumn" } } }, "required": [ "columns" ] } ] } } } } } } }, "/export/{dataset}": { "get": { "tags": [ "Export" ], "summary": "Export a page of a dataset", "description": "Returns one page of a dataset in the requested format. Filter with `where` (JSON), pick `columns`, sort with `orderBy` (`-createdAt,orderNumber`), bound by `since`/`until`, or aggregate with `groupBy`. Timestamp columns are rendered in the site timezone (ISO 8601 with offset) unless `timezone=utc`. Requires the dataset's own read permission.", "parameters": [ { "schema": { "type": "string", "example": "orders" }, "required": true, "name": "dataset", "in": "path" }, { "schema": { "type": "string", "description": "Drizzle-style filter. `{\"status\":\"shipped\"}` for equality; `{\"priority\":{\"gte\":2},\"carrier\":{\"ilike\":\"%ups%\"}}` with operators eq, ne, gt, gte, lt, lte, inArray, notInArray, like, notLike, ilike, notIlike, isNull, isNotNull, between, notBetween; `{\"or\":[...]}`, `{\"and\":[...]}`, `{\"not\":{...}}` to combine. Column names come from GET /export/datasets/{dataset}.", "example": "{\"status\":\"shipped\",\"lineCount\":1}" }, "required": false, "description": "Drizzle-style filter. `{\"status\":\"shipped\"}` for equality; `{\"priority\":{\"gte\":2},\"carrier\":{\"ilike\":\"%ups%\"}}` with operators eq, ne, gt, gte, lt, lte, inArray, notInArray, like, notLike, ilike, notIlike, isNull, isNotNull, between, notBetween; `{\"or\":[...]}`, `{\"and\":[...]}`, `{\"not\":{...}}` to combine. Column names come from GET /export/datasets/{dataset}.", "name": "where", "in": "query" }, { "schema": { "type": "string", "description": "Comma-separated column names; all when omitted", "example": "orderNumber,status,carrier,createdAt" }, "required": false, "description": "Comma-separated column names; all when omitted", "name": "columns", "in": "query" }, { "schema": { "type": "string", "description": "Comma-separated columns; prefix with - for descending", "example": "-createdAt" }, "required": false, "description": "Comma-separated columns; prefix with - for descending", "name": "orderBy", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Inclusive lower bound on the time column (ISO 8601)" }, "required": false, "description": "Inclusive lower bound on the time column (ISO 8601)", "name": "since", "in": "query" }, { "schema": { "type": "string", "format": "date-time" }, "required": false, "name": "until", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 10000, "example": 1000 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": [ "integer", "null" ], "minimum": 0, "example": 0 }, "required": false, "name": "offset", "in": "query" }, { "schema": { "type": "string", "enum": [ "json", "ndjson", "csv", "xlsx" ] }, "required": false, "name": "format", "in": "query" }, { "schema": { "type": "string", "description": "Group by this column and return {group, value} rows instead of records" }, "required": false, "description": "Group by this column and return {group, value} rows instead of records", "name": "groupBy", "in": "query" }, { "schema": { "type": "string", "enum": [ "count", "sum", "avg", "min", "max" ] }, "required": false, "name": "aggregate", "in": "query" }, { "schema": { "type": "string", "description": "Numeric column for sum/avg/min/max" }, "required": false, "description": "Numeric column for sum/avg/min/max", "name": "aggregateField", "in": "query" }, { "schema": { "type": "string", "enum": [ "site", "utc" ], "description": "How timestamp columns are rendered: site (default) = the configured site timezone in the site's technical timestamp standard (ISO 8601 with offset unless changed under Configuration → General, e.g. 2026-09-06T10:08:55-04:00); utc = raw UTC instants (2026-09-06T14:08:55.000Z)", "example": "site" }, "required": false, "description": "How timestamp columns are rendered: site (default) = the configured site timezone in the site's technical timestamp standard (ISO 8601 with offset unless changed under Configuration → General, e.g. 2026-09-06T10:08:55-04:00); utc = raw UTC instants (2026-09-06T14:08:55.000Z)", "name": "timezone", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "filename", "in": "query" } ], "responses": { "200": { "description": "A page of rows in the requested format. For ndjson/csv/xlsx the pagination is returned in the X-Total-Count / X-Next-Offset / X-Has-More headers.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "pagination": { "type": "object", "properties": { "dataset": { "type": "string" }, "limit": { "type": "number" }, "offset": { "type": "number" }, "returned": { "type": "number" }, "total": { "type": [ "number", "null" ] }, "hasMore": { "type": "boolean" }, "nextOffset": { "type": [ "number", "null" ] } }, "required": [ "dataset", "limit", "offset", "returned", "total", "hasMore", "nextOffset" ] } }, "required": [ "data", "pagination" ] } }, "application/x-ndjson": { "schema": { "type": "string" } }, "text/csv": { "schema": { "type": "string" } }, "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Bad filter, column, or format" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Unknown dataset" } } }, "post": { "tags": [ "Export" ], "summary": "Export a page of a dataset (JSON body)", "description": "The same export as GET, with the request in a JSON body — easier for nested filters. Every field is optional.", "parameters": [ { "schema": { "type": "string", "example": "orders" }, "required": true, "name": "dataset", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportRequest" } } } }, "responses": { "200": { "description": "A page of rows in the requested format. For ndjson/csv/xlsx the pagination is returned in the X-Total-Count / X-Next-Offset / X-Has-More headers.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "pagination": { "type": "object", "properties": { "dataset": { "type": "string" }, "limit": { "type": "number" }, "offset": { "type": "number" }, "returned": { "type": "number" }, "total": { "type": [ "number", "null" ] }, "hasMore": { "type": "boolean" }, "nextOffset": { "type": [ "number", "null" ] } }, "required": [ "dataset", "limit", "offset", "returned", "total", "hasMore", "nextOffset" ] } }, "required": [ "data", "pagination" ] } }, "application/x-ndjson": { "schema": { "type": "string" } }, "text/csv": { "schema": { "type": "string" } }, "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Bad filter, column, or format" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Unknown dataset" } } } }, "/export/spec": { "get": { "tags": [ "Export" ], "summary": "Export the rows behind a chart", "description": "Runs a ChartSpec (the definition behind every Explore chart, dashboard widget and report section) and returns its rows. `spec` is the base64url-encoded spec — copy it from a chart's menu in the app (Get API request). `from`/`to` pin the chart to an absolute site-local window instead of its rolling range.", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "spec", "in": "query" }, { "schema": { "type": "string", "enum": [ "json", "ndjson", "csv", "xlsx" ] }, "required": false, "name": "format", "in": "query" }, { "schema": { "type": "string", "example": "2026-09-01" }, "required": false, "name": "from", "in": "query" }, { "schema": { "type": "string", "example": "2026-09-30" }, "required": false, "name": "to", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "filename", "in": "query" } ], "responses": { "200": { "description": "The chart's rows: the x grouping first, then one column per series.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "columns": { "type": "array", "items": { "type": "string" } } }, "required": [ "data", "columns" ] } }, "text/csv": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid spec" }, "403": { "description": "Insufficient permissions for the spec's dataset" } } } }, "/export/sql": { "post": { "tags": [ "Export" ], "summary": "Export the result of a read-only ClickHouse query", "description": "Runs one SELECT against the activity log tables (the same guarded runner as the app's SQL editor: read-only, per-table read permissions, environment row policies, 10s and 1000-row caps). Requires dashboard:RunCustomQuery. `{environmentId}` and `{timezone}` are available as bound variables.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "sql": { "type": "string", "example": "SELECT toStartOfDay(created_at, {timezone}) AS day, count() AS picks FROM pick_put_logs GROUP BY day ORDER BY day" }, "format": { "type": "string", "enum": [ "json", "ndjson", "csv", "xlsx" ] }, "filename": { "type": "string" } }, "required": [ "sql" ] } } } }, "responses": { "200": { "description": "Query rows in the requested format", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "columns": { "type": "array", "items": { "type": "string" } } }, "required": [ "data", "columns" ] } }, "text/csv": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid or non-read-only SQL" }, "403": { "description": "Insufficient permissions" } } } }, "/print": { "post": { "tags": [ "Print" ], "summary": "Send a ZPL label to a printer or printer group", "description": "Targets exactly one of `groupId`, `groupName`, or `pandaId`. Group prints select a printer per the group's mode (round-robin or duty/standby) and fail over through remaining members.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrintRequest" } } } }, "responses": { "200": { "description": "Label sent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrintResult" } } } }, "400": { "description": "Invalid target selection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrintErrorBody" } } } }, "404": { "description": "Printer or group not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrintErrorBody" } } } }, "409": { "description": "No active printers in the group", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrintErrorBody" } } } }, "502": { "description": "Printer connection failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrintErrorBody" } } } } } } } }, "webhooks": {} }