{"openapi":"3.1.0","info":{"title":"FR8 Factory Customer Data API","version":"1.0.0","description":"Read-only access to your own load data. Authenticate every request with your per-customer API key as a Bearer token; a key is scoped to exactly one customer and can never return another customer's loads."},"servers":[{"url":"/"}],"security":[{"bearerAuth":[]}],"paths":{"/api/v1/loads":{"get":{"operationId":"listLoads","summary":"List your loads","description":"Returns the authenticated customer's loads, stably ordered by (updatedAt, id) ascending. Poll with `updatedSince` set to the max `updatedAt` you've stored — the field only moves on real value changes, so an unchanged load never reappears in your delta.","security":[{"bearerAuth":[]}],"parameters":[{"name":"page","in":"query","required":false,"description":"1-based page number.","schema":{"type":"integer","minimum":1,"default":1}},{"name":"pageSize","in":"query","required":false,"description":"Rows per page. Values above 1000 clamp to 1000.","schema":{"type":"integer","minimum":1,"maximum":1000,"default":100}},{"name":"updatedSince","in":"query","required":false,"description":"ISO 8601 date or datetime; only loads with updatedAt >= this value return.","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"The customer's loads (page envelope).","headers":{"X-RateLimit-Limit":{"description":"Your key's per-minute request cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current rolling 60s window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix epoch seconds when the window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"loadNumber":{"type":"string","description":"FR8 Factory load number — the stable row identity to upsert on."},"poNumber":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Customer PO number."},"billingRefNumber":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Billing reference."},"originCity":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Pickup city."},"originState":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Pickup state (2-letter)."},"originZip":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Pickup ZIP."},"originWarehouse":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Pickup warehouse name, when the stop is a known warehouse."},"destinationCity":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Delivery city."},"destinationState":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Delivery state (2-letter)."},"destinationZip":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Delivery ZIP."},"destinationWarehouse":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Delivery warehouse name, when the stop is a known warehouse."},"status":{"type":"string","enum":["PrePlanning","Available","Covered","Dispatched","Loading","InTransit","Unloading","Delivered","Claims","PenApp","Completed","OnHold","Cancelled"],"description":"Load status — raw operational vocabulary; closed list."},"scheduledPickupDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Scheduled pickup appointment date (ISO 8601)."},"scheduledPickupTime":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Scheduled pickup appointment time (local, e.g. \"08:00\")."},"scheduledDeliveryDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Scheduled delivery appointment date (ISO 8601)."},"scheduledDeliveryTime":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Scheduled delivery appointment time (local, e.g. \"14:30\")."},"tenderedDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Date the load was tendered (ISO 8601)."},"actualPickupDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Actual pickup — driver checked in at origin (ISO 8601)."},"actualDeliveryDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Actual delivery — driver checked in at destination (ISO 8601)."},"requestedDeliveryDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Requested delivery date (ISO 8601)."},"miles":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Load miles, as a decimal string."},"totalCost":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Total cost (AR) — the invoice amount, as a decimal string."},"updatedAt":{"type":"string","format":"date-time","description":"Last value-affecting change (ISO 8601) — the updatedSince cursor."}},"required":["loadNumber","poNumber","billingRefNumber","originCity","originState","originZip","originWarehouse","destinationCity","destinationState","destinationZip","destinationWarehouse","status","scheduledPickupDate","scheduledPickupTime","scheduledDeliveryDate","scheduledDeliveryTime","tenderedDate","actualPickupDate","actualDeliveryDate","requestedDeliveryDate","miles","totalCost","updatedAt"],"additionalProperties":false}},"page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"1-based page number echoed back."},"pageSize":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Effective page size (post-clamp)."},"totalCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Total rows matching the query."},"hasMore":{"type":"boolean","description":"Whether a further page exists."}},"required":["data","page","pageSize","totalCount","hasMore"],"additionalProperties":false}}}},"400":{"description":"Invalid query parameters.","headers":{"X-RateLimit-Limit":{"description":"Your key's per-minute request cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current rolling 60s window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix epoch seconds when the window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"details":{"description":"Per-parameter validation messages (400 only).","type":"array","items":{"type":"string"}}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"Missing, malformed, unknown, or revoked API key — indistinguishable by design.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"details":{"description":"Per-parameter validation messages (400 only).","type":"array","items":{"type":"string"}}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"Per-key rate limit exceeded.","headers":{"X-RateLimit-Limit":{"description":"Your key's per-minute request cap.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current rolling 60s window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix epoch seconds when the window resets.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds until the window admits requests.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"details":{"description":"Per-parameter validation messages (400 only).","type":"array","items":{"type":"string"}}},"required":["error"],"additionalProperties":false}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"details":{"description":"Per-parameter validation messages (400 only).","type":"array","items":{"type":"string"}}},"required":["error"],"additionalProperties":false}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Per-customer API key (`fr8_live_…`), sent as `Authorization: Bearer <key>`. Issued by FR8 Factory ops; rotate by requesting a second key, cutting over, then revoking the old one."}}}}