{ "openapi": "3.1.0", "info": { "title": "ROME API", "version": "1.0.0", "description": "The machine-facing surface of a ROME deployment.\n\n**Each customer runs their own ROME**, so this API lives at their host, not at a shared one. Write your integration once against this document and configure it per customer: a base URL and a key.\n\n**Authentication** is an API key, sent as `Authorization: Bearer rome_sk_...`. Keys are issued by the facility's IT administrator, carry a fixed list of permissions, and do not expire — they are revoked when they should stop working.\n\n**Timestamps** are epoch milliseconds UTC. The slots `date` parameter is a local YYYY-MM-DD date. Each facility reports its own IANA timezone so you can render a dock's day correctly.\n\n**Versioning.** Everything here is under `/v1` and will keep working. A breaking change ships as `/v2` and both run while you migrate." }, "servers": [ { "url": "https://your-rome-host/api", "description": "One customer's ROME deployment" } ], "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "An API key issued by the facility. Begins `rome_sk_`." } } }, "security": [ { "apiKey": [] } ], "paths": { "/v1/expected-work/orders": { "get": { "summary": "List expected orders", "description": "Expected work uses snake_case payloads. See docs/api/expected-work.md for validation, allocation and replay semantics. Lists return at most 1,000 records; imports accept at most 500 rows. Handler errors carry an error message; authentication errors also carry a code. No appointment, check-in or yard presence is created by intake.\n\n**Requires scope:** `orders:read`", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "location_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Assigned location/dock ID." }, { "name": "date", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Expected day YYYY-MM-DD." }, { "name": "reference", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Exact alias, trimmed and case-insensitive." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": [ { "id": "order-id", "order_no": "PO-001", "quantity": 10, "unit": "pallets", "allocated": 4, "references": [ { "type": "ORDER", "value": "PO-001", "primary": true } ], "allocations": [ { "load_id": "shipment-id", "quantity": 4 } ] } ] } } }, "400": { "description": "`missing_parameter` — A required query parameter was not sent.\n\n`bad_range` — The from/to window is backwards or wider than 366 days.\n\n`too_many_rows` — The range holds more rows than one response may carry. Ask for less.\n\n`bad_value` — An enum or field value is invalid.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "401": { "description": "`no_credentials` — No Authorization header.\n\n`invalid_key` — The key is unknown, malformed or revoked. All three answer the same.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "403": { "description": "`missing_scope` — The key is live but was not given this permission. The response names what is missing.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "404": { "description": "`not_found` — No such facility, or one this key cannot see. Both answer the same.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "409": { "description": "`not_bookable` — The requested appointment conflicts with booking rules or capacity; helper validation may also return 400/404.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "429": { "description": "Rate limited. Honor Retry-After when present and back off." }, "500": { "description": "`server_error` — Something failed on our side. Retry reads with backoff; reconcile writes before retrying because a response can be lost after commit.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } } } }, "post": { "summary": "Create or replay expected orders", "description": "Expected work uses snake_case payloads. See docs/api/expected-work.md for validation, allocation and replay semantics. Lists return at most 1,000 records; imports accept at most 500 rows. Handler errors carry an error message; authentication errors also carry a code. No appointment, check-in or yard presence is created by intake.\n\n**Requires scope:** `orders:write`", "security": [ { "apiKey": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "location_id": "dock-id", "rows": [ { "source": "erp", "source_key": "stable-row-001", "references": [ { "type": "ORDER", "value": "PO-001", "primary": true } ], "quantity": 10, "unit": "pallets", "expected_date": "2026-10-01", "direction": "out" } ] } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "example": { "orders": [ { "id": "order-id", "created": true } ] } } } }, "400": { "description": "`missing_parameter` — A required query parameter was not sent.\n\n`bad_range` — The from/to window is backwards or wider than 366 days.\n\n`too_many_rows` — The range holds more rows than one response may carry. Ask for less.\n\n`bad_value` — An enum or field value is invalid.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "401": { "description": "`no_credentials` — No Authorization header.\n\n`invalid_key` — The key is unknown, malformed or revoked. All three answer the same.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "403": { "description": "`missing_scope` — The key is live but was not given this permission. The response names what is missing.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "404": { "description": "`not_found` — No such facility, or one this key cannot see. Both answer the same.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "409": { "description": "`not_bookable` — The requested appointment conflicts with booking rules or capacity; helper validation may also return 400/404.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "429": { "description": "Rate limited. Honor Retry-After when present and back off." }, "500": { "description": "`server_error` — Something failed on our side. Retry reads with backoff; reconcile writes before retrying because a response can be lost after commit.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } } } } }, "/v1/expected-work/orders/preview": { "post": { "summary": "Validate an import without writing", "description": "Expected work uses snake_case payloads. See docs/api/expected-work.md for validation, allocation and replay semantics. Lists return at most 1,000 records; imports accept at most 500 rows. Handler errors carry an error message; authentication errors also carry a code. No appointment, check-in or yard presence is created by intake.\n\n**Requires scope:** `orders:write`", "security": [ { "apiKey": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "location_id": "dock-id", "rows": [ { "source": "erp", "source_key": "stable-row-001", "references": [ { "type": "ORDER", "value": "PO-001", "primary": true } ], "quantity": 10, "unit": "pallets", "expected_date": "2026-10-01", "direction": "out" } ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "valid": true, "count": 1, "errors": [] } } } }, "400": { "description": "`missing_parameter` — A required query parameter was not sent.\n\n`bad_range` — The from/to window is backwards or wider than 366 days.\n\n`too_many_rows` — The range holds more rows than one response may carry. Ask for less.\n\n`bad_value` — An enum or field value is invalid.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "401": { "description": "`no_credentials` — No Authorization header.\n\n`invalid_key` — The key is unknown, malformed or revoked. All three answer the same.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "403": { "description": "`missing_scope` — The key is live but was not given this permission. The response names what is missing.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "404": { "description": "`not_found` — No such facility, or one this key cannot see. Both answer the same.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "409": { "description": "`not_bookable` — The requested appointment conflicts with booking rules or capacity; helper validation may also return 400/404.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "429": { "description": "Rate limited. Honor Retry-After when present and back off." }, "500": { "description": "`server_error` — Something failed on our side. Retry reads with backoff; reconcile writes before retrying because a response can be lost after commit.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } } } } }, "/v1/expected-work/orders/{id}": { "patch": { "summary": "Enrich references or update an unallocated quantity", "description": "Expected work uses snake_case payloads. See docs/api/expected-work.md for validation, allocation and replay semantics. Lists return at most 1,000 records; imports accept at most 500 rows. Handler errors carry an error message; authentication errors also carry a code. No appointment, check-in or yard presence is created by intake.\n\n**Requires scope:** `orders:write`", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Order or shipment ID; its location must be visible to this key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "references": [ { "type": "BOL", "value": "BOL-002" } ], "expected_date": "2026-10-02" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "ok": true } } } }, "400": { "description": "`missing_parameter` — A required query parameter was not sent.\n\n`bad_range` — The from/to window is backwards or wider than 366 days.\n\n`too_many_rows` — The range holds more rows than one response may carry. Ask for less.\n\n`bad_value` — An enum or field value is invalid.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "401": { "description": "`no_credentials` — No Authorization header.\n\n`invalid_key` — The key is unknown, malformed or revoked. All three answer the same.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "403": { "description": "`missing_scope` — The key is live but was not given this permission. The response names what is missing.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "404": { "description": "`not_found` — No such facility, or one this key cannot see. Both answer the same.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "409": { "description": "`not_bookable` — The requested appointment conflicts with booking rules or capacity; helper validation may also return 400/404.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "429": { "description": "Rate limited. Honor Retry-After when present and back off." }, "500": { "description": "`server_error` — Something failed on our side. Retry reads with backoff; reconcile writes before retrying because a response can be lost after commit.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } } } } }, "/v1/expected-work/shipments": { "get": { "summary": "List assembled shipments", "description": "Expected work uses snake_case payloads. See docs/api/expected-work.md for validation, allocation and replay semantics. Lists return at most 1,000 records; imports accept at most 500 rows. Handler errors carry an error message; authentication errors also carry a code. No appointment, check-in or yard presence is created by intake.\n\n**Requires scope:** `orders:read`", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "location_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Assigned location/dock ID." }, { "name": "reference", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Matches a shipment alias or an allocated order alias." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": [ { "id": "shipment-id", "stop_id": "stop-id", "reference": "LOAD-001", "direction": "pickup", "service_method": "live", "appointment_id": null, "references": [], "orders": [ { "id": "order-id", "order_no": "PO-001", "quantity": 4, "unit": "pallets" } ] } ] } } }, "400": { "description": "`missing_parameter` — A required query parameter was not sent.\n\n`bad_range` — The from/to window is backwards or wider than 366 days.\n\n`too_many_rows` — The range holds more rows than one response may carry. Ask for less.\n\n`bad_value` — An enum or field value is invalid.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "401": { "description": "`no_credentials` — No Authorization header.\n\n`invalid_key` — The key is unknown, malformed or revoked. All three answer the same.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "403": { "description": "`missing_scope` — The key is live but was not given this permission. The response names what is missing.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "404": { "description": "`not_found` — No such facility, or one this key cannot see. Both answer the same.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "409": { "description": "`not_bookable` — The requested appointment conflicts with booking rules or capacity; helper validation may also return 400/404.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "429": { "description": "Rate limited. Honor Retry-After when present and back off." }, "500": { "description": "`server_error` — Something failed on our side. Retry reads with backoff; reconcile writes before retrying because a response can be lost after commit.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } } } }, "post": { "summary": "Allocate orders to a shipment and issue its private invitation", "description": "Expected work uses snake_case payloads. See docs/api/expected-work.md for validation, allocation and replay semantics. Lists return at most 1,000 records; imports accept at most 500 rows. Handler errors carry an error message; authentication errors also carry a code. No appointment, check-in or yard presence is created by intake.\n\n**Requires scope:** `orders:write`, `appointments:write`", "security": [ { "apiKey": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "location_id": "dock-id", "request_id": "unique-request-001", "direction": "out", "service_method": "live", "references": [ { "type": "LOAD", "value": "LOAD-001", "primary": true } ], "allocations": [ { "order_id": "order-id", "quantity": 4 } ] } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "example": { "id": "shipment-id", "stopId": "stop-id", "bookingLinkId": "link-id", "bookingUrl": null } } } }, "400": { "description": "`missing_parameter` — A required query parameter was not sent.\n\n`bad_range` — The from/to window is backwards or wider than 366 days.\n\n`too_many_rows` — The range holds more rows than one response may carry. Ask for less.\n\n`bad_value` — An enum or field value is invalid.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "401": { "description": "`no_credentials` — No Authorization header.\n\n`invalid_key` — The key is unknown, malformed or revoked. All three answer the same.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "403": { "description": "`missing_scope` — The key is live but was not given this permission. The response names what is missing.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "404": { "description": "`not_found` — No such facility, or one this key cannot see. Both answer the same.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "409": { "description": "`not_bookable` — The requested appointment conflicts with booking rules or capacity; helper validation may also return 400/404.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "429": { "description": "Rate limited. Honor Retry-After when present and back off." }, "500": { "description": "`server_error` — Something failed on our side. Retry reads with backoff; reconcile writes before retrying because a response can be lost after commit.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } } } } }, "/v1/expected-work/shipments/{id}/references": { "patch": { "summary": "Add shipment reference aliases", "description": "Expected work uses snake_case payloads. See docs/api/expected-work.md for validation, allocation and replay semantics. Lists return at most 1,000 records; imports accept at most 500 rows. Handler errors carry an error message; authentication errors also carry a code. No appointment, check-in or yard presence is created by intake.\n\n**Requires scope:** `orders:write`", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Order or shipment ID; its location must be visible to this key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "references": [ { "type": "TMS_LOAD", "value": "TMS-001" } ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "ok": true } } } }, "400": { "description": "`missing_parameter` — A required query parameter was not sent.\n\n`bad_range` — The from/to window is backwards or wider than 366 days.\n\n`too_many_rows` — The range holds more rows than one response may carry. Ask for less.\n\n`bad_value` — An enum or field value is invalid.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "401": { "description": "`no_credentials` — No Authorization header.\n\n`invalid_key` — The key is unknown, malformed or revoked. All three answer the same.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "403": { "description": "`missing_scope` — The key is live but was not given this permission. The response names what is missing.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "404": { "description": "`not_found` — No such facility, or one this key cannot see. Both answer the same.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "409": { "description": "`not_bookable` — The requested appointment conflicts with booking rules or capacity; helper validation may also return 400/404.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "429": { "description": "Rate limited. Honor Retry-After when present and back off." }, "500": { "description": "`server_error` — Something failed on our side. Retry reads with backoff; reconcile writes before retrying because a response can be lost after commit.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } } } } }, "/v1/expected-work/shipments/{id}/release": { "post": { "summary": "Release an unbooked shipment's order allocations", "description": "Expected work uses snake_case payloads. See docs/api/expected-work.md for validation, allocation and replay semantics. Lists return at most 1,000 records; imports accept at most 500 rows. Handler errors carry an error message; authentication errors also carry a code. No appointment, check-in or yard presence is created by intake.\n\n**Requires scope:** `orders:write`", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Order or shipment ID; its location must be visible to this key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "location_id": "dock-id" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "ok": true } } } }, "400": { "description": "`missing_parameter` — A required query parameter was not sent.\n\n`bad_range` — The from/to window is backwards or wider than 366 days.\n\n`too_many_rows` — The range holds more rows than one response may carry. Ask for less.\n\n`bad_value` — An enum or field value is invalid.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "401": { "description": "`no_credentials` — No Authorization header.\n\n`invalid_key` — The key is unknown, malformed or revoked. All three answer the same.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "403": { "description": "`missing_scope` — The key is live but was not given this permission. The response names what is missing.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "404": { "description": "`not_found` — No such facility, or one this key cannot see. Both answer the same.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "409": { "description": "`not_bookable` — The requested appointment conflicts with booking rules or capacity; helper validation may also return 400/404.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "429": { "description": "Rate limited. Honor Retry-After when present and back off." }, "500": { "description": "`server_error` — Something failed on our side. Retry reads with backoff; reconcile writes before retrying because a response can be lost after commit.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } } } } }, "/v1/facilities": { "get": { "summary": "List the docks this key can see", "description": "Where an integration starts. Every other endpoint takes a facilityId, and this is how you learn them. A key narrowed to particular sites sees only those.\n\n**Requires:** any live API key.", "security": [ { "apiKey": [] } ], "parameters": [], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "facilities": [ { "id": "0f8c1b2e-4a77-4b3d-9c21-8a6d5e4f1234", "name": "Main Dock", "site": "Fort Smith", "timezone": "America/Chicago" } ] } } } }, "400": { "description": "`missing_parameter` — A required query parameter was not sent.\n\n`bad_range` — The from/to window is backwards or wider than 366 days.\n\n`too_many_rows` — The range holds more rows than one response may carry. Ask for less.\n\n`bad_value` — An enum or field value is invalid.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "401": { "description": "`no_credentials` — No Authorization header.\n\n`invalid_key` — The key is unknown, malformed or revoked. All three answer the same.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "403": { "description": "`missing_scope` — The key is live but was not given this permission. The response names what is missing.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "404": { "description": "`not_found` — No such facility, or one this key cannot see. Both answer the same.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "409": { "description": "`not_bookable` — The requested appointment conflicts with booking rules or capacity; helper validation may also return 400/404.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "429": { "description": "Rate limited. Honor Retry-After when present and back off." }, "500": { "description": "`server_error` — Something failed on our side. Retry reads with backoff; reconcile writes before retrying because a response can be lost after commit.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } } } } }, "/v1/appointments": { "get": { "summary": "Scheduled arrivals at a dock", "description": "What is booked. Times are epoch milliseconds UTC; use the facility's timezone from GET /v1/facilities to render them in the dock's own day. Results are limited to the first 1,000 rows, ordered by start time, with no cursor; narrow the time window.\n\n**Requires scope:** `appointments:read`", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "locationId", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Which dock. Get these from GET /v1/facilities." }, { "name": "from", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Start of the window, epoch milliseconds UTC. Defaults to 90 days ago." }, { "name": "to", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "End of the window, epoch milliseconds UTC. Defaults to now. The window may not exceed 366 days." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "appointments": [ { "id": "3b9d0c11-6e2a-42f8-8f1a-2c7b5d9e0011", "facilityId": "0f8c1b2e-4a77-4b3d-9c21-8a6d5e4f1234", "startAt": 1700000000000, "status": "booked", "direction": "pickup", "carrier": "Priority1", "reference": "PO-44718", "equipmentId": "reefer-53" } ] } } } }, "400": { "description": "`missing_parameter` — A required query parameter was not sent.\n\n`bad_range` — The from/to window is backwards or wider than 366 days.\n\n`too_many_rows` — The range holds more rows than one response may carry. Ask for less.\n\n`bad_value` — An enum or field value is invalid.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "401": { "description": "`no_credentials` — No Authorization header.\n\n`invalid_key` — The key is unknown, malformed or revoked. All three answer the same.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "403": { "description": "`missing_scope` — The key is live but was not given this permission. The response names what is missing.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "404": { "description": "`not_found` — No such facility, or one this key cannot see. Both answer the same.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "409": { "description": "`not_bookable` — The requested appointment conflicts with booking rules or capacity; helper validation may also return 400/404.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "429": { "description": "Rate limited. Honor Retry-After when present and back off." }, "500": { "description": "`server_error` — Something failed on our side. Retry reads with backoff; reconcile writes before retrying because a response can be lost after commit.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } } } }, "post": { "summary": "Book a slot", "description": "Books a truck into one of this dock's times. Refused if the slot is full or is not one of the dock's booking times — the same checks the facility's own screen applies, because there is one answer to whether a dock is full.\n\n**serviceMethod is the field to map carefully.** It is how the truck is served at the dock — `live` (driver waits), `drop` (leaves the trailer), `hook` (drops one and takes another). It is NOT a TMS 'live shipment' flag meaning 'a real shipment rather than a quote'. It decides whether a driver is waiting at all, so map it deliberately rather than by name.\n\n`reference` is what the driver will quote at the gate to identify themselves. Without it they cannot check in.\n\n**Requires scope:** `appointments:write`", "security": [ { "apiKey": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "facilityId", "startAt", "carrier", "carrierKind", "direction", "serviceMethod", "reference" ], "properties": { "facilityId": { "type": "string", "maxLength": 36, "description": "Dock/location ID from GET /v1/facilities, not a plant ID." }, "startAt": { "type": "integer", "minimum": 1, "description": "UTC epoch milliseconds returned by GET /v1/slots." }, "carrier": { "type": "string", "minLength": 1, "maxLength": 100 }, "carrierKind": { "type": "string", "enum": [ "asset", "broker", "unknown" ] }, "direction": { "type": "string", "enum": [ "pickup", "delivery" ] }, "serviceMethod": { "type": "string", "enum": [ "live", "drop", "hook" ] }, "reference": { "type": "string", "minLength": 1, "maxLength": 50 }, "loadStopId": { "type": "string", "description": "Optional existing shipment stop. Books it without duplicating the load; must belong to facilityId and be unbooked." }, "brokerName": { "type": "string", "maxLength": 100 }, "contact": { "type": "string", "maxLength": 100 }, "phone": { "type": "string", "maxLength": 40 }, "email": { "type": "string", "maxLength": 200 }, "trailer": { "type": "string", "maxLength": 50 }, "equipmentId": { "type": "string", "maxLength": 40 }, "isReturn": { "type": "boolean", "default": false } } }, "example": { "facilityId": "dock-id", "startAt": 1790000000000, "carrier": "Example Carrier", "carrierKind": "asset", "direction": "pickup", "serviceMethod": "live", "reference": "PILOT-001" } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "example": { "id": "3b9d0c11-6e2a-42f8-8f1a-2c7b5d9e0011", "facilityId": "0f8c1b2e-4a77-4b3d-9c21-8a6d5e4f1234", "startAt": 1700000000000, "status": "booked", "reference": "PO-44718" } } } }, "400": { "description": "`missing_parameter` — A required query parameter was not sent.\n\n`bad_range` — The from/to window is backwards or wider than 366 days.\n\n`too_many_rows` — The range holds more rows than one response may carry. Ask for less.\n\n`bad_value` — An enum or field value is invalid.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "401": { "description": "`no_credentials` — No Authorization header.\n\n`invalid_key` — The key is unknown, malformed or revoked. All three answer the same.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "403": { "description": "`missing_scope` — The key is live but was not given this permission. The response names what is missing.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "404": { "description": "`not_found` — No such facility, or one this key cannot see. Both answer the same.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "409": { "description": "`not_bookable` — The requested appointment conflicts with booking rules or capacity; helper validation may also return 400/404.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "429": { "description": "Rate limited. Honor Retry-After when present and back off." }, "500": { "description": "`server_error` — Something failed on our side. Retry reads with backoff; reconcile writes before retrying because a response can be lost after commit.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } } } } }, "/v1/runs": { "get": { "summary": "Completed visits, with the minutes", "description": "What actually happened at the dock: when the truck arrived, when it was called, when loading started, when it left, and the minutes between. The minutes are computed by ROME from its own timestamps and are the same figures the facility sees. A null arrivedAt means nobody recorded the truck arriving — which is a real answer rather than a missing one. `departedAt` here maps to the dock history clearedAt timestamp, NOT a confirmed facility gate exit. Runs use a half-open [from,to) window and refuse more than 20,000 rows.\n\n**Requires scope:** `history:read`", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "facilityId", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Which dock. Get these from GET /v1/facilities." }, { "name": "from", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Start of the window, epoch milliseconds UTC. Defaults to 90 days ago." }, { "name": "to", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "End of the window, epoch milliseconds UTC. Defaults to now. The window may not exceed 366 days." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "runs": [ { "id": "9c2f7a30-1d55-4c9b-b0e7-5f4a8b3c2211", "facilityId": "0f8c1b2e-4a77-4b3d-9c21-8a6d5e4f1234", "trailer": "TR-9001", "carrier": "Priority1", "customer": "Brighton Foods", "reference": "PO-44718", "arrivedAt": 1699998800000, "calledAt": 1700000000000, "loadingAt": 1700002400000, "readyAt": 1700009000000, "departedAt": 1700010800000, "minutesToLoading": 40, "minutesToReady": 150, "minutesAtDoor": 180 } ] } } } }, "400": { "description": "`missing_parameter` — A required query parameter was not sent.\n\n`bad_range` — The from/to window is backwards or wider than 366 days.\n\n`too_many_rows` — The range holds more rows than one response may carry. Ask for less.\n\n`bad_value` — An enum or field value is invalid.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "401": { "description": "`no_credentials` — No Authorization header.\n\n`invalid_key` — The key is unknown, malformed or revoked. All three answer the same.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "403": { "description": "`missing_scope` — The key is live but was not given this permission. The response names what is missing.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "404": { "description": "`not_found` — No such facility, or one this key cannot see. Both answer the same.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "409": { "description": "`not_bookable` — The requested appointment conflicts with booking rules or capacity; helper validation may also return 400/404.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "429": { "description": "Rate limited. Honor Retry-After when present and back off." }, "500": { "description": "`server_error` — Something failed on our side. Retry reads with backoff; reconcile writes before retrying because a response can be lost after commit.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } } } } }, "/v1/slots": { "get": { "summary": "When a dock can take a truck", "description": "A dock's booking times are its own: an opening hour, a slot count, and how many trucks fit in each. Ask here before booking — an arbitrary time is refused.\n\n`date` is YYYY-MM-DD **in the facility's own timezone**, not yours. A slot belongs to the dock's day; midnight-to-midnight where you are would return the wrong morning to anybody a timezone away. Get the zone from GET /v1/facilities.\n\nSend `startAt` back to POST /v1/appointments exactly as given. Do not reconstruct it — rounding an hour in the wrong zone books a slot that does not exist.\n\n**Requires scope:** `appointments:read`", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "facilityId", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Which dock. Get these from GET /v1/facilities." }, { "name": "date", "in": "query", "required": false, "schema": { "type": "string" }, "description": "YYYY-MM-DD in the facility's timezone. Defaults to the dock's today." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "facilityId": "0f8c1b2e-4a77-4b3d-9c21-8a6d5e4f1234", "date": "2026-09-04", "timezone": "America/Chicago", "slots": [ { "startAt": 1700000000000, "capacity": 2, "booked": 1, "available": true }, { "startAt": 1700003600000, "capacity": 2, "booked": 2, "available": false } ] } } } }, "400": { "description": "`missing_parameter` — A required query parameter was not sent.\n\n`bad_range` — The from/to window is backwards or wider than 366 days.\n\n`too_many_rows` — The range holds more rows than one response may carry. Ask for less.\n\n`bad_value` — An enum or field value is invalid.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "401": { "description": "`no_credentials` — No Authorization header.\n\n`invalid_key` — The key is unknown, malformed or revoked. All three answer the same.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "403": { "description": "`missing_scope` — The key is live but was not given this permission. The response names what is missing.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "404": { "description": "`not_found` — No such facility, or one this key cannot see. Both answer the same.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "409": { "description": "`not_bookable` — The requested appointment conflicts with booking rules or capacity; helper validation may also return 400/404.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "429": { "description": "Rate limited. Honor Retry-After when present and back off." }, "500": { "description": "`server_error` — Something failed on our side. Retry reads with backoff; reconcile writes before retrying because a response can be lost after commit.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } } } } }, "/v1/appointments/{id}": { "delete": { "summary": "Cancel a booked slot", "description": "Releases the slot. The load and its orders are preserved — an appointment is a time held for a stop, not the shipment itself — so cancelling and rebooking does not lose anything.\n\n`reason` is required and must be at least ten characters. A cancelled slot is a truck that is not coming, and somebody at the dock will want to know why without ringing you.\n\n**Requires scope:** `appointments:write`", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The appointment to cancel." }, { "name": "reason", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Why. Ten characters minimum." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "ok": true } } } }, "400": { "description": "`missing_parameter` — A required query parameter was not sent.\n\n`bad_range` — The from/to window is backwards or wider than 366 days.\n\n`too_many_rows` — The range holds more rows than one response may carry. Ask for less.\n\n`bad_value` — An enum or field value is invalid.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "401": { "description": "`no_credentials` — No Authorization header.\n\n`invalid_key` — The key is unknown, malformed or revoked. All three answer the same.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "403": { "description": "`missing_scope` — The key is live but was not given this permission. The response names what is missing.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "404": { "description": "`not_found` — No such facility, or one this key cannot see. Both answer the same.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "409": { "description": "`not_bookable` — The requested appointment conflicts with booking rules or capacity; helper validation may also return 400/404.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } }, "429": { "description": "Rate limited. Honor Retry-After when present and back off." }, "500": { "description": "`server_error` — Something failed on our side. Retry reads with backoff; reconcile writes before retrying because a response can be lost after commit.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Readable by a person." }, "code": { "type": "string", "description": "Present on authentication and legacy v1 errors. Expected-work handler errors currently omit it." } } } } } } } } } } }