{ "openapi": "3.1.0", "info": { "title": "LinenFlow Public API", "version": "1.0.0", "description": "Read-only REST access to your LinenFlow data. Authenticate with `Authorization: Bearer lfk_live_…`. Lists paginate by opaque cursor. Timestamps are ISO 8601 UTC; money is integer cents except direct-sales charge unit prices, which are mills (unit_price_mills, 1/1000 dollar); weights are pounds. Keys see exactly the customers granted to them — nothing else exists." }, "servers": [ { "url": "https://api.linenflow.co/v1" } ], "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "lfk_live_…" } }, "schemas": { "Envelope": { "type": "object", "properties": { "data": { "description": "The resource array (lists) or object (single resources)." }, "pagination": { "type": "object", "properties": { "cursor": { "type": [ "string", "null" ], "description": "Pass as ?cursor= for the next page. Null on the last page." }, "has_more": { "type": "boolean" } } }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "unauthorized", "forbidden", "not_found", "method_not_allowed", "invalid_params", "rate_limited", "internal_error" ] }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "request_id": { "type": "string" } }, "required": [ "error", "request_id" ] } } }, "paths": { "/customers": { "get": { "operationId": "customers", "summary": "List the customers this key can access", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size, 1–200. Default 50.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from the previous page.", "schema": { "type": "string" } }, { "name": "customer_id", "in": "query", "required": false, "description": "Filter to one customer. Must be within the key’s access.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "data": [ { "id": "cm0example1", "name": "Grandview Medical Center", "is_group": false, "created_at": "2026-01-05T14:00:00.000Z", "departments": [ { "id": "cm0exdept1", "name": "Surgery" } ] } ], "pagination": { "cursor": null, "has_more": false }, "request_id": "req_…" } } } }, "401": { "description": "Missing, unknown, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Missing, unknown, or revoked API key." }, "request_id": "req_…" } } } }, "403": { "description": "The key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "The key lacks the required scope." }, "request_id": "req_…" } } } }, "404": { "description": "Unknown endpoint or resource outside the key’s access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Unknown endpoint or resource outside the key’s access." }, "request_id": "req_…" } } } }, "422": { "description": "A query parameter is missing, unknown, or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_params", "message": "A query parameter is missing, unknown, or malformed." }, "request_id": "req_…" } } } }, "429": { "description": "Rate limit exceeded — honor the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded — honor the Retry-After header." }, "request_id": "req_…" } } } }, "500": { "description": "Unexpected failure — quote request_id to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected failure — quote request_id to support." }, "request_id": "req_…" } } } } } } }, "/customers/{id}/departments": { "get": { "operationId": "customers_id_departments", "summary": "List one customer’s departments", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size, 1–200. Default 50.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from the previous page.", "schema": { "type": "string" } }, { "name": "customer_id", "in": "query", "required": false, "description": "Filter to one customer. Must be within the key’s access.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "data": [ { "id": "cm0exdept1", "customer_id": "cm0example1", "name": "Surgery", "cost_center_code": "4400" } ], "pagination": { "cursor": null, "has_more": false }, "request_id": "req_…" } } } }, "401": { "description": "Missing, unknown, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Missing, unknown, or revoked API key." }, "request_id": "req_…" } } } }, "403": { "description": "The key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "The key lacks the required scope." }, "request_id": "req_…" } } } }, "404": { "description": "Unknown endpoint or resource outside the key’s access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Unknown endpoint or resource outside the key’s access." }, "request_id": "req_…" } } } }, "422": { "description": "A query parameter is missing, unknown, or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_params", "message": "A query parameter is missing, unknown, or malformed." }, "request_id": "req_…" } } } }, "429": { "description": "Rate limit exceeded — honor the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded — honor the Retry-After header." }, "request_id": "req_…" } } } }, "500": { "description": "Unexpected failure — quote request_id to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected failure — quote request_id to support." }, "request_id": "req_…" } } } } } } }, "/items": { "get": { "operationId": "items", "summary": "List catalog items relevant to the key’s customers", "description": "Filtered to one customer, weight_lb reflects that customer’s override when set.", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size, 1–200. Default 50.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from the previous page.", "schema": { "type": "string" } }, { "name": "customer_id", "in": "query", "required": false, "description": "Filter to one customer. Must be within the key’s access.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "data": [ { "id": "cm0exitem1", "sku": "BTH-01", "name": "Bath Towel", "category": "Towels", "unit_of_measure": "each", "weight_lb": 0.65 } ], "pagination": { "cursor": null, "has_more": false }, "request_id": "req_…" } } } }, "401": { "description": "Missing, unknown, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Missing, unknown, or revoked API key." }, "request_id": "req_…" } } } }, "403": { "description": "The key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "The key lacks the required scope." }, "request_id": "req_…" } } } }, "404": { "description": "Unknown endpoint or resource outside the key’s access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Unknown endpoint or resource outside the key’s access." }, "request_id": "req_…" } } } }, "422": { "description": "A query parameter is missing, unknown, or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_params", "message": "A query parameter is missing, unknown, or malformed." }, "request_id": "req_…" } } } }, "429": { "description": "Rate limit exceeded — honor the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded — honor the Retry-After header." }, "request_id": "req_…" } } } }, "500": { "description": "Unexpected failure — quote request_id to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected failure — quote request_id to support." }, "request_id": "req_…" } } } } } } }, "/manifests": { "get": { "operationId": "manifests", "summary": "List manifests", "description": "Date filters apply to the delivered date.", "x-required-scope": "processing", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size, 1–200. Default 50.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from the previous page.", "schema": { "type": "string" } }, { "name": "customer_id", "in": "query", "required": false, "description": "Filter to one customer. Must be within the key’s access.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "Inclusive start (YYYY-MM-DD, org timezone).", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "Inclusive end (YYYY-MM-DD, org timezone).", "schema": { "type": "string", "format": "date" } }, { "name": "department_id", "in": "query", "required": false, "description": "Filter to one department.", "schema": { "type": "string" } }, { "name": "type", "in": "query", "required": false, "description": "Filter by manifest type.", "schema": { "type": "string", "enum": [ "normal", "rewash", "new_linen" ] } }, { "name": "status", "in": "query", "required": false, "description": "Filter by lifecycle status.", "schema": { "type": "string", "enum": [ "collected", "received", "cleaned", "staged", "delivered" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "data": [ { "id": "cm0exman1", "manifest_number": "MAN-26-000123", "type": "normal", "status": "delivered", "customer_id": "cm0example1", "department_id": "cm0exdept1", "department_name": "Surgery", "created_at": "2026-08-01T12:00:00.000Z", "picked_up_at": "2026-08-01T13:05:00.000Z", "received_at": "2026-08-01T15:20:00.000Z", "cleaned_at": "2026-08-02T15:00:00.000Z", "staged_at": "2026-08-02T18:30:00.000Z", "delivered_at": "2026-08-03T12:10:00.000Z", "soil_weight_lb": 100, "clean_weight_lb": 90.9, "clean_piece_count": 400, "variance_pct": 0.091, "variance_within_tolerance": true, "parent_manifest_id": null, "amount_cents": 41500, "currency": "usd" } ], "pagination": { "cursor": null, "has_more": false }, "request_id": "req_…" } } } }, "401": { "description": "Missing, unknown, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Missing, unknown, or revoked API key." }, "request_id": "req_…" } } } }, "403": { "description": "The key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "The key lacks the required scope." }, "request_id": "req_…" } } } }, "404": { "description": "Unknown endpoint or resource outside the key’s access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Unknown endpoint or resource outside the key’s access." }, "request_id": "req_…" } } } }, "422": { "description": "A query parameter is missing, unknown, or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_params", "message": "A query parameter is missing, unknown, or malformed." }, "request_id": "req_…" } } } }, "429": { "description": "Rate limit exceeded — honor the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded — honor the Retry-After header." }, "request_id": "req_…" } } } }, "500": { "description": "Unexpected failure — quote request_id to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected failure — quote request_id to support." }, "request_id": "req_…" } } } } } } }, "/manifests/{id}": { "get": { "operationId": "manifests_id", "summary": "Get one manifest with bins, rewash links, and signature metadata", "x-required-scope": "processing", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "data": { "id": "cm0exman1", "manifest_number": "MAN-26-000123", "type": "normal", "status": "delivered", "customer_id": "cm0example1", "department_id": "cm0exdept1", "department_name": "Surgery", "created_at": "2026-08-01T12:00:00.000Z", "picked_up_at": "2026-08-01T13:05:00.000Z", "received_at": "2026-08-01T15:20:00.000Z", "cleaned_at": "2026-08-02T15:00:00.000Z", "staged_at": "2026-08-02T18:30:00.000Z", "delivered_at": "2026-08-03T12:10:00.000Z", "soil_weight_lb": 100, "clean_weight_lb": 90.9, "clean_piece_count": 400, "variance_pct": 0.091, "variance_within_tolerance": true, "parent_manifest_id": null, "amount_cents": 41500, "currency": "usd", "bins": [ { "id": "cm0exbin1", "side": "soil", "content": "good", "bin_ticket_number": "B-26-0000001", "gross_lb": 110.2, "tare_lb": 10.2, "net_lb": 100, "items": [] }, { "id": "cm0exbin2", "side": "clean", "content": "good", "bin_ticket_number": "B-26-0000002", "gross_lb": 101.1, "tare_lb": 10.2, "net_lb": 90.9, "items": [ { "item_id": "cm0exitem1", "item_name": "Bath Towel", "piece_count": 400, "disposition": "cleaned" } ] } ], "held_rewash": { "held_weight_lb": 10, "status": "pending", "soil_rewash_lb": 6.6, "error_rewash_lb": 3.4 }, "rewash_links": { "parent_manifest": null, "rewash_children": [ { "id": "cm0exman2", "manifest_number": "MAN-26-000124" } ] }, "signature": { "signed_by_name": "Pat Jones", "signed_by_title": "Receiving Clerk", "delivered_at": "2026-08-03T12:10:00.000Z" } }, "request_id": "req_…" } } } }, "401": { "description": "Missing, unknown, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Missing, unknown, or revoked API key." }, "request_id": "req_…" } } } }, "403": { "description": "The key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "The key lacks the required scope." }, "request_id": "req_…" } } } }, "404": { "description": "Unknown endpoint or resource outside the key’s access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Unknown endpoint or resource outside the key’s access." }, "request_id": "req_…" } } } }, "422": { "description": "A query parameter is missing, unknown, or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_params", "message": "A query parameter is missing, unknown, or malformed." }, "request_id": "req_…" } } } }, "429": { "description": "Rate limit exceeded — honor the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded — honor the Retry-After header." }, "request_id": "req_…" } } } }, "500": { "description": "Unexpected failure — quote request_id to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected failure — quote request_id to support." }, "request_id": "req_…" } } } } } } }, "/deliveries/daily": { "get": { "operationId": "deliveries_daily", "summary": "Daily delivered counts by customer, department, and item with par and fill rate", "description": "Defaults to the last 7 days and caps the range at 92 days.", "x-required-scope": "processing", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size, 1–200. Default 50.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from the previous page.", "schema": { "type": "string" } }, { "name": "customer_id", "in": "query", "required": false, "description": "Filter to one customer. Must be within the key’s access.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "Inclusive start (YYYY-MM-DD, org timezone).", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "Inclusive end (YYYY-MM-DD, org timezone).", "schema": { "type": "string", "format": "date" } }, { "name": "department_id", "in": "query", "required": false, "description": "Filter to one department.", "schema": { "type": "string" } }, { "name": "item_id", "in": "query", "required": false, "description": "Filter to one item.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "data": [ { "date": "2026-08-11", "customer_id": "cm0example1", "customer_name": "Grandview Medical Center", "department_id": "cm0exdept1", "department_name": "Surgery", "item_id": "cm0exitem1", "item_name": "Bath Towel", "delivered_count": 340, "daily_par": 400, "fill_rate": 0.85 } ], "pagination": { "cursor": null, "has_more": false }, "request_id": "req_…" } } } }, "401": { "description": "Missing, unknown, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Missing, unknown, or revoked API key." }, "request_id": "req_…" } } } }, "403": { "description": "The key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "The key lacks the required scope." }, "request_id": "req_…" } } } }, "404": { "description": "Unknown endpoint or resource outside the key’s access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Unknown endpoint or resource outside the key’s access." }, "request_id": "req_…" } } } }, "422": { "description": "A query parameter is missing, unknown, or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_params", "message": "A query parameter is missing, unknown, or malformed." }, "request_id": "req_…" } } } }, "429": { "description": "Rate limit exceeded — honor the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded — honor the Retry-After header." }, "request_id": "req_…" } } } }, "500": { "description": "Unexpected failure — quote request_id to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected failure — quote request_id to support." }, "request_id": "req_…" } } } } } } }, "/inventory/totals": { "get": { "operationId": "inventory_totals", "summary": "List per-item inventory totals by location", "description": "total_owned excludes retired units.", "x-required-scope": "processing", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size, 1–200. Default 50.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from the previous page.", "schema": { "type": "string" } }, { "name": "customer_id", "in": "query", "required": false, "description": "Filter to one customer. Must be within the key’s access.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "data": [ { "item_id": "cm0exitem1", "item_name": "Bath Towel", "total_owned": 1200, "at_customer": 800, "at_facility": 350, "in_transit": 50, "retired": 90 } ], "pagination": { "cursor": null, "has_more": false }, "request_id": "req_…" } } } }, "401": { "description": "Missing, unknown, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Missing, unknown, or revoked API key." }, "request_id": "req_…" } } } }, "403": { "description": "The key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "The key lacks the required scope." }, "request_id": "req_…" } } } }, "404": { "description": "Unknown endpoint or resource outside the key’s access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Unknown endpoint or resource outside the key’s access." }, "request_id": "req_…" } } } }, "422": { "description": "A query parameter is missing, unknown, or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_params", "message": "A query parameter is missing, unknown, or malformed." }, "request_id": "req_…" } } } }, "429": { "description": "Rate limit exceeded — honor the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded — honor the Retry-After header." }, "request_id": "req_…" } } } }, "500": { "description": "Unexpected failure — quote request_id to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected failure — quote request_id to support." }, "request_id": "req_…" } } } } } } }, "/inventory/par": { "get": { "operationId": "inventory_par", "summary": "List live par levels", "description": "A null department_id is the customer-wide row.", "x-required-scope": "processing", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size, 1–200. Default 50.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from the previous page.", "schema": { "type": "string" } }, { "name": "customer_id", "in": "query", "required": false, "description": "Filter to one customer. Must be within the key’s access.", "schema": { "type": "string" } }, { "name": "department_id", "in": "query", "required": false, "description": "Filter to one department.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "data": [ { "customer_id": "cm0example1", "department_id": "cm0exdept1", "department_name": "Surgery", "item_id": "cm0exitem1", "item_name": "Bath Towel", "par_quantity": 400, "par_unit": "pieces", "reorder_threshold": 120 } ], "pagination": { "cursor": null, "has_more": false }, "request_id": "req_…" } } } }, "401": { "description": "Missing, unknown, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Missing, unknown, or revoked API key." }, "request_id": "req_…" } } } }, "403": { "description": "The key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "The key lacks the required scope." }, "request_id": "req_…" } } } }, "404": { "description": "Unknown endpoint or resource outside the key’s access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Unknown endpoint or resource outside the key’s access." }, "request_id": "req_…" } } } }, "422": { "description": "A query parameter is missing, unknown, or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_params", "message": "A query parameter is missing, unknown, or malformed." }, "request_id": "req_…" } } } }, "429": { "description": "Rate limit exceeded — honor the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded — honor the Retry-After header." }, "request_id": "req_…" } } } }, "500": { "description": "Unexpected failure — quote request_id to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected failure — quote request_id to support." }, "request_id": "req_…" } } } } } } }, "/new-linen": { "get": { "operationId": "new-linen", "summary": "List new-linen injections", "description": "date is the org-local cleaned day; from/to filter on it.", "x-required-scope": "processing", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size, 1–200. Default 50.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from the previous page.", "schema": { "type": "string" } }, { "name": "customer_id", "in": "query", "required": false, "description": "Filter to one customer. Must be within the key’s access.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "Inclusive start (YYYY-MM-DD, org timezone).", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "Inclusive end (YYYY-MM-DD, org timezone).", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "data": [ { "id": "cm0exman1", "manifest_number": "MAN-26-000123", "date": "2026-08-10", "customer_id": "cm0example1", "department_id": null, "direction": "in", "soil_weight_lb": 52.1, "injected_weight_lb": 51.8, "items": [ { "item_id": "cm0exitem1", "item_name": "Bath Towel", "piece_count": 240 } ] } ], "pagination": { "cursor": null, "has_more": false }, "request_id": "req_…" } } } }, "401": { "description": "Missing, unknown, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Missing, unknown, or revoked API key." }, "request_id": "req_…" } } } }, "403": { "description": "The key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "The key lacks the required scope." }, "request_id": "req_…" } } } }, "404": { "description": "Unknown endpoint or resource outside the key’s access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Unknown endpoint or resource outside the key’s access." }, "request_id": "req_…" } } } }, "422": { "description": "A query parameter is missing, unknown, or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_params", "message": "A query parameter is missing, unknown, or malformed." }, "request_id": "req_…" } } } }, "429": { "description": "Rate limit exceeded — honor the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded — honor the Retry-After header." }, "request_id": "req_…" } } } }, "500": { "description": "Unexpected failure — quote request_id to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected failure — quote request_id to support." }, "request_id": "req_…" } } } } } } }, "/rewash": { "get": { "operationId": "rewash", "summary": "List held and resolved rewash batches", "description": "from/to filter on the discovered date.", "x-required-scope": "processing", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size, 1–200. Default 50.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from the previous page.", "schema": { "type": "string" } }, { "name": "customer_id", "in": "query", "required": false, "description": "Filter to one customer. Must be within the key’s access.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "Inclusive start (YYYY-MM-DD, org timezone).", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "Inclusive end (YYYY-MM-DD, org timezone).", "schema": { "type": "string", "format": "date" } }, { "name": "status", "in": "query", "required": false, "description": "Filter by batch status.", "schema": { "type": "string", "enum": [ "pending", "consumed", "voided" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "data": [ { "id": "cm0exrw1", "customer_id": "cm0example1", "department_id": null, "discovered_at": "2026-08-09T14:20:00.000Z", "status": "consumed", "held_weight_lb": 62.4, "soil_rewash_lb": 40.1, "error_rewash_lb": 22.3, "parent_manifest": { "id": "cm0exman1", "manifest_number": "MAN-26-000118" }, "consumed_by_manifest": { "id": "cm0exman2", "manifest_number": "MAN-26-000125", "delivered_at": "2026-08-11T16:05:00.000Z" }, "outcomes": [ { "fault_class": "soil_rewash", "good_lb": 36, "damage_lb": 4.1 } ] } ], "pagination": { "cursor": null, "has_more": false }, "request_id": "req_…" } } } }, "401": { "description": "Missing, unknown, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Missing, unknown, or revoked API key." }, "request_id": "req_…" } } } }, "403": { "description": "The key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "The key lacks the required scope." }, "request_id": "req_…" } } } }, "404": { "description": "Unknown endpoint or resource outside the key’s access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Unknown endpoint or resource outside the key’s access." }, "request_id": "req_…" } } } }, "422": { "description": "A query parameter is missing, unknown, or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_params", "message": "A query parameter is missing, unknown, or malformed." }, "request_id": "req_…" } } } }, "429": { "description": "Rate limit exceeded — honor the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded — honor the Retry-After header." }, "request_id": "req_…" } } } }, "500": { "description": "Unexpected failure — quote request_id to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected failure — quote request_id to support." }, "request_id": "req_…" } } } } } } }, "/inventory/units": { "get": { "operationId": "inventory_units", "summary": "List units", "description": "A unit is a floor or area that holds carts.", "x-required-scope": "processing", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size, 1–200. Default 50.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from the previous page.", "schema": { "type": "string" } }, { "name": "customer_id", "in": "query", "required": false, "description": "Filter to one customer. Must be within the key’s access.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "data": [ { "id": "cm0exunit1", "customer_id": "cm0example1", "name": "8 North East", "building": "Main", "floor": "8", "unit_type": "med_surg", "cost_center": "70110", "cart_count": 3, "is_active": true } ], "pagination": { "cursor": null, "has_more": false }, "request_id": "req_…" } } } }, "401": { "description": "Missing, unknown, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Missing, unknown, or revoked API key." }, "request_id": "req_…" } } } }, "403": { "description": "The key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "The key lacks the required scope." }, "request_id": "req_…" } } } }, "404": { "description": "Unknown endpoint or resource outside the key’s access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Unknown endpoint or resource outside the key’s access." }, "request_id": "req_…" } } } }, "422": { "description": "A query parameter is missing, unknown, or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_params", "message": "A query parameter is missing, unknown, or malformed." }, "request_id": "req_…" } } } }, "429": { "description": "Rate limit exceeded — honor the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded — honor the Retry-After header." }, "request_id": "req_…" } } } }, "500": { "description": "Unexpected failure — quote request_id to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected failure — quote request_id to support." }, "request_id": "req_…" } } } } } } }, "/inventory/carts": { "get": { "operationId": "inventory_carts", "summary": "List carts with their par", "description": "par is the live par sheet of the cart. count_days are the days the cart is counted.", "x-required-scope": "processing", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size, 1–200. Default 50.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from the previous page.", "schema": { "type": "string" } }, { "name": "customer_id", "in": "query", "required": false, "description": "Filter to one customer. Must be within the key’s access.", "schema": { "type": "string" } }, { "name": "unit_id", "in": "query", "required": false, "description": "Filter to one unit.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "data": [ { "id": "cm0excart1", "customer_id": "cm0example1", "unit_id": "cm0exunit1", "unit_name": "8 North East", "name": "8 North East 1", "kind": "cart", "stocking_method": "fixed", "count_days": [ "mon", "tue", "wed", "thu", "fri" ], "is_active": true, "par": [ { "item_id": "cm0exitem1", "item_name": "Bath Towel", "par_quantity": 40 } ] } ], "pagination": { "cursor": null, "has_more": false }, "request_id": "req_…" } } } }, "401": { "description": "Missing, unknown, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Missing, unknown, or revoked API key." }, "request_id": "req_…" } } } }, "403": { "description": "The key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "The key lacks the required scope." }, "request_id": "req_…" } } } }, "404": { "description": "Unknown endpoint or resource outside the key’s access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Unknown endpoint or resource outside the key’s access." }, "request_id": "req_…" } } } }, "422": { "description": "A query parameter is missing, unknown, or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_params", "message": "A query parameter is missing, unknown, or malformed." }, "request_id": "req_…" } } } }, "429": { "description": "Rate limit exceeded — honor the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded — honor the Retry-After header." }, "request_id": "req_…" } } } }, "500": { "description": "Unexpected failure — quote request_id to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected failure — quote request_id to support." }, "request_id": "req_…" } } } } } } }, "/inventory/counts": { "get": { "operationId": "inventory_counts", "summary": "List cart counts", "description": "date is the org-local count day; from/to filter on it (default the last 7 days, 92 days at most). par is the par when the count was generated.", "x-required-scope": "processing", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size, 1–200. Default 50.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from the previous page.", "schema": { "type": "string" } }, { "name": "customer_id", "in": "query", "required": false, "description": "Filter to one customer. Must be within the key’s access.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "Inclusive start (YYYY-MM-DD, org timezone).", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "Inclusive end (YYYY-MM-DD, org timezone).", "schema": { "type": "string", "format": "date" } }, { "name": "unit_id", "in": "query", "required": false, "description": "Filter to one unit.", "schema": { "type": "string" } }, { "name": "cart_id", "in": "query", "required": false, "description": "Filter to one cart.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Filter by count status.", "schema": { "type": "string", "enum": [ "pending", "in_progress", "counted", "verified", "assumed" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "data": [ { "id": "cm0excount1", "customer_id": "cm0example1", "cart_id": "cm0excart1", "cart_name": "8 North East 1", "unit_id": "cm0exunit1", "unit_name": "8 North East", "date": "2026-09-21", "status": "counted", "unscheduled": false, "counted_at": "2026-09-21T10:42:00.000Z", "verified_at": null, "lines": [ { "item_id": "cm0exitem1", "item_name": "Bath Towel", "par": 40, "on_hand": 12, "required": 28, "delivered": 28, "extra": 0, "returned": 0 } ] } ], "pagination": { "cursor": null, "has_more": false }, "request_id": "req_…" } } } }, "401": { "description": "Missing, unknown, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Missing, unknown, or revoked API key." }, "request_id": "req_…" } } } }, "403": { "description": "The key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "The key lacks the required scope." }, "request_id": "req_…" } } } }, "404": { "description": "Unknown endpoint or resource outside the key’s access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Unknown endpoint or resource outside the key’s access." }, "request_id": "req_…" } } } }, "422": { "description": "A query parameter is missing, unknown, or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_params", "message": "A query parameter is missing, unknown, or malformed." }, "request_id": "req_…" } } } }, "429": { "description": "Rate limit exceeded — honor the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded — honor the Retry-After header." }, "request_id": "req_…" } } } }, "500": { "description": "Unexpected failure — quote request_id to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected failure — quote request_id to support." }, "request_id": "req_…" } } } } } } }, "/inventory/balances": { "get": { "operationId": "inventory_balances", "summary": "List balances by item and status", "description": "One row per item and status with a non-zero quantity.", "x-required-scope": "processing", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size, 1–200. Default 50.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from the previous page.", "schema": { "type": "string" } }, { "name": "customer_id", "in": "query", "required": false, "description": "Filter to one customer. Must be within the key’s access.", "schema": { "type": "string" } }, { "name": "item_id", "in": "query", "required": false, "description": "Filter to one item.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "data": [ { "item_id": "cm0exitem1", "item_name": "Bath Towel", "status": "in_reserve", "quantity": 350 }, { "item_id": "cm0exitem1", "item_name": "Bath Towel", "status": "at_customer", "quantity": 800 } ], "pagination": { "cursor": null, "has_more": false }, "request_id": "req_…" } } } }, "401": { "description": "Missing, unknown, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Missing, unknown, or revoked API key." }, "request_id": "req_…" } } } }, "403": { "description": "The key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "The key lacks the required scope." }, "request_id": "req_…" } } } }, "404": { "description": "Unknown endpoint or resource outside the key’s access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Unknown endpoint or resource outside the key’s access." }, "request_id": "req_…" } } } }, "422": { "description": "A query parameter is missing, unknown, or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_params", "message": "A query parameter is missing, unknown, or malformed." }, "request_id": "req_…" } } } }, "429": { "description": "Rate limit exceeded — honor the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded — honor the Retry-After header." }, "request_id": "req_…" } } } }, "500": { "description": "Unexpected failure — quote request_id to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected failure — quote request_id to support." }, "request_id": "req_…" } } } } } } }, "/inventory/signals": { "get": { "operationId": "inventory_signals", "summary": "List inventory signals", "description": "Open and acknowledged signals by default. Advisory only.", "x-required-scope": "processing", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size, 1–200. Default 50.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from the previous page.", "schema": { "type": "string" } }, { "name": "customer_id", "in": "query", "required": false, "description": "Filter to one customer. Must be within the key’s access.", "schema": { "type": "string" } }, { "name": "kind", "in": "query", "required": false, "description": "Filter by signal kind.", "schema": { "type": "string", "enum": [ "shortfall_streak", "rolling_erosion", "injection_dependency", "over_fill", "dormant_stock", "circulation_breach", "unmatched_injection", "receiving_variance", "end_of_life", "count_overdue" ] } }, { "name": "status", "in": "query", "required": false, "description": "Filter by status.", "schema": { "type": "string", "enum": [ "open", "acknowledged", "dismissed", "resolved" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "data": [ { "id": "cm0exsig1", "kind": "shortfall_streak", "severity": "high", "status": "open", "customer_id": "cm0example1", "department_id": null, "item_id": "cm0exitem1", "item_name": "Bath Towel", "summary": "7 service days under 85% · average 70%", "suggested_order_qty": null, "window_start": "2026-08-24", "window_end": "2026-09-20", "generated_at": "2026-09-21T06:15:04.000Z" } ], "pagination": { "cursor": null, "has_more": false }, "request_id": "req_…" } } } }, "401": { "description": "Missing, unknown, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Missing, unknown, or revoked API key." }, "request_id": "req_…" } } } }, "403": { "description": "The key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "The key lacks the required scope." }, "request_id": "req_…" } } } }, "404": { "description": "Unknown endpoint or resource outside the key’s access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Unknown endpoint or resource outside the key’s access." }, "request_id": "req_…" } } } }, "422": { "description": "A query parameter is missing, unknown, or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_params", "message": "A query parameter is missing, unknown, or malformed." }, "request_id": "req_…" } } } }, "429": { "description": "Rate limit exceeded — honor the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded — honor the Retry-After header." }, "request_id": "req_…" } } } }, "500": { "description": "Unexpected failure — quote request_id to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected failure — quote request_id to support." }, "request_id": "req_…" } } } } } } }, "/invoices": { "get": { "operationId": "invoices", "summary": "List sent invoices with totals, balance, and a signed PDF link", "description": "Only sent, partially_paid, and paid invoices exist publicly. pdf_url is signed and expires in about 15 minutes.", "x-required-scope": "accounting", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size, 1–200. Default 50.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from the previous page.", "schema": { "type": "string" } }, { "name": "customer_id", "in": "query", "required": false, "description": "Filter to one customer. Must be within the key’s access.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "Inclusive start (YYYY-MM-DD, org timezone).", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "Inclusive end (YYYY-MM-DD, org timezone).", "schema": { "type": "string", "format": "date" } }, { "name": "status", "in": "query", "required": false, "description": "Filter to one status.", "schema": { "type": "string", "enum": [ "sent", "partially_paid", "paid" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "data": [ { "id": "cm0exinv1", "invoice_number": "INV-26-00042", "status": "sent", "customer_id": "cm0example1", "department_id": null, "issued_at": "2026-08-01T15:00:00.000Z", "due_at": "2026-08-31T15:00:00.000Z", "sent_at": "2026-08-01T15:05:00.000Z", "paid_at": null, "subtotal_cents": 125000, "surcharges_cents": 2500, "tax_cents": 0, "total_cents": 127500, "balance_cents": 127500, "currency": "usd", "pdf_url": "https://api.linenflow.co/v1/files/invoice/cm0exinv1?kid=key_…&exp=1780000000&sig=…" } ], "pagination": { "cursor": null, "has_more": false }, "request_id": "req_…" } } } }, "401": { "description": "Missing, unknown, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Missing, unknown, or revoked API key." }, "request_id": "req_…" } } } }, "403": { "description": "The key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "The key lacks the required scope." }, "request_id": "req_…" } } } }, "404": { "description": "Unknown endpoint or resource outside the key’s access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Unknown endpoint or resource outside the key’s access." }, "request_id": "req_…" } } } }, "422": { "description": "A query parameter is missing, unknown, or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_params", "message": "A query parameter is missing, unknown, or malformed." }, "request_id": "req_…" } } } }, "429": { "description": "Rate limit exceeded — honor the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded — honor the Retry-After header." }, "request_id": "req_…" } } } }, "500": { "description": "Unexpected failure — quote request_id to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected failure — quote request_id to support." }, "request_id": "req_…" } } } } } } }, "/files/invoice/{id}": { "get": { "operationId": "files_invoice_id", "summary": "Fetch one invoice PDF via its signed expiring link", "description": "Auth is the signed query string from pdf_url. The key is re-verified live at fetch time.", "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "kid", "in": "query", "required": true, "description": "Key id from the signed link.", "schema": { "type": "string" } }, { "name": "exp", "in": "query", "required": true, "description": "Expiry timestamp from the signed link.", "schema": { "type": "integer" } }, { "name": "sig", "in": "query", "required": true, "description": "Signature from the signed link.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/pdf": { "schema": { "type": "string", "contentEncoding": "binary" } } } }, "401": { "description": "Missing, unknown, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Missing, unknown, or revoked API key." }, "request_id": "req_…" } } } }, "403": { "description": "The key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "The key lacks the required scope." }, "request_id": "req_…" } } } }, "404": { "description": "Unknown endpoint or resource outside the key’s access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Unknown endpoint or resource outside the key’s access." }, "request_id": "req_…" } } } }, "422": { "description": "A query parameter is missing, unknown, or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_params", "message": "A query parameter is missing, unknown, or malformed." }, "request_id": "req_…" } } } }, "429": { "description": "Rate limit exceeded — honor the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded — honor the Retry-After header." }, "request_id": "req_…" } } } }, "500": { "description": "Unexpected failure — quote request_id to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected failure — quote request_id to support." }, "request_id": "req_…" } } } } } } }, "/payments": { "get": { "operationId": "payments", "summary": "List payments with their invoice allocations", "x-required-scope": "accounting", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size, 1–200. Default 50.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from the previous page.", "schema": { "type": "string" } }, { "name": "customer_id", "in": "query", "required": false, "description": "Filter to one customer. Must be within the key’s access.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "Inclusive start (YYYY-MM-DD, org timezone).", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "Inclusive end (YYYY-MM-DD, org timezone).", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "data": [ { "id": "cm0expay1", "customer_id": "cm0example1", "kind": "check", "status": "settled", "amount_cents": 127500, "currency": "usd", "received_at": "2026-08-10T14:00:00.000Z", "returned_at": null, "allocations": [ { "invoice_id": "cm0exinv1", "invoice_number": "INV-26-00042", "amount_cents": 127500 } ] } ], "pagination": { "cursor": null, "has_more": false }, "request_id": "req_…" } } } }, "401": { "description": "Missing, unknown, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Missing, unknown, or revoked API key." }, "request_id": "req_…" } } } }, "403": { "description": "The key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "The key lacks the required scope." }, "request_id": "req_…" } } } }, "404": { "description": "Unknown endpoint or resource outside the key’s access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Unknown endpoint or resource outside the key’s access." }, "request_id": "req_…" } } } }, "422": { "description": "A query parameter is missing, unknown, or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_params", "message": "A query parameter is missing, unknown, or malformed." }, "request_id": "req_…" } } } }, "429": { "description": "Rate limit exceeded — honor the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded — honor the Retry-After header." }, "request_id": "req_…" } } } }, "500": { "description": "Unexpected failure — quote request_id to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected failure — quote request_id to support." }, "request_id": "req_…" } } } } } } }, "/balance": { "get": { "operationId": "balance", "summary": "A/R balance and aging buckets per customer", "x-required-scope": "accounting", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size, 1–200. Default 50.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from the previous page.", "schema": { "type": "string" } }, { "name": "customer_id", "in": "query", "required": false, "description": "Filter to one customer. Must be within the key’s access.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "data": [ { "customer_id": "cm0example1", "customer_name": "Grandview Medical Center", "balance_cents": 127500, "currency": "usd", "aging": { "current": 127500, "d1_30": 0, "d31_60": 0, "d61_plus": 0 } } ], "pagination": { "cursor": null, "has_more": false }, "request_id": "req_…" } } } }, "401": { "description": "Missing, unknown, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Missing, unknown, or revoked API key." }, "request_id": "req_…" } } } }, "403": { "description": "The key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "The key lacks the required scope." }, "request_id": "req_…" } } } }, "404": { "description": "Unknown endpoint or resource outside the key’s access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Unknown endpoint or resource outside the key’s access." }, "request_id": "req_…" } } } }, "422": { "description": "A query parameter is missing, unknown, or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_params", "message": "A query parameter is missing, unknown, or malformed." }, "request_id": "req_…" } } } }, "429": { "description": "Rate limit exceeded — honor the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded — honor the Retry-After header." }, "request_id": "req_…" } } } }, "500": { "description": "Unexpected failure — quote request_id to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected failure — quote request_id to support." }, "request_id": "req_…" } } } } } } }, "/purchase-orders": { "get": { "operationId": "purchase-orders", "summary": "List purchase orders with total, spent, and remaining amounts", "x-required-scope": "accounting", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size, 1–200. Default 50.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from the previous page.", "schema": { "type": "string" } }, { "name": "customer_id", "in": "query", "required": false, "description": "Filter to one customer. Must be within the key’s access.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Filter to one status.", "schema": { "type": "string", "enum": [ "pending", "active", "closed", "cancelled" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "data": [ { "id": "cm0expo1", "customer_id": "cm0example1", "po_number": "PO-2026-118", "status": "active", "total_cents": 5000000, "spent_cents": 1275000, "remaining_cents": 3725000, "currency": "usd", "started_at": "2026-07-01T04:00:00.000Z", "expires_at": "2027-06-30T04:00:00.000Z" } ], "pagination": { "cursor": null, "has_more": false }, "request_id": "req_…" } } } }, "401": { "description": "Missing, unknown, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Missing, unknown, or revoked API key." }, "request_id": "req_…" } } } }, "403": { "description": "The key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "The key lacks the required scope." }, "request_id": "req_…" } } } }, "404": { "description": "Unknown endpoint or resource outside the key’s access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Unknown endpoint or resource outside the key’s access." }, "request_id": "req_…" } } } }, "422": { "description": "A query parameter is missing, unknown, or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_params", "message": "A query parameter is missing, unknown, or malformed." }, "request_id": "req_…" } } } }, "429": { "description": "Rate limit exceeded — honor the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded — honor the Retry-After header." }, "request_id": "req_…" } } } }, "500": { "description": "Unexpected failure — quote request_id to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected failure — quote request_id to support." }, "request_id": "req_…" } } } } } } }, "/orders": { "get": { "operationId": "orders", "summary": "List direct-sales orders", "description": "from/to filter on placed_at in the org timezone.", "x-required-scope": "direct_sales", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size, 1–200. Default 50.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from the previous page.", "schema": { "type": "string" } }, { "name": "customer_id", "in": "query", "required": false, "description": "Filter to one customer. Must be within the key’s access.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "Inclusive start (YYYY-MM-DD, org timezone).", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "Inclusive end (YYYY-MM-DD, org timezone).", "schema": { "type": "string", "format": "date" } }, { "name": "stage", "in": "query", "required": false, "description": "Filter by order stage.", "schema": { "type": "string", "enum": [ "draft", "submitted", "in_production", "shipped", "delivered", "cancelled" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "data": [ { "id": "cm0exorder1", "order_number": "DS-26-00042", "stage": "submitted", "customer_id": "cm0example1", "placed_at": "2026-08-01T14:30:00.000Z", "requested_delivery_date": "2026-08-08T00:00:00.000Z", "confirmed_delivery_date": null, "delivered_at": null, "subtotal_cents": 12500, "total_cents": 13500, "currency": "usd", "orderer_name": "Dana Ortiz", "wearer_name": "Sam Lee", "wearer_department": "Cardiology", "delivery_location": "Main dock", "po_number": "PO-1042", "line_count": 2 } ], "pagination": { "cursor": null, "has_more": false }, "request_id": "req_…" } } } }, "401": { "description": "Missing, unknown, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Missing, unknown, or revoked API key." }, "request_id": "req_…" } } } }, "403": { "description": "The key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "The key lacks the required scope." }, "request_id": "req_…" } } } }, "404": { "description": "Unknown endpoint or resource outside the key’s access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Unknown endpoint or resource outside the key’s access." }, "request_id": "req_…" } } } }, "422": { "description": "A query parameter is missing, unknown, or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_params", "message": "A query parameter is missing, unknown, or malformed." }, "request_id": "req_…" } } } }, "429": { "description": "Rate limit exceeded — honor the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded — honor the Retry-After header." }, "request_id": "req_…" } } } }, "500": { "description": "Unexpected failure — quote request_id to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected failure — quote request_id to support." }, "request_id": "req_…" } } } } } } }, "/orders/{id}": { "get": { "operationId": "orders_id", "summary": "Fetch one direct-sales order with lines and charges", "x-required-scope": "direct_sales", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "data": { "id": "cm0exorder1", "order_number": "DS-26-00042", "stage": "submitted", "customer_id": "cm0example1", "placed_at": "2026-08-01T14:30:00.000Z", "requested_delivery_date": "2026-08-08T00:00:00.000Z", "confirmed_delivery_date": null, "delivered_at": null, "subtotal_cents": 12500, "total_cents": 13500, "currency": "usd", "orderer_name": "Dana Ortiz", "wearer_name": "Sam Lee", "wearer_department": "Cardiology", "delivery_location": "Main dock", "po_number": "PO-1042", "line_count": 2, "status_history": [ { "to": "submitted", "at": "2026-08-01T14:30:00.000Z" } ], "lines": [ { "id": "cm0exline1", "is_order_level": false, "item_name": "Lab Coat", "size": "M", "color": "White", "quantity": 2, "manufacturer": "Northwind Uniforms", "embroidery_lines": [ "SAM LEE", "CARDIOLOGY" ], "line_subtotal_cents": 12500, "charges": [ { "description": "Lab Coat", "charge_basis": "per_piece", "is_base_item": true, "unit_price_mills": 55000, "quantity": 2, "amount_cents": 11000 } ] } ] }, "request_id": "req_…" } } } }, "401": { "description": "Missing, unknown, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Missing, unknown, or revoked API key." }, "request_id": "req_…" } } } }, "403": { "description": "The key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "The key lacks the required scope." }, "request_id": "req_…" } } } }, "404": { "description": "Unknown endpoint or resource outside the key’s access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Unknown endpoint or resource outside the key’s access." }, "request_id": "req_…" } } } }, "422": { "description": "A query parameter is missing, unknown, or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_params", "message": "A query parameter is missing, unknown, or malformed." }, "request_id": "req_…" } } } }, "429": { "description": "Rate limit exceeded — honor the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded — honor the Retry-After header." }, "request_id": "req_…" } } } }, "500": { "description": "Unexpected failure — quote request_id to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected failure — quote request_id to support." }, "request_id": "req_…" } } } } } } }, "/quality-tickets": { "get": { "operationId": "quality-tickets", "summary": "List quality tickets", "description": "The event thread includes customer-visible entries only.", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size, 1–200. Default 50.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from the previous page.", "schema": { "type": "string" } }, { "name": "customer_id", "in": "query", "required": false, "description": "Filter to one customer. Must be within the key’s access.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "Inclusive start (YYYY-MM-DD, org timezone).", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "Inclusive end (YYYY-MM-DD, org timezone).", "schema": { "type": "string", "format": "date" } }, { "name": "status", "in": "query", "required": false, "description": "Filter by ticket status.", "schema": { "type": "string", "enum": [ "new", "acknowledged", "in_progress", "resolved", "verified" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "data": [ { "id": "cm0exticket1", "ticket_number": "TKT-26-00007", "kind": "stain", "kind_label": "Stain", "status": "acknowledged", "status_label": "Acknowledged", "subject": "Stained surgical towels", "created_at": "2026-08-10T13:00:00.000Z", "acknowledged_at": "2026-08-10T15:00:00.000Z", "resolved_at": null, "resolution_note": null, "last_correspondence_at": "2026-08-10T13:00:00.000Z", "customer_visible_events": [ { "event_type": "created", "actor_kind": "portal", "body": "Towels arrived stained.", "created_at": "2026-08-10T13:00:00.000Z" } ] } ], "pagination": { "cursor": null, "has_more": false }, "request_id": "req_…" } } } }, "401": { "description": "Missing, unknown, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Missing, unknown, or revoked API key." }, "request_id": "req_…" } } } }, "403": { "description": "The key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "The key lacks the required scope." }, "request_id": "req_…" } } } }, "404": { "description": "Unknown endpoint or resource outside the key’s access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Unknown endpoint or resource outside the key’s access." }, "request_id": "req_…" } } } }, "422": { "description": "A query parameter is missing, unknown, or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_params", "message": "A query parameter is missing, unknown, or malformed." }, "request_id": "req_…" } } } }, "429": { "description": "Rate limit exceeded — honor the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded — honor the Retry-After header." }, "request_id": "req_…" } } } }, "500": { "description": "Unexpected failure — quote request_id to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected failure — quote request_id to support." }, "request_id": "req_…" } } } } } } }, "/ratings": { "get": { "operationId": "ratings", "summary": "List delivery ratings", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size, 1–200. Default 50.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from the previous page.", "schema": { "type": "string" } }, { "name": "customer_id", "in": "query", "required": false, "description": "Filter to one customer. Must be within the key’s access.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "Inclusive start (YYYY-MM-DD, org timezone).", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "Inclusive end (YYYY-MM-DD, org timezone).", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "data": [ { "id": "cm0exrating1", "customer_id": "cm0example1", "manifest_id": "cm0exmanifest1", "manifest_number": "MAN-26-000123", "on_time": true, "quality_rating": 5, "note": "On time and clean.", "created_at": "2026-08-11T16:00:00.000Z" } ], "pagination": { "cursor": null, "has_more": false }, "request_id": "req_…" } } } }, "401": { "description": "Missing, unknown, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Missing, unknown, or revoked API key." }, "request_id": "req_…" } } } }, "403": { "description": "The key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "The key lacks the required scope." }, "request_id": "req_…" } } } }, "404": { "description": "Unknown endpoint or resource outside the key’s access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Unknown endpoint or resource outside the key’s access." }, "request_id": "req_…" } } } }, "422": { "description": "A query parameter is missing, unknown, or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_params", "message": "A query parameter is missing, unknown, or malformed." }, "request_id": "req_…" } } } }, "429": { "description": "Rate limit exceeded — honor the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded — honor the Retry-After header." }, "request_id": "req_…" } } } }, "500": { "description": "Unexpected failure — quote request_id to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected failure — quote request_id to support." }, "request_id": "req_…" } } } } } } } } }