{"openapi":"3.1.0","info":{"title":"Caspian EYE","description":"\n**Caspian EYE** is a Control Tower for multimodal freight across the\nTrans-Caspian / Middle Corridor. **By design the platform relies on real upstream\ndata** — live weather, AIS/port connectors, CSV upload, and partner ingestion —\nwith honest **`provenance`** on every observational field.\n\n**OpenAI is enrichment and fallback** (NLP, ETA/risk narratives), not the source\nof truth for wind, positions, or port congestion.\nSee `docs/technical/24-connectors-and-provenance.md`.\n\nThe endpoints **compose** — chaining documented combinations reproduces corridor\nlogistics intelligence. See `docs/WORKFLOWS.md`.\n\n**Try it:** authorize via `Authentication` → `/auth/token`\n(demo: `dispatcher` / `caspian-demo`), then call any endpoint.\n","contact":{"name":"Caspian EYE","url":"https://caspian-eye.io/"},"license":{"name":"Commercial-in-Confidence","identifier":"LicenseRef-CE"},"version":"1.0.0"},"paths":{"/api/v1/auth/token":{"post":{"tags":["Authentication"],"summary":"OAuth2 password grant","description":"Exchange username/password for an access + refresh token pair.","operationId":"issue_token_api_v1_auth_token_post","requestBody":{"content":{"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/Body_issue_token_api_v1_auth_token_post"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenResponse"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/api/v1/auth/token/client":{"post":{"tags":["Authentication"],"summary":"OAuth2 client credentials","description":"Machine-to-machine token for partner integrations (API_CLIENT role).","operationId":"issue_client_token_api_v1_auth_token_client_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientCredentialsRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenResponse"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/api/v1/auth/refresh":{"post":{"tags":["Authentication"],"summary":"Refresh an access token","operationId":"refresh_token_api_v1_auth_refresh_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefreshRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenResponse"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/api/v1/auth/me":{"get":{"tags":["Authentication"],"summary":"Current identity","operationId":"whoami_api_v1_auth_me_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrincipalInfo"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}},"security":[{"OAuth2Password":[]}]}},"/api/v1/auth/roles":{"get":{"tags":["Authentication"],"summary":"RBAC role catalog","operationId":"list_roles_api_v1_auth_roles_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/RoleInfo"},"type":"array","title":"Response List Roles Api V1 Auth Roles Get"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/api/v1/system/info":{"get":{"tags":["System"],"summary":"Service metadata","operationId":"info_api_v1_system_info_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SystemInfo"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/api/v1/system/stats":{"get":{"tags":["System"],"summary":"Simulated world statistics","operationId":"stats_api_v1_system_stats_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorldStats"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/api/v1/admin/organizations":{"get":{"tags":["Admin"],"summary":"List organizations","operationId":"list_organizations_api_v1_admin_organizations_get","security":[{"OAuth2Password":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"description":"Page size.","default":25,"title":"Limit"},"description":"Page size."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Opaque cursor from a previous page.","title":"Cursor"},"description":"Opaque cursor from a previous page."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_Organization_"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}},"post":{"tags":["Admin"],"summary":"Create organization","operationId":"create_organization_api_v1_admin_organizations_post","security":[{"OAuth2Password":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationCreate"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Organization"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/api/v1/admin/organizations/{org_id}":{"get":{"tags":["Admin"],"summary":"Get organization","operationId":"get_organization_api_v1_admin_organizations__org_id__get","security":[{"OAuth2Password":[]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","title":"Org Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Organization"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/api/v1/admin/users":{"get":{"tags":["Admin"],"summary":"List users","operationId":"list_users_api_v1_admin_users_get","security":[{"OAuth2Password":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"description":"Page size.","default":25,"title":"Limit"},"description":"Page size."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Opaque cursor from a previous page.","title":"Cursor"},"description":"Opaque cursor from a previous page."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_User_"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}},"post":{"tags":["Admin"],"summary":"Create user","operationId":"create_user_api_v1_admin_users_post","security":[{"OAuth2Password":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserCreate"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/api/v1/admin/users/{user_id}":{"get":{"tags":["Admin"],"summary":"Get user","operationId":"get_user_api_v1_admin_users__user_id__get","security":[{"OAuth2Password":[]}],"parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string","title":"User Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}},"patch":{"tags":["Admin"],"summary":"Update user","operationId":"patch_user_api_v1_admin_users__user_id__patch","security":[{"OAuth2Password":[]}],"parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string","title":"User Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserPatch"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/api/v1/shipments":{"get":{"tags":["Shipments"],"summary":"List/search shipments","operationId":"list_shipments_api_v1_shipments_get","security":[{"OAuth2Password":[]}],"parameters":[{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/ShipmentStatus"},{"type":"null"}],"title":"Status"}},{"name":"risk_level","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/RiskLevel"},{"type":"null"}],"title":"Risk Level"}},{"name":"origin_location_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Origin Location Id"}},{"name":"destination_location_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Destination Location Id"}},{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Search ref/commodity.","title":"Q"},"description":"Search ref/commodity."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"description":"Page size.","default":25,"title":"Limit"},"description":"Page size."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Opaque cursor from a previous page.","title":"Cursor"},"description":"Opaque cursor from a previous page."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_Shipment_"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}},"post":{"tags":["Shipments"],"summary":"Create a shipment","operationId":"create_shipment_api_v1_shipments_post","security":[{"OAuth2Password":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShipmentCreate"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Shipment"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/api/v1/shipments/{shipment_id}":{"get":{"tags":["Shipments"],"summary":"Get shipment detail","operationId":"get_shipment_api_v1_shipments__shipment_id__get","security":[{"OAuth2Password":[]}],"parameters":[{"name":"shipment_id","in":"path","required":true,"schema":{"type":"string","title":"Shipment Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShipmentDetail"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}},"patch":{"tags":["Shipments"],"summary":"Update a shipment","operationId":"patch_shipment_api_v1_shipments__shipment_id__patch","security":[{"OAuth2Password":[]}],"parameters":[{"name":"shipment_id","in":"path","required":true,"schema":{"type":"string","title":"Shipment Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShipmentPatch"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Shipment"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/api/v1/shipments/{shipment_id}/legs":{"get":{"tags":["Shipments"],"summary":"Shipment legs","operationId":"get_legs_api_v1_shipments__shipment_id__legs_get","security":[{"OAuth2Password":[]}],"parameters":[{"name":"shipment_id","in":"path","required":true,"schema":{"type":"string","title":"Shipment Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Leg"},"title":"Response Get Legs Api V1 Shipments  Shipment Id  Legs Get"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/api/v1/shipments/{shipment_id}/containers":{"get":{"tags":["Shipments"],"summary":"Shipment containers","operationId":"get_containers_api_v1_shipments__shipment_id__containers_get","security":[{"OAuth2Password":[]}],"parameters":[{"name":"shipment_id","in":"path","required":true,"schema":{"type":"string","title":"Shipment Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Container"},"title":"Response Get Containers Api V1 Shipments  Shipment Id  Containers Get"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/api/v1/shipments/{shipment_id}/events":{"get":{"tags":["Shipments"],"summary":"Shipment events","operationId":"get_events_api_v1_shipments__shipment_id__events_get","security":[{"OAuth2Password":[]}],"parameters":[{"name":"shipment_id","in":"path","required":true,"schema":{"type":"string","title":"Shipment Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"description":"Page size.","default":25,"title":"Limit"},"description":"Page size."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Opaque cursor from a previous page.","title":"Cursor"},"description":"Opaque cursor from a previous page."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_Event_"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/api/v1/shipments/{shipment_id}/timeline":{"get":{"tags":["Shipments"],"summary":"Shipment timeline","operationId":"get_timeline_api_v1_shipments__shipment_id__timeline_get","security":[{"OAuth2Password":[]}],"parameters":[{"name":"shipment_id","in":"path","required":true,"schema":{"type":"string","title":"Shipment Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Timeline"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/api/v1/shipments/{shipment_id}/route":{"get":{"tags":["Shipments"],"summary":"Shipment route (GeoJSON)","operationId":"get_route_api_v1_shipments__shipment_id__route_get","security":[{"OAuth2Password":[]}],"parameters":[{"name":"shipment_id","in":"path","required":true,"schema":{"type":"string","title":"Shipment Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShipmentRoute"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/api/v1/shipments/{shipment_id}/documents":{"get":{"tags":["Shipments"],"summary":"Shipment documents","operationId":"get_documents_api_v1_shipments__shipment_id__documents_get","security":[{"OAuth2Password":[]}],"parameters":[{"name":"shipment_id","in":"path","required":true,"schema":{"type":"string","title":"Shipment Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ShipmentDocument"},"title":"Response Get Documents Api V1 Shipments  Shipment Id  Documents Get"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/api/v1/shipments/{shipment_id}/eta":{"get":{"tags":["Shipments"],"summary":"Shipment ETA","operationId":"get_eta_api_v1_shipments__shipment_id__eta_get","security":[{"OAuth2Password":[]}],"parameters":[{"name":"shipment_id","in":"path","required":true,"schema":{"type":"string","title":"Shipment Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EtaPrediction"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/api/v1/shipments/{shipment_id}/eta/history":{"get":{"tags":["Shipments"],"summary":"ETA evolution history","operationId":"get_eta_history_api_v1_shipments__shipment_id__eta_history_get","security":[{"OAuth2Password":[]}],"parameters":[{"name":"shipment_id","in":"path","required":true,"schema":{"type":"string","title":"Shipment Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/EtaHistoryPoint"},"title":"Response Get Eta History Api V1 Shipments  Shipment Id  Eta History Get"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/api/v1/shipments/{shipment_id}/eta/override":{"post":{"tags":["Shipments"],"summary":"Override ETA (cascades to risk)","operationId":"override_eta_api_v1_shipments__shipment_id__eta_override_post","security":[{"OAuth2Password":[]}],"parameters":[{"name":"shipment_id","in":"path","required":true,"schema":{"type":"string","title":"Shipment Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EtaOverrideRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EtaPrediction"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/api/v1/shipments/{shipment_id}/risk":{"get":{"tags":["Shipments"],"summary":"Shipment risk","operationId":"get_risk_api_v1_shipments__shipment_id__risk_get","security":[{"OAuth2Password":[]}],"parameters":[{"name":"shipment_id","in":"path","required":true,"schema":{"type":"string","title":"Shipment Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskBreakdown"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/api/v1/shipments/{shipment_id}/weather":{"get":{"tags":["Shipments"],"summary":"Weather along the route","operationId":"get_weather_api_v1_shipments__shipment_id__weather_get","security":[{"OAuth2Password":[]}],"parameters":[{"name":"shipment_id","in":"path","required":true,"schema":{"type":"string","title":"Shipment Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouteWeather"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/api/v1/legs/{leg_id}":{"get":{"tags":["Legs"],"summary":"Get a leg","operationId":"get_leg_api_v1_legs__leg_id__get","security":[{"OAuth2Password":[]}],"parameters":[{"name":"leg_id","in":"path","required":true,"schema":{"type":"string","title":"Leg Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Leg"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}},"patch":{"tags":["Legs"],"summary":"Update a leg","operationId":"patch_leg_api_v1_legs__leg_id__patch","security":[{"OAuth2Password":[]}],"parameters":[{"name":"leg_id","in":"path","required":true,"schema":{"type":"string","title":"Leg Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegPatch"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Leg"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/api/v1/containers":{"get":{"tags":["Containers"],"summary":"List containers","operationId":"list_containers_api_v1_containers_get","security":[{"OAuth2Password":[]}],"parameters":[{"name":"shipment_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Shipment Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"description":"Page size.","default":25,"title":"Limit"},"description":"Page size."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Opaque cursor from a previous page.","title":"Cursor"},"description":"Opaque cursor from a previous page."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_Container_"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/api/v1/containers/{container_id}":{"get":{"tags":["Containers"],"summary":"Get a container","operationId":"get_container_api_v1_containers__container_id__get","security":[{"OAuth2Password":[]}],"parameters":[{"name":"container_id","in":"path","required":true,"schema":{"type":"string","title":"Container Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Container"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/api/v1/assets":{"get":{"tags":["Assets & Tracking"],"summary":"List assets (live positions)","operationId":"list_assets_api_v1_assets_get","security":[{"OAuth2Password":[]}],"parameters":[{"name":"type","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/AssetType"},{"type":"null"}],"title":"Type"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"description":"Page size.","default":25,"title":"Limit"},"description":"Page size."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Opaque cursor from a previous page.","title":"Cursor"},"description":"Opaque cursor from a previous page."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_Asset_"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/api/v1/assets/{asset_id}":{"get":{"tags":["Assets & Tracking"],"summary":"Get an asset","operationId":"get_asset_api_v1_assets__asset_id__get","security":[{"OAuth2Password":[]}],"parameters":[{"name":"asset_id","in":"path","required":true,"schema":{"type":"string","title":"Asset Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Asset"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/api/v1/assets/{asset_id}/position":{"get":{"tags":["Assets & Tracking"],"summary":"Latest position","operationId":"get_latest_position_api_v1_assets__asset_id__position_get","security":[{"OAuth2Password":[]}],"parameters":[{"name":"asset_id","in":"path","required":true,"schema":{"type":"string","title":"Asset Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Position"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/api/v1/assets/{asset_id}/positions":{"get":{"tags":["Assets & Tracking"],"summary":"Position history (track)","operationId":"get_positions_api_v1_assets__asset_id__positions_get","security":[{"OAuth2Password":[]}],"parameters":[{"name":"asset_id","in":"path","required":true,"schema":{"type":"string","title":"Asset Id"}},{"name":"since","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Since"}},{"name":"until","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Until"}},{"name":"step_minutes","in":"query","required":false,"schema":{"type":"integer","maximum":240,"minimum":5,"default":30,"title":"Step Minutes"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Position"},"title":"Response Get Positions Api V1 Assets  Asset Id  Positions Get"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/api/v1/locations":{"get":{"tags":["Locations & Ports"],"summary":"List locations","operationId":"list_locations_api_v1_locations_get","security":[{"OAuth2Password":[]}],"parameters":[{"name":"type","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/LocationType"},{"type":"null"}],"title":"Type"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"description":"Page size.","default":25,"title":"Limit"},"description":"Page size."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Opaque cursor from a previous page.","title":"Cursor"},"description":"Opaque cursor from a previous page."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_Location_"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/api/v1/locations/{location_id}":{"get":{"tags":["Locations & Ports"],"summary":"Get a location","operationId":"get_location_api_v1_locations__location_id__get","security":[{"OAuth2Password":[]}],"parameters":[{"name":"location_id","in":"path","required":true,"schema":{"type":"string","title":"Location Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Location"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/api/v1/ports":{"get":{"tags":["Locations & Ports"],"summary":"List ports (with congestion)","operationId":"list_ports_api_v1_ports_get","security":[{"OAuth2Password":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"description":"Page size.","default":25,"title":"Limit"},"description":"Page size."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Opaque cursor from a previous page.","title":"Cursor"},"description":"Opaque cursor from a previous page."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_Port_"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/api/v1/ports/{location_id}":{"get":{"tags":["Locations & Ports"],"summary":"Get a port","operationId":"get_port_api_v1_ports__location_id__get","security":[{"OAuth2Password":[]}],"parameters":[{"name":"location_id","in":"path","required":true,"schema":{"type":"string","title":"Location Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Port"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/api/v1/ports/{location_id}/status":{"get":{"tags":["Locations & Ports"],"summary":"Port congestion status","operationId":"get_port_status_api_v1_ports__location_id__status_get","security":[{"OAuth2Password":[]}],"parameters":[{"name":"location_id","in":"path","required":true,"schema":{"type":"string","title":"Location Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortStatus"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/api/v1/ports/{location_id}/lineup":{"get":{"tags":["Locations & Ports"],"summary":"Port vessel lineup","operationId":"get_port_lineup_api_v1_ports__location_id__lineup_get","security":[{"OAuth2Password":[]}],"parameters":[{"name":"location_id","in":"path","required":true,"schema":{"type":"string","title":"Location Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/VesselLineupEntry"},"title":"Response Get Port Lineup Api V1 Ports  Location Id  Lineup Get"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/api/v1/events":{"get":{"tags":["Events"],"summary":"List/filter events","operationId":"list_events_api_v1_events_get","security":[{"OAuth2Password":[]}],"parameters":[{"name":"shipment_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Shipment Id"}},{"name":"event_type","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/EventType"},{"type":"null"}],"title":"Event Type"}},{"name":"source","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/EventSource"},{"type":"null"}],"title":"Source"}},{"name":"exceptions_only","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Exceptions Only"}},{"name":"since","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Since"}},{"name":"until","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Until"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"description":"Page size.","default":25,"title":"Limit"},"description":"Page size."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Opaque cursor from a previous page.","title":"Cursor"},"description":"Opaque cursor from a previous page."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_Event_"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}},"post":{"tags":["Events"],"summary":"Submit a manual event","operationId":"create_event_api_v1_events_post","security":[{"OAuth2Password":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventCreate"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/api/v1/events/taxonomy":{"get":{"tags":["Events"],"summary":"Event-type taxonomy","operationId":"get_taxonomy_api_v1_events_taxonomy_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/EventTaxonomyEntry"},"type":"array","title":"Response Get Taxonomy Api V1 Events Taxonomy Get"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}},"security":[{"OAuth2Password":[]}]}},"/api/v1/events/{event_id}":{"get":{"tags":["Events"],"summary":"Get an event","operationId":"get_event_api_v1_events__event_id__get","security":[{"OAuth2Password":[]}],"parameters":[{"name":"event_id","in":"path","required":true,"schema":{"type":"string","title":"Event Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/api/v1/eta/predict":{"post":{"tags":["ETA Prediction"],"summary":"Predict ETA (formula + optional AI factors)","description":"Compute a baseline ETA then enrich it with explainable factors (AI when configured).","operationId":"predict_eta_api_v1_eta_predict_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EtaPredictRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EtaPrediction"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}},"security":[{"OAuth2Password":[]}]}},"/api/v1/eta/overdue":{"get":{"tags":["ETA Prediction"],"summary":"Materially-delayed ETAs","operationId":"overdue_api_v1_eta_overdue_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/EtaPrediction"},"type":"array","title":"Response Overdue Api V1 Eta Overdue Get"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}},"security":[{"OAuth2Password":[]}]}},"/api/v1/risk/score":{"post":{"tags":["Risk Assessment"],"summary":"Score risk (formula + optional AI narrative)","description":"Composite weighted score with explainable factor breakdown.","operationId":"score_risk_api_v1_risk_score_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskScoreRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskBreakdown"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}},"security":[{"OAuth2Password":[]}]}},"/api/v1/risk/summary":{"get":{"tags":["Risk Assessment"],"summary":"Fleet-wide risk distribution","operationId":"risk_summary_api_v1_risk_summary_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskSummary"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}},"security":[{"OAuth2Password":[]}]}},"/api/v1/risk/heatmap":{"get":{"tags":["Risk Assessment"],"summary":"Geographic risk heatmap","operationId":"risk_heatmap_api_v1_risk_heatmap_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskHeatmap"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}},"security":[{"OAuth2Password":[]}]}},"/api/v1/nlp/classify":{"post":{"tags":["NLP Event Processing"],"summary":"Classify a message (AI enrichment + fallback)","description":"Classify free text into the event taxonomy and correlate it to a shipment.","operationId":"classify_api_v1_nlp_classify_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClassifyRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClassifyResponse"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}},"security":[{"OAuth2Password":[]}]}},"/api/v1/nlp/extract":{"post":{"tags":["NLP Event Processing"],"summary":"Extract entities (AI enrichment + fallback)","operationId":"extract_api_v1_nlp_extract_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExtractRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExtractResponse"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}},"security":[{"OAuth2Password":[]}]}},"/api/v1/nlp/detect-language":{"post":{"tags":["NLP Event Processing"],"summary":"Detect language","operationId":"detect_language_api_v1_nlp_detect_language_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetectLanguageRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetectLanguageResponse"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}},"security":[{"OAuth2Password":[]}]}},"/api/v1/nlp/ingest":{"post":{"tags":["NLP Event Processing"],"summary":"Ingest message -> classified event","description":"Classify a message and, when correlated, post it as an event on the timeline.","operationId":"ingest_api_v1_nlp_ingest_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestResponse"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}},"security":[{"OAuth2Password":[]}]}},"/api/v1/dashboard/summary":{"get":{"tags":["Dashboard"],"summary":"Operational summary","operationId":"summary_api_v1_dashboard_summary_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DashboardSummary"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}},"security":[{"OAuth2Password":[]}]}},"/api/v1/dashboard/kpis":{"get":{"tags":["Dashboard"],"summary":"Key performance indicators","operationId":"kpis_api_v1_dashboard_kpis_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/Kpi"},"type":"array","title":"Response Kpis Api V1 Dashboard Kpis Get"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}},"security":[{"OAuth2Password":[]}]}},"/api/v1/dashboard/arrivals":{"get":{"tags":["Dashboard"],"summary":"Upcoming arrivals","operationId":"arrivals_api_v1_dashboard_arrivals_get","security":[{"OAuth2Password":[]}],"parameters":[{"name":"hours","in":"query","required":false,"schema":{"type":"integer","maximum":168,"minimum":1,"default":24,"title":"Hours"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ArrivalItem"},"title":"Response Arrivals Api V1 Dashboard Arrivals Get"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/api/v1/dashboard/exceptions":{"get":{"tags":["Dashboard"],"summary":"Open exceptions","operationId":"exceptions_api_v1_dashboard_exceptions_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/ExceptionItem"},"type":"array","title":"Response Exceptions Api V1 Dashboard Exceptions Get"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}},"security":[{"OAuth2Password":[]}]}},"/api/v1/dashboard/feeds":{"get":{"tags":["Dashboard"],"summary":"Upstream feed health","operationId":"feeds_api_v1_dashboard_feeds_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/FeedStatus"},"type":"array","title":"Response Feeds Api V1 Dashboard Feeds Get"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}},"security":[{"OAuth2Password":[]}]}},"/api/v1/ingestion/upload":{"post":{"tags":["Data Ingestion"],"summary":"Upload CSV/XLSX shipment manifest","operationId":"upload_api_v1_ingestion_upload_post","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_upload_api_v1_ingestion_upload_post"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadResponse"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}},"security":[{"OAuth2Password":[]}]}},"/api/v1/ingestion/templates":{"get":{"tags":["Data Ingestion"],"summary":"Upload templates","operationId":"templates_api_v1_ingestion_templates_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/UploadTemplate"},"type":"array","title":"Response Templates Api V1 Ingestion Templates Get"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}},"security":[{"OAuth2Password":[]}]}},"/api/v1/ingestion/connectors":{"get":{"tags":["Data Ingestion"],"summary":"Connector status","operationId":"connectors_api_v1_ingestion_connectors_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/ConnectorStatus"},"type":"array","title":"Response Connectors Api V1 Ingestion Connectors Get"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}},"security":[{"OAuth2Password":[]}]}},"/api/v1/ingestion/webhooks":{"get":{"tags":["Data Ingestion"],"summary":"List webhooks","operationId":"list_webhooks_api_v1_ingestion_webhooks_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/WebhookSubscription"},"type":"array","title":"Response List Webhooks Api V1 Ingestion Webhooks Get"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}},"security":[{"OAuth2Password":[]}]},"post":{"tags":["Data Ingestion"],"summary":"Register a webhook","operationId":"create_webhook_api_v1_ingestion_webhooks_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookCreate"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSubscription"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}},"security":[{"OAuth2Password":[]}]}},"/api/v1/ingestion/webhooks/{hook_id}":{"delete":{"tags":["Data Ingestion"],"summary":"Delete a webhook","operationId":"delete_webhook_api_v1_ingestion_webhooks__hook_id__delete","security":[{"OAuth2Password":[]}],"parameters":[{"name":"hook_id","in":"path","required":true,"schema":{"type":"string","title":"Hook Id"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/api/v1/ingestion/webhooks/{hook_id}/test":{"post":{"tags":["Data Ingestion"],"summary":"Test a webhook","operationId":"test_webhook_api_v1_ingestion_webhooks__hook_id__test_post","security":[{"OAuth2Password":[]}],"parameters":[{"name":"hook_id","in":"path","required":true,"schema":{"type":"string","title":"Hook Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookTestResult"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/api/v1/ingestion/events":{"post":{"tags":["Data Ingestion"],"summary":"Inbound partner event push","operationId":"push_event_api_v1_ingestion_events_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InboundEventPush"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}},"security":[{"OAuth2Password":[]}]}},"/api/v1/weather/location/{location_id}":{"get":{"tags":["Weather"],"summary":"Weather at a location","operationId":"location_weather_api_v1_weather_location__location_id__get","security":[{"OAuth2Password":[]}],"parameters":[{"name":"location_id","in":"path","required":true,"schema":{"type":"string","title":"Location Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarineWeather"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/api/v1/weather/shipment/{shipment_id}":{"get":{"tags":["Weather"],"summary":"Weather along a route","operationId":"shipment_weather_api_v1_weather_shipment__shipment_id__get","security":[{"OAuth2Password":[]}],"parameters":[{"name":"shipment_id","in":"path","required":true,"schema":{"type":"string","title":"Shipment Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouteWeather"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/api/v1/notifications":{"get":{"tags":["Notifications"],"summary":"List notifications","operationId":"list_notifications_api_v1_notifications_get","security":[{"OAuth2Password":[]}],"parameters":[{"name":"unacknowledged_only","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Unacknowledged Only"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"description":"Page size.","default":25,"title":"Limit"},"description":"Page size."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Opaque cursor from a previous page.","title":"Cursor"},"description":"Opaque cursor from a previous page."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_Notification_"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/api/v1/notifications/subscribe":{"post":{"tags":["Notifications"],"summary":"Subscribe to alerts","operationId":"subscribe_api_v1_notifications_subscribe_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotificationSubscribe"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotificationSubscription"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}},"security":[{"OAuth2Password":[]}]}},"/api/v1/notifications/{notification_id}/ack":{"post":{"tags":["Notifications"],"summary":"Acknowledge an alert","operationId":"acknowledge_api_v1_notifications__notification_id__ack_post","security":[{"OAuth2Password":[]}],"parameters":[{"name":"notification_id","in":"path","required":true,"schema":{"type":"string","title":"Notification Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AckResponse"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/health":{"get":{"tags":["System"],"summary":"Health check","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/health/ready":{"get":{"tags":["System"],"summary":"Readiness probe","operationId":"readiness_health_ready_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReadinessResponse"}}}},"400":{"description":"Bad request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Authentication required or token invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Insufficient role/organization permissions.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Resource not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Conflict (e.g. optimistic-concurrency version mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"422":{"description":"Request validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Upstream dependency (AI provider) unavailable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}}},"components":{"schemas":{"AckResponse":{"properties":{"id":{"type":"string","title":"Id","examples":["ntf_0007"]},"acknowledged":{"type":"boolean","title":"Acknowledged","examples":[true]}},"type":"object","required":["id","acknowledged"],"title":"AckResponse"},"ArrivalItem":{"properties":{"shipment_id":{"type":"string","title":"Shipment Id"},"external_ref":{"type":"string","title":"External Ref"},"destination_location_id":{"type":"string","title":"Destination Location Id"},"eta":{"type":"string","format":"date-time","title":"Eta"},"risk_level":{"$ref":"#/components/schemas/RiskLevel"}},"type":"object","required":["shipment_id","external_ref","destination_location_id","eta","risk_level"],"title":"ArrivalItem"},"Asset":{"properties":{"id":{"type":"string","title":"Id","examples":["ast_vessel_01"]},"type":{"$ref":"#/components/schemas/AssetType"},"name":{"type":"string","title":"Name","examples":["MV Turan"]},"imo_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Imo Number","description":"IMO (vessels).","examples":["9123456"]},"mmsi":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mmsi","description":"AIS MMSI.","examples":["273345000"]},"flag_state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Flag State","description":"ISO 3166-1 alpha-3.","examples":["KAZ"]},"operator":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Operator","examples":["KazMorTransFlot"]},"current_position":{"anyOf":[{"$ref":"#/components/schemas/GeoPoint"},{"type":"null"}]},"position_updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Position Updated At"},"speed_knots":{"anyOf":[{"type":"number","minimum":0.0},{"type":"null"}],"title":"Speed Knots","examples":[12.4]},"heading":{"anyOf":[{"type":"number","maximum":360.0,"minimum":0.0},{"type":"null"}],"title":"Heading","examples":[214.0]},"status":{"$ref":"#/components/schemas/AssetStatus","default":"ACTIVE"}},"type":"object","required":["id","type","name"],"title":"Asset","description":"A physical transport asset: vessel, train, or truck."},"AssetStatus":{"type":"string","enum":["ACTIVE","IDLE","MAINTENANCE","DECOMMISSIONED"],"title":"AssetStatus"},"AssetType":{"type":"string","enum":["VESSEL","TRAIN","TRUCK","BARGE"],"title":"AssetType"},"Body_issue_token_api_v1_auth_token_post":{"properties":{"grant_type":{"anyOf":[{"type":"string","pattern":"^password$"},{"type":"null"}],"title":"Grant Type"},"username":{"type":"string","title":"Username"},"password":{"type":"string","format":"password","title":"Password"},"scope":{"type":"string","title":"Scope","default":""},"client_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Client Id"},"client_secret":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"password","title":"Client Secret"}},"type":"object","required":["username","password"],"title":"Body_issue_token_api_v1_auth_token_post"},"Body_upload_api_v1_ingestion_upload_post":{"properties":{"file":{"type":"string","contentMediaType":"application/octet-stream","title":"File","description":"CSV or XLSX manifest."}},"type":"object","required":["file"],"title":"Body_upload_api_v1_ingestion_upload_post"},"ClassifyRequest":{"properties":{"text":{"type":"string","minLength":3,"title":"Text","examples":["MV Turan delayed 12h at Aktau due to berth congestion."]},"language_hint":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language Hint","examples":["en","ru","kk"]}},"type":"object","required":["text"],"title":"ClassifyRequest","description":"Classify an unstructured message into the event taxonomy (spec §5.3.1)."},"ClassifyResponse":{"properties":{"event_type":{"$ref":"#/components/schemas/EventType"},"event_subtype":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Event Subtype"},"confidence":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Confidence"},"detected_language":{"type":"string","title":"Detected Language","examples":["en"]},"entities":{"items":{"$ref":"#/components/schemas/ExtractedEntity"},"type":"array","title":"Entities"},"matched_shipment_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Matched Shipment Id","description":"Shipment the event was correlated to, if any."},"rationale":{"type":"string","title":"Rationale","examples":["Mentions delay and port congestion."]},"generated_by":{"type":"string","title":"Generated By","examples":["ai","fallback"]}},"type":"object","required":["event_type","confidence","detected_language","entities","rationale","generated_by"],"title":"ClassifyResponse"},"ClientCredentialsRequest":{"properties":{"client_id":{"type":"string","title":"Client Id","examples":["partner-tms"]},"client_secret":{"type":"string","title":"Client Secret","examples":["..."]},"organization_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Organization Id"}},"type":"object","required":["client_id","client_secret"],"title":"ClientCredentialsRequest","description":"Machine-to-machine token request (spec §6.3 client_credentials grant)."},"ConfidenceInterval":{"properties":{"low":{"type":"string","format":"date-time","title":"Low"},"high":{"type":"string","format":"date-time","title":"High"},"level":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Level","default":0.8}},"type":"object","required":["low","high"],"title":"ConfidenceInterval","description":"An 80% confidence window for arrival (spec §5.2.2)."},"ConnectorMode":{"type":"string","enum":["live","simulated","disabled"],"title":"ConnectorMode","description":"Per-domain connector operating mode."},"ConnectorStatus":{"properties":{"name":{"type":"string","title":"Name","examples":["AIS Connector"]},"type":{"type":"string","title":"Type","examples":["AIS","WEATHER","PORT_FEED","EMAIL","WEBHOOK"]},"status":{"type":"string","title":"Status","examples":["CONNECTED","DEGRADED","DISCONNECTED"]},"mode":{"$ref":"#/components/schemas/ConnectorMode","examples":["live"]},"provider":{"type":"string","title":"Provider","examples":["MarineTraffic"]},"last_event_at":{"type":"string","format":"date-time","title":"Last Event At"},"events_ingested_24h":{"type":"integer","minimum":0.0,"title":"Events Ingested 24H"},"lag_seconds":{"type":"number","minimum":0.0,"title":"Lag Seconds"},"simulated_health":{"type":"boolean","title":"Simulated Health","description":"True when HEALTHY/CONNECTED status reflects simulated feed, not live poll.","default":false,"examples":[false]}},"type":"object","required":["name","type","status","mode","provider","last_event_at","events_ingested_24h","lag_seconds"],"title":"ConnectorStatus","description":"Status of an ingestion connector (spec §5.1.1-§5.1.3)."},"Container":{"properties":{"id":{"type":"string","title":"Id","examples":["cnt_01"]},"container_number":{"type":"string","maxLength":11,"minLength":11,"title":"Container Number","description":"ISO 6346 number.","examples":["MSCU1234567"]},"type":{"$ref":"#/components/schemas/ContainerType"},"shipment_id":{"type":"string","title":"Shipment Id"},"current_leg_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Current Leg Id"},"seal_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Seal Number","examples":["SEAL-88213"]},"weight_kg":{"anyOf":[{"type":"number","minimum":0.0},{"type":"null"}],"title":"Weight Kg","examples":[18450.0]},"teu":{"type":"number","maximum":4.0,"minimum":0.0,"title":"Teu","examples":[2.0]}},"type":"object","required":["id","container_number","type","shipment_id","teu"],"title":"Container","description":"An intermodal container."},"ContainerType":{"type":"string","enum":["20DC","40DC","40HC","20RF","40RF","FLAT","OPEN_TOP"],"title":"ContainerType"},"DashboardSummary":{"properties":{"active_shipments":{"type":"integer","title":"Active Shipments","examples":[28]},"by_status":{"additionalProperties":{"type":"integer"},"propertyNames":{"$ref":"#/components/schemas/ShipmentStatus"},"type":"object","title":"By Status","examples":[{"AT_PORT":6,"DELIVERED":9,"IN_TRANSIT":22,"PLANNED":3}]},"by_risk_level":{"additionalProperties":{"type":"integer"},"propertyNames":{"$ref":"#/components/schemas/RiskLevel"},"type":"object","title":"By Risk Level","examples":[{"CRITICAL":3,"HIGH":7,"LOW":14,"MEDIUM":16}]},"exceptions_count":{"type":"integer","title":"Exceptions Count","examples":[5]},"on_time_percentage":{"type":"number","maximum":100.0,"minimum":0.0,"title":"On Time Percentage","examples":[87.5]},"delayed_count":{"type":"integer","title":"Delayed Count","examples":[5]},"arrivals_next_24h":{"type":"integer","title":"Arrivals Next 24H","examples":[4]},"average_risk_score":{"type":"number","maximum":100.0,"minimum":0.0,"title":"Average Risk Score","examples":[48.7]},"total_teu_in_transit":{"type":"number","title":"Total Teu In Transit","examples":[1240.0]},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["active_shipments","by_status","by_risk_level","exceptions_count","on_time_percentage","delayed_count","arrivals_next_24h","average_risk_score","total_teu_in_transit","updated_at"],"title":"DashboardSummary","description":"Top-level operational picture (spec §5.5.1)."},"DataProvenance":{"type":"string","enum":["live","simulated","ai","fallback","manual","derived"],"title":"DataProvenance","description":"Explicit origin of a numeric/observational field (ADR 006)."},"DetectLanguageRequest":{"properties":{"text":{"type":"string","minLength":1,"title":"Text"}},"type":"object","required":["text"],"title":"DetectLanguageRequest"},"DetectLanguageResponse":{"properties":{"language":{"type":"string","title":"Language","examples":["ru"]},"confidence":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Confidence"}},"type":"object","required":["language","confidence"],"title":"DetectLanguageResponse"},"EntityType":{"type":"string","enum":["VESSEL","IMO","PORT","CONTAINER","DATETIME","DELAY_DURATION","ORGANIZATION"],"title":"EntityType"},"EtaFactor":{"properties":{"name":{"type":"string","title":"Name","examples":["Port congestion at destination"]},"impact_hours":{"type":"number","title":"Impact Hours","description":"Signed hours added(+)/removed(-) from the baseline.","examples":[6.5]},"weight":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Weight","examples":[0.35]},"description":{"type":"string","title":"Description","examples":["Aktau berth queue averaging 14h over the last 72h."]}},"type":"object","required":["name","impact_hours","weight","description"],"title":"EtaFactor","description":"A single contributing factor to an AI ETA adjustment (spec §5.2.2)."},"EtaHistoryPoint":{"properties":{"recorded_at":{"type":"string","format":"date-time","title":"Recorded At"},"eta":{"type":"string","format":"date-time","title":"Eta"},"confidence":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Confidence"},"source":{"$ref":"#/components/schemas/EtaSource"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason"}},"type":"object","required":["recorded_at","eta","confidence","source"],"title":"EtaHistoryPoint","description":"A historical ETA snapshot for the evolution chart (spec §5.5.3)."},"EtaOverrideRequest":{"properties":{"eta":{"type":"string","format":"date-time","title":"Eta"},"reason_code":{"type":"string","title":"Reason Code","examples":["LOCAL_KNOWLEDGE","AGENT_REPORT","PORT_NOTICE"]},"justification":{"type":"string","minLength":3,"title":"Justification","examples":["Agent confirms berth available on arrival."]}},"type":"object","required":["eta","reason_code","justification"],"title":"EtaOverrideRequest","description":"Manual ETA override request body (spec §5.2.4)."},"EtaPredictRequest":{"properties":{"origin_location_id":{"type":"string","title":"Origin Location Id"},"destination_location_id":{"type":"string","title":"Destination Location Id"},"mode":{"$ref":"#/components/schemas/TransportMode"},"departure":{"type":"string","format":"date-time","title":"Departure"},"asset_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Asset Id"}},"type":"object","required":["origin_location_id","destination_location_id","mode","departure"],"title":"EtaPredictRequest","description":"Ad-hoc ETA prediction request (spec §6.2 POST /eta/predict)."},"EtaPrediction":{"properties":{"shipment_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Shipment Id"},"leg_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Leg Id"},"baseline_eta":{"type":"string","format":"date-time","title":"Baseline Eta"},"current_eta":{"type":"string","format":"date-time","title":"Current Eta"},"confidence":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Confidence","examples":[0.78]},"confidence_interval":{"$ref":"#/components/schemas/ConfidenceInterval"},"adjustment_hours":{"type":"number","title":"Adjustment Hours","description":"current_eta - baseline_eta in hours.","examples":[6.5]},"factors":{"items":{"$ref":"#/components/schemas/EtaFactor"},"type":"array","title":"Factors"},"generated_by":{"$ref":"#/components/schemas/EtaSource"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["baseline_eta","current_eta","confidence","confidence_interval","adjustment_hours","factors","generated_by","updated_at"],"title":"EtaPrediction","description":"The current ETA for a leg or shipment with explainability."},"EtaSource":{"type":"string","enum":["baseline","ai","override","fallback"],"title":"EtaSource"},"Event":{"properties":{"id":{"type":"string","title":"Id","examples":["evt_01"]},"shipment_id":{"type":"string","title":"Shipment Id"},"leg_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Leg Id"},"event_type":{"$ref":"#/components/schemas/EventType"},"event_subtype":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Event Subtype"},"category":{"type":"string","title":"Category","examples":["Port"]},"occurred_at":{"type":"string","format":"date-time","title":"Occurred At"},"detected_at":{"type":"string","format":"date-time","title":"Detected At"},"source":{"$ref":"#/components/schemas/EventSource"},"confidence":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Confidence","examples":[0.92]},"location":{"anyOf":[{"$ref":"#/components/schemas/GeoPoint"},{"type":"null"}]},"payload":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Payload"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"is_exception":{"type":"boolean","title":"Is Exception","default":false}},"type":"object","required":["id","shipment_id","event_type","category","occurred_at","detected_at","source","confidence"],"title":"Event","description":"A state change, milestone, or exception in the transport lifecycle."},"EventCreate":{"properties":{"shipment_id":{"type":"string","title":"Shipment Id"},"leg_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Leg Id"},"event_type":{"$ref":"#/components/schemas/EventType"},"event_subtype":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Event Subtype"},"occurred_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Occurred At","description":"Defaults to now (UTC) if omitted."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"payload":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Payload"}},"type":"object","required":["shipment_id","event_type"],"title":"EventCreate","description":"Request body to submit a manual event (spec §6.2 POST /events)."},"EventSource":{"type":"string","enum":["AIS","PORT_EDI","RAIL_API","GPS","MANUAL","EMAIL","NLP_INFERRED"],"title":"EventSource"},"EventTaxonomyEntry":{"properties":{"category":{"type":"string","title":"Category"},"event_type":{"$ref":"#/components/schemas/EventType"},"description":{"type":"string","title":"Description"},"is_exception":{"type":"boolean","title":"Is Exception"}},"type":"object","required":["category","event_type","description","is_exception"],"title":"EventTaxonomyEntry","description":"A documented entry of the event-type taxonomy (spec §4.3)."},"EventType":{"type":"string","enum":["VESSEL_DEPARTED","TRAIN_DEPARTED","TRUCK_DEPARTED","VESSEL_ARRIVED","TRAIN_ARRIVED","TRUCK_ARRIVED","PORT_ENTRY","BERTH_ASSIGNED","BERTH_CHANGE","PORT_EXIT","CONTAINER_LOADED","CONTAINER_DISCHARGED","TRANSSHIPMENT","CUSTOMS_HOLD","CUSTOMS_CLEARED","INSPECTION_REQUIRED","DELAY_WEATHER","DELAY_PORT_CONGESTION","DELAY_MECHANICAL","ROUTE_DEVIATION","DOCUMENT_RECEIVED","ETA_UPDATED","STATUS_OVERRIDE"],"title":"EventType"},"ExceptionItem":{"properties":{"shipment_id":{"type":"string","title":"Shipment Id"},"external_ref":{"type":"string","title":"External Ref"},"event_type":{"type":"string","title":"Event Type"},"severity":{"$ref":"#/components/schemas/RiskLevel"},"description":{"type":"string","title":"Description"},"occurred_at":{"type":"string","format":"date-time","title":"Occurred At"}},"type":"object","required":["shipment_id","external_ref","event_type","severity","description","occurred_at"],"title":"ExceptionItem"},"ExtractRequest":{"properties":{"text":{"type":"string","minLength":3,"title":"Text"}},"type":"object","required":["text"],"title":"ExtractRequest"},"ExtractResponse":{"properties":{"detected_language":{"type":"string","title":"Detected Language"},"entities":{"items":{"$ref":"#/components/schemas/ExtractedEntity"},"type":"array","title":"Entities"},"generated_by":{"type":"string","title":"Generated By"}},"type":"object","required":["detected_language","entities","generated_by"],"title":"ExtractResponse"},"ExtractedEntity":{"properties":{"type":{"$ref":"#/components/schemas/EntityType"},"value":{"type":"string","title":"Value","examples":["MV Turan"]},"normalized":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Normalized","description":"Canonical reference (e.g. location id).","examples":["loc_aktau"]},"confidence":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Confidence","examples":[0.9]}},"type":"object","required":["type","value","confidence"],"title":"ExtractedEntity","description":"A named entity extracted from unstructured text (spec §5.3.2)."},"FeedStatus":{"properties":{"name":{"type":"string","title":"Name","examples":["AIS Stream"]},"source":{"type":"string","title":"Source","examples":["AIS","WEATHER","PORT_EDI","RAIL_API","EMAIL"]},"status":{"type":"string","title":"Status","examples":["HEALTHY","DEGRADED","DOWN"]},"last_event_at":{"type":"string","format":"date-time","title":"Last Event At"},"lag_seconds":{"type":"number","minimum":0.0,"title":"Lag Seconds"},"events_per_minute":{"type":"number","minimum":0.0,"title":"Events Per Minute"}},"type":"object","required":["name","source","status","last_event_at","lag_seconds","events_per_minute"],"title":"FeedStatus","description":"Health of an upstream data feed (spec §5.5.1, §5.1)."},"GeoLineString":{"properties":{"type":{"type":"string","title":"Type","default":"LineString"},"coordinates":{"items":{"items":{"type":"number"},"type":"array"},"type":"array","title":"Coordinates","description":"Ordered [longitude, latitude] vertices."}},"type":"object","required":["coordinates"],"title":"GeoLineString","description":"A GeoJSON LineString feature for routes."},"GeoPoint":{"properties":{"latitude":{"type":"number","maximum":90.0,"minimum":-90.0,"title":"Latitude","examples":[43.65]},"longitude":{"type":"number","maximum":180.0,"minimum":-180.0,"title":"Longitude","examples":[51.16]}},"type":"object","required":["latitude","longitude"],"title":"GeoPoint","description":"A WGS84 coordinate."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"HealthResponse":{"properties":{"status":{"type":"string","title":"Status","examples":["ok"]},"version":{"type":"string","title":"Version"},"environment":{"type":"string","title":"Environment"},"ai_active":{"type":"boolean","title":"Ai Active"},"time":{"type":"string","format":"date-time","title":"Time"}},"type":"object","required":["status","version","environment","ai_active","time"],"title":"HealthResponse"},"HeatmapCell":{"properties":{"latitude":{"type":"number","maximum":90.0,"minimum":-90.0,"title":"Latitude"},"longitude":{"type":"number","maximum":180.0,"minimum":-180.0,"title":"Longitude"},"segment":{"type":"string","title":"Segment","examples":["Aktau - Baku (sea)"]},"risk_score":{"type":"number","maximum":100.0,"minimum":0.0,"title":"Risk Score"},"shipment_count":{"type":"integer","minimum":0.0,"title":"Shipment Count"},"level":{"$ref":"#/components/schemas/RiskLevel"}},"type":"object","required":["latitude","longitude","segment","risk_score","shipment_count","level"],"title":"HeatmapCell","description":"A geographic risk-concentration cell (spec §5.4.3)."},"InboundEventPush":{"properties":{"shipment_id":{"type":"string","title":"Shipment Id","examples":["shp_00001"]},"event_type":{"$ref":"#/components/schemas/EventType"},"source":{"$ref":"#/components/schemas/EventSource","examples":["PORT_EDI"]},"occurred_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Occurred At"},"leg_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Leg Id"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"payload":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Payload"}},"type":"object","required":["shipment_id","event_type","source"],"title":"InboundEventPush","description":"Partner push payload for inbound event ingestion (connector Phase 4)."},"IngestRequest":{"properties":{"text":{"type":"string","minLength":3,"title":"Text"},"create_event":{"type":"boolean","title":"Create Event","description":"Create an event on the matched shipment.","default":true}},"type":"object","required":["text"],"title":"IngestRequest","description":"Classify a free-text message and post it as an event (spec §5.3)."},"IngestResponse":{"properties":{"classification":{"$ref":"#/components/schemas/ClassifyResponse"},"created_event":{"anyOf":[{"$ref":"#/components/schemas/Event"},{"type":"null"}]}},"type":"object","required":["classification"],"title":"IngestResponse","description":"Result of NLP ingestion: the classification and any event it produced."},"Kpi":{"properties":{"key":{"type":"string","title":"Key","examples":["eta_accuracy"]},"label":{"type":"string","title":"Label","examples":["ETA accuracy (7d)"]},"value":{"type":"number","title":"Value"},"unit":{"type":"string","title":"Unit","examples":["%","h","count"]},"trend":{"type":"number","title":"Trend","description":"Change vs previous period.","examples":[2.4]}},"type":"object","required":["key","label","value","unit","trend"],"title":"Kpi"},"Leg":{"properties":{"id":{"type":"string","title":"Id","examples":["leg_01"]},"shipment_id":{"type":"string","title":"Shipment Id"},"sequence":{"type":"integer","minimum":1.0,"title":"Sequence","description":"Order within the shipment.","examples":[1]},"mode":{"$ref":"#/components/schemas/TransportMode"},"status":{"$ref":"#/components/schemas/LegStatus"},"asset_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Asset Id"},"origin_location_id":{"type":"string","title":"Origin Location Id"},"destination_location_id":{"type":"string","title":"Destination Location Id"},"planned_departure":{"type":"string","format":"date-time","title":"Planned Departure"},"actual_departure":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Actual Departure"},"planned_arrival":{"type":"string","format":"date-time","title":"Planned Arrival"},"actual_arrival":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Actual Arrival"},"current_eta":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Current Eta"},"distance_km":{"anyOf":[{"type":"number","minimum":0.0},{"type":"null"}],"title":"Distance Km","examples":[412.0]}},"type":"object","required":["id","shipment_id","sequence","mode","status","origin_location_id","destination_location_id","planned_departure","planned_arrival"],"title":"Leg","description":"A single-mode transport segment within a multimodal shipment."},"LegPatch":{"properties":{"status":{"anyOf":[{"$ref":"#/components/schemas/LegStatus"},{"type":"null"}]},"asset_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Asset Id"},"actual_departure":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Actual Departure"},"actual_arrival":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Actual Arrival"},"current_eta":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Current Eta"}},"type":"object","title":"LegPatch","description":"Partial update for a leg."},"LegStatus":{"type":"string","enum":["PLANNED","ACTIVE","COMPLETED","CANCELLED"],"title":"LegStatus"},"Location":{"properties":{"id":{"type":"string","title":"Id","examples":["loc_aktau"]},"name":{"type":"string","title":"Name","examples":["Port of Aktau"]},"type":{"$ref":"#/components/schemas/LocationType"},"country":{"type":"string","maxLength":3,"minLength":3,"title":"Country","description":"ISO 3166-1 alpha-3.","examples":["KAZ"]},"unlocode":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Unlocode","description":"UN/LOCODE.","examples":["KZAKT"]},"position":{"$ref":"#/components/schemas/GeoPoint"},"timezone":{"type":"string","title":"Timezone","default":"UTC","examples":["Asia/Aqtau"]}},"type":"object","required":["id","name","type","country","position"],"title":"Location","description":"A canonical place: port, terminal, junction, warehouse, border, city."},"LocationType":{"type":"string","enum":["PORT","TERMINAL","RAIL_JUNCTION","WAREHOUSE","BORDER_CROSSING","CITY"],"title":"LocationType"},"MarineWeather":{"properties":{"position":{"$ref":"#/components/schemas/GeoPoint"},"wind_speed_knots":{"type":"number","minimum":0.0,"title":"Wind Speed Knots","examples":[18.0]},"wind_direction_deg":{"type":"number","maximum":360.0,"minimum":0.0,"title":"Wind Direction Deg","examples":[230.0]},"wave_height_m":{"type":"number","minimum":0.0,"title":"Wave Height M","examples":[1.6]},"visibility_km":{"type":"number","minimum":0.0,"title":"Visibility Km","examples":[9.0]},"sea_state":{"type":"integer","maximum":9.0,"minimum":0.0,"title":"Sea State","description":"Douglas sea scale.","examples":[3]},"temperature_c":{"type":"number","title":"Temperature C","examples":[12.5]},"observed_at":{"type":"string","format":"date-time","title":"Observed At"},"provenance":{"$ref":"#/components/schemas/DataProvenance","default":"simulated","examples":["live"]},"provider":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Provider","examples":["open_meteo"]}},"type":"object","required":["position","wind_speed_knots","wind_direction_deg","wave_height_m","visibility_km","sea_state","temperature_c","observed_at"],"title":"MarineWeather","description":"A marine weather observation correlated to a position (spec §5.1.2)."},"Notification":{"properties":{"id":{"type":"string","title":"Id"},"shipment_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Shipment Id"},"level":{"$ref":"#/components/schemas/RiskLevel"},"type":{"type":"string","title":"Type","examples":["RISK_ESCALATION","ETA_SHIFT","EXCEPTION"]},"message":{"type":"string","title":"Message"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"acknowledged":{"type":"boolean","title":"Acknowledged","default":false}},"type":"object","required":["id","level","type","message","created_at"],"title":"Notification","description":"An in-app alert (spec §5.4.2)."},"NotificationSubscribe":{"properties":{"risk_levels":{"items":{"$ref":"#/components/schemas/RiskLevel"},"type":"array","title":"Risk Levels"},"channels":{"items":{"type":"string"},"type":"array","title":"Channels","examples":[["in_app","email","webhook"]]},"shipment_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Shipment Id"}},"type":"object","title":"NotificationSubscribe","description":"Subscribe to alerts (spec §5.4.2)."},"NotificationSubscription":{"properties":{"id":{"type":"string","title":"Id"},"risk_levels":{"items":{"$ref":"#/components/schemas/RiskLevel"},"type":"array","title":"Risk Levels"},"channels":{"items":{"type":"string"},"type":"array","title":"Channels"},"shipment_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Shipment Id"},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["id","risk_levels","channels","created_at"],"title":"NotificationSubscription"},"Organization":{"properties":{"id":{"type":"string","title":"Id","examples":["org_titr_logistics"]},"name":{"type":"string","title":"Name","examples":["TITR Logistics LLP"]},"country":{"type":"string","maxLength":3,"minLength":3,"title":"Country","examples":["KAZ"]},"tier":{"type":"string","title":"Tier","examples":["OPERATOR","PARTNER","CLIENT"]},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["id","name","country","tier","created_at"],"title":"Organization","description":"A tenant organization (spec §4.2.1 organization_id)."},"OrganizationCreate":{"properties":{"name":{"type":"string","minLength":2,"title":"Name"},"country":{"type":"string","maxLength":3,"minLength":3,"title":"Country"},"tier":{"type":"string","title":"Tier","default":"CLIENT"}},"type":"object","required":["name","country"],"title":"OrganizationCreate"},"PageMeta":{"properties":{"total":{"type":"integer","title":"Total","description":"Total number of matching items.","examples":[137]},"count":{"type":"integer","title":"Count","description":"Number of items in this page.","examples":[25]},"limit":{"type":"integer","title":"Limit","description":"Requested page size.","examples":[25]},"has_more":{"type":"boolean","title":"Has More","description":"Whether more pages exist."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Opaque cursor for the next page, or null at the end."}},"type":"object","required":["total","count","limit","has_more"],"title":"PageMeta","description":"Pagination envelope metadata."},"Page_Asset_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Asset"},"type":"array","title":"Data"},"meta":{"$ref":"#/components/schemas/PageMeta"}},"type":"object","required":["data","meta"],"title":"Page[Asset]"},"Page_Container_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Container"},"type":"array","title":"Data"},"meta":{"$ref":"#/components/schemas/PageMeta"}},"type":"object","required":["data","meta"],"title":"Page[Container]"},"Page_Event_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Event"},"type":"array","title":"Data"},"meta":{"$ref":"#/components/schemas/PageMeta"}},"type":"object","required":["data","meta"],"title":"Page[Event]"},"Page_Location_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Location"},"type":"array","title":"Data"},"meta":{"$ref":"#/components/schemas/PageMeta"}},"type":"object","required":["data","meta"],"title":"Page[Location]"},"Page_Notification_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Notification"},"type":"array","title":"Data"},"meta":{"$ref":"#/components/schemas/PageMeta"}},"type":"object","required":["data","meta"],"title":"Page[Notification]"},"Page_Organization_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Organization"},"type":"array","title":"Data"},"meta":{"$ref":"#/components/schemas/PageMeta"}},"type":"object","required":["data","meta"],"title":"Page[Organization]"},"Page_Port_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Port"},"type":"array","title":"Data"},"meta":{"$ref":"#/components/schemas/PageMeta"}},"type":"object","required":["data","meta"],"title":"Page[Port]"},"Page_Shipment_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Shipment"},"type":"array","title":"Data"},"meta":{"$ref":"#/components/schemas/PageMeta"}},"type":"object","required":["data","meta"],"title":"Page[Shipment]"},"Page_User_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/User"},"type":"array","title":"Data"},"meta":{"$ref":"#/components/schemas/PageMeta"}},"type":"object","required":["data","meta"],"title":"Page[User]"},"Port":{"properties":{"location":{"$ref":"#/components/schemas/Location"},"status":{"$ref":"#/components/schemas/PortStatus"}},"type":"object","required":["location","status"],"title":"Port","description":"A port: its location plus live operational status."},"PortStatus":{"properties":{"berths_total":{"type":"integer","minimum":0.0,"title":"Berths Total","examples":[6]},"berths_occupied":{"type":"integer","minimum":0.0,"title":"Berths Occupied","examples":[4]},"vessels_at_anchor":{"type":"integer","minimum":0.0,"title":"Vessels At Anchor","examples":[3]},"vessels_expected_24h":{"type":"integer","minimum":0.0,"title":"Vessels Expected 24H","examples":[5]},"congestion_index":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Congestion Index","description":"0=clear, 1=fully congested.","examples":[0.62]},"avg_wait_hours":{"type":"number","minimum":0.0,"title":"Avg Wait Hours","examples":[14.5]},"updated_at":{"type":"string","format":"date-time","title":"Updated At"},"provenance":{"$ref":"#/components/schemas/DataProvenance","default":"simulated","examples":["live"]},"provider":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Provider","examples":["port_edi"]}},"type":"object","required":["berths_total","berths_occupied","vessels_at_anchor","vessels_expected_24h","congestion_index","avg_wait_hours","updated_at"],"title":"PortStatus","description":"Operational status / congestion snapshot for a port (spec §5.5.2)."},"Position":{"properties":{"time":{"type":"string","format":"date-time","title":"Time"},"asset_id":{"type":"string","title":"Asset Id"},"latitude":{"type":"number","maximum":90.0,"minimum":-90.0,"title":"Latitude"},"longitude":{"type":"number","maximum":180.0,"minimum":-180.0,"title":"Longitude"},"speed_knots":{"anyOf":[{"type":"number","minimum":0.0},{"type":"null"}],"title":"Speed Knots"},"heading":{"anyOf":[{"type":"number","maximum":360.0,"minimum":0.0},{"type":"null"}],"title":"Heading"},"source":{"$ref":"#/components/schemas/PositionSource","default":"AIS"},"provenance":{"$ref":"#/components/schemas/DataProvenance","default":"simulated","examples":["live"]},"provider":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Provider","examples":["marine_traffic"]}},"type":"object","required":["time","asset_id","latitude","longitude"],"title":"Position","description":"A single time-stamped position record (TimescaleDB hypertable row)."},"PositionSource":{"type":"string","enum":["AIS","GPS","MANUAL"],"title":"PositionSource"},"PrincipalInfo":{"properties":{"subject":{"type":"string","title":"Subject"},"role":{"$ref":"#/components/schemas/UserRole"},"organization_id":{"type":"string","title":"Organization Id"},"scopes":{"items":{"type":"string"},"type":"array","title":"Scopes"}},"type":"object","required":["subject","role","organization_id","scopes"],"title":"PrincipalInfo","description":"The authenticated caller (GET /auth/me)."},"ReadinessCheck":{"properties":{"name":{"type":"string","title":"Name","examples":["world","ai","redis"]},"ok":{"type":"boolean","title":"Ok","examples":[true]},"detail":{"type":"string","title":"Detail","examples":["seeded world available"]}},"type":"object","required":["name","ok","detail"],"title":"ReadinessCheck","description":"Result of a single dependency probe."},"ReadinessResponse":{"properties":{"status":{"type":"string","title":"Status","examples":["ready","degraded","not_ready"]},"version":{"type":"string","title":"Version","examples":["1.0.0"]},"checks":{"items":{"$ref":"#/components/schemas/ReadinessCheck"},"type":"array","title":"Checks"},"time":{"type":"string","format":"date-time","title":"Time"}},"type":"object","required":["status","version","checks","time"],"title":"ReadinessResponse","description":"Readiness probe (GET /health/ready) — world + AI + optional Redis."},"RefreshRequest":{"properties":{"refresh_token":{"type":"string","title":"Refresh Token"}},"type":"object","required":["refresh_token"],"title":"RefreshRequest"},"RiskBreakdown":{"properties":{"shipment_id":{"type":"string","title":"Shipment Id"},"score":{"type":"number","maximum":100.0,"minimum":0.0,"title":"Score","examples":[63.4]},"level":{"$ref":"#/components/schemas/RiskLevel"},"factors":{"items":{"$ref":"#/components/schemas/RiskFactor"},"type":"array","title":"Factors"},"summary":{"type":"string","title":"Summary","examples":["Elevated risk driven by port congestion and weather."]},"generated_by":{"type":"string","title":"Generated By","examples":["ai","fallback"]},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["shipment_id","score","level","factors","summary","generated_by","updated_at"],"title":"RiskBreakdown","description":"A shipment's composite risk score with factor breakdown (spec §5.4.1)."},"RiskFactor":{"properties":{"name":{"type":"string","title":"Name","examples":["ETA deviation from plan"]},"weight":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Weight","examples":[0.3]},"value":{"type":"number","maximum":100.0,"minimum":0.0,"title":"Value","description":"Raw factor severity 0-100.","examples":[72.0]},"contribution":{"type":"number","maximum":100.0,"minimum":0.0,"title":"Contribution","description":"weight * value contribution to the score.","examples":[21.6]},"description":{"type":"string","title":"Description","examples":["Projected 9h late versus plan."]}},"type":"object","required":["name","weight","value","contribution","description"],"title":"RiskFactor","description":"A weighted risk contributor (spec §5.4.1)."},"RiskHeatmap":{"properties":{"cells":{"items":{"$ref":"#/components/schemas/HeatmapCell"},"type":"array","title":"Cells"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["cells","updated_at"],"title":"RiskHeatmap"},"RiskLevel":{"type":"string","enum":["LOW","MEDIUM","HIGH","CRITICAL"],"title":"RiskLevel"},"RiskScoreRequest":{"properties":{"shipment_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Shipment Id"},"eta_deviation_hours":{"type":"number","title":"Eta Deviation Hours","default":0.0,"examples":[9.0]},"weather_severity":{"type":"number","maximum":100.0,"minimum":0.0,"title":"Weather Severity","default":0.0,"examples":[40.0]},"port_congestion":{"type":"number","maximum":100.0,"minimum":0.0,"title":"Port Congestion","default":0.0,"examples":[62.0]},"customs_risk":{"type":"number","maximum":100.0,"minimum":0.0,"title":"Customs Risk","default":0.0,"examples":[20.0]},"asset_reliability":{"type":"number","maximum":100.0,"minimum":0.0,"title":"Asset Reliability","default":80.0,"examples":[80.0]},"cargo_sensitivity":{"type":"number","maximum":100.0,"minimum":0.0,"title":"Cargo Sensitivity","default":0.0,"examples":[50.0]}},"type":"object","title":"RiskScoreRequest","description":"Ad-hoc risk scoring request (spec §6.2 POST /risk/score)."},"RiskSummary":{"properties":{"total":{"type":"integer","title":"Total","examples":[40]},"average_score":{"type":"number","maximum":100.0,"minimum":0.0,"title":"Average Score","examples":[48.7]},"by_level":{"additionalProperties":{"type":"integer"},"propertyNames":{"$ref":"#/components/schemas/RiskLevel"},"type":"object","title":"By Level","examples":[{"CRITICAL":3,"HIGH":7,"LOW":14,"MEDIUM":16}]},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["total","average_score","by_level","updated_at"],"title":"RiskSummary","description":"Fleet-wide risk distribution (spec §5.4.2)."},"RoleInfo":{"properties":{"role":{"$ref":"#/components/schemas/UserRole"},"description":{"type":"string","title":"Description"},"rate_limit_per_minute":{"type":"integer","title":"Rate Limit Per Minute"}},"type":"object","required":["role","description","rate_limit_per_minute"],"title":"RoleInfo","description":"An RBAC role definition (GET /roles)."},"RouteFeature":{"properties":{"type":{"type":"string","title":"Type","default":"Feature"},"geometry":{"$ref":"#/components/schemas/GeoLineString"},"properties":{"type":"object","title":"Properties"}},"type":"object","required":["geometry"],"title":"RouteFeature","description":"A GeoJSON Feature wrapping a route line with properties."},"RouteWeather":{"properties":{"shipment_id":{"type":"string","title":"Shipment Id"},"points":{"items":{"$ref":"#/components/schemas/RouteWeatherPoint"},"type":"array","title":"Points"}},"type":"object","required":["shipment_id","points"],"title":"RouteWeather"},"RouteWeatherPoint":{"properties":{"location_id":{"type":"string","title":"Location Id"},"weather":{"$ref":"#/components/schemas/MarineWeather"}},"type":"object","required":["location_id","weather"],"title":"RouteWeatherPoint"},"Shipment":{"properties":{"id":{"type":"string","title":"Id","examples":["shp_0001"]},"external_ref":{"type":"string","title":"External Ref","examples":["CE-BKG-20260101-0001"]},"status":{"$ref":"#/components/schemas/ShipmentStatus"},"origin_location_id":{"type":"string","title":"Origin Location Id"},"destination_location_id":{"type":"string","title":"Destination Location Id"},"commodity":{"type":"string","title":"Commodity","examples":["Polypropylene granulate"]},"planned_departure":{"type":"string","format":"date-time","title":"Planned Departure"},"planned_arrival":{"type":"string","format":"date-time","title":"Planned Arrival"},"current_eta":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Current Eta"},"eta_confidence":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Eta Confidence","examples":[0.78]},"risk_score":{"type":"number","maximum":100.0,"minimum":0.0,"title":"Risk Score","examples":[63.4]},"risk_level":{"$ref":"#/components/schemas/RiskLevel","default":"LOW"},"teu_total":{"type":"number","minimum":0.0,"title":"Teu Total","examples":[8.0]},"container_count":{"type":"integer","minimum":0.0,"title":"Container Count","examples":[4]},"organization_id":{"type":"string","title":"Organization Id"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"},"version":{"type":"integer","minimum":1.0,"title":"Version","default":1}},"type":"object","required":["id","external_ref","status","origin_location_id","destination_location_id","commodity","planned_departure","planned_arrival","risk_score","teu_total","container_count","organization_id","created_at","updated_at"],"title":"Shipment","description":"End-to-end multimodal transport order (summary view)."},"ShipmentCreate":{"properties":{"external_ref":{"type":"string","minLength":3,"title":"External Ref","examples":["CE-BKG-20260101-0042"]},"origin_location_id":{"type":"string","title":"Origin Location Id"},"destination_location_id":{"type":"string","title":"Destination Location Id"},"commodity":{"type":"string","minLength":2,"title":"Commodity","examples":["Wheat"]},"planned_departure":{"type":"string","format":"date-time","title":"Planned Departure"},"planned_arrival":{"type":"string","format":"date-time","title":"Planned Arrival"},"mode_sequence":{"items":{"$ref":"#/components/schemas/TransportMode"},"type":"array","title":"Mode Sequence","description":"Ordered modes that define the legs."},"container_count":{"type":"integer","maximum":500.0,"minimum":1.0,"title":"Container Count","default":1},"organization_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Organization Id","description":"Defaults to the caller's organization."}},"type":"object","required":["external_ref","origin_location_id","destination_location_id","commodity","planned_departure","planned_arrival"],"title":"ShipmentCreate","description":"Create-shipment request body (spec §6.2 POST /shipments)."},"ShipmentDetail":{"properties":{"id":{"type":"string","title":"Id","examples":["shp_0001"]},"external_ref":{"type":"string","title":"External Ref","examples":["CE-BKG-20260101-0001"]},"status":{"$ref":"#/components/schemas/ShipmentStatus"},"origin_location_id":{"type":"string","title":"Origin Location Id"},"destination_location_id":{"type":"string","title":"Destination Location Id"},"commodity":{"type":"string","title":"Commodity","examples":["Polypropylene granulate"]},"planned_departure":{"type":"string","format":"date-time","title":"Planned Departure"},"planned_arrival":{"type":"string","format":"date-time","title":"Planned Arrival"},"current_eta":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Current Eta"},"eta_confidence":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Eta Confidence","examples":[0.78]},"risk_score":{"type":"number","maximum":100.0,"minimum":0.0,"title":"Risk Score","examples":[63.4]},"risk_level":{"$ref":"#/components/schemas/RiskLevel","default":"LOW"},"teu_total":{"type":"number","minimum":0.0,"title":"Teu Total","examples":[8.0]},"container_count":{"type":"integer","minimum":0.0,"title":"Container Count","examples":[4]},"organization_id":{"type":"string","title":"Organization Id"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"},"version":{"type":"integer","minimum":1.0,"title":"Version","default":1},"legs":{"items":{"$ref":"#/components/schemas/Leg"},"type":"array","title":"Legs"},"containers":{"items":{"$ref":"#/components/schemas/Container"},"type":"array","title":"Containers"},"recent_events":{"items":{"$ref":"#/components/schemas/Event"},"type":"array","title":"Recent Events"},"eta":{"anyOf":[{"$ref":"#/components/schemas/EtaPrediction"},{"type":"null"}]},"risk":{"anyOf":[{"$ref":"#/components/schemas/RiskBreakdown"},{"type":"null"}]}},"type":"object","required":["id","external_ref","status","origin_location_id","destination_location_id","commodity","planned_departure","planned_arrival","risk_score","teu_total","container_count","organization_id","created_at","updated_at","legs","containers","recent_events"],"title":"ShipmentDetail","description":"Full shipment view with related entities (spec §5.5.3)."},"ShipmentDocument":{"properties":{"id":{"type":"string","title":"Id"},"shipment_id":{"type":"string","title":"Shipment Id"},"name":{"type":"string","title":"Name","examples":["Bill_of_Lading.pdf"]},"doc_type":{"type":"string","title":"Doc Type","examples":["BILL_OF_LADING","PACKING_LIST","CUSTOMS_DECLARATION"]},"uploaded_at":{"type":"string","format":"date-time","title":"Uploaded At"},"size_kb":{"type":"integer","minimum":0.0,"title":"Size Kb"},"url":{"type":"string","title":"Url","examples":["https://docs.caspian-eye.io/files/blo_0001.pdf"]}},"type":"object","required":["id","shipment_id","name","doc_type","uploaded_at","size_kb","url"],"title":"ShipmentDocument","description":"An associated document (spec §5.5.3)."},"ShipmentPatch":{"properties":{"status":{"anyOf":[{"$ref":"#/components/schemas/ShipmentStatus"},{"type":"null"}]},"commodity":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Commodity"},"planned_arrival":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Planned Arrival"},"version":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Version","description":"Optimistic concurrency token."}},"type":"object","title":"ShipmentPatch","description":"Partial shipment update (spec §6.2 PATCH /shipments/{id})."},"ShipmentRoute":{"properties":{"shipment_id":{"type":"string","title":"Shipment Id"},"features":{"items":{"$ref":"#/components/schemas/RouteFeature"},"type":"array","title":"Features"}},"type":"object","required":["shipment_id","features"],"title":"ShipmentRoute","description":"The shipment's planned route as GeoJSON (spec §5.5.2)."},"ShipmentStatus":{"type":"string","enum":["CREATED","IN_TRANSIT","AT_PORT","ON_RAIL","ON_TRUCK","DELIVERED","CANCELLED","EXCEPTION"],"title":"ShipmentStatus"},"SystemInfo":{"properties":{"name":{"type":"string","title":"Name","examples":["Caspian EYE"]},"version":{"type":"string","title":"Version","examples":["1.0.0"]},"environment":{"type":"string","title":"Environment","examples":["production"]},"api_prefix":{"type":"string","title":"Api Prefix","examples":["/api/v1"]},"ai_active":{"type":"boolean","title":"Ai Active","examples":[true]},"docs_url":{"type":"string","title":"Docs Url","examples":["/docs"]},"description":{"type":"string","title":"Description","examples":["Multimodal Control Tower — connectors + AI fallback"]},"data_modes":{"additionalProperties":{"type":"string"},"type":"object","title":"Data Modes","examples":[{"ais":"simulated","port":"simulated","weather":"live"}]},"connectors_live_count":{"type":"integer","minimum":0.0,"title":"Connectors Live Count","default":0,"examples":[1]}},"type":"object","required":["name","version","environment","api_prefix","ai_active","docs_url","description"],"title":"SystemInfo","description":"Public service metadata (GET /api/v1/system/info)."},"Timeline":{"properties":{"shipment_id":{"type":"string","title":"Shipment Id"},"entries":{"items":{"$ref":"#/components/schemas/TimelineEntry"},"type":"array","title":"Entries"}},"type":"object","required":["shipment_id","entries"],"title":"Timeline"},"TimelineEntry":{"properties":{"timestamp":{"type":"string","format":"date-time","title":"Timestamp"},"kind":{"type":"string","title":"Kind","examples":["milestone","event"]},"title":{"type":"string","title":"Title"},"status":{"type":"string","title":"Status","examples":["planned","actual","exception"]},"leg_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Leg Id"},"detail":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Detail"}},"type":"object","required":["timestamp","kind","title","status"],"title":"TimelineEntry","description":"A point on the shipment timeline (milestone or event)."},"TokenResponse":{"properties":{"access_token":{"type":"string","title":"Access Token"},"refresh_token":{"type":"string","title":"Refresh Token"},"token_type":{"type":"string","title":"Token Type","default":"Bearer"},"expires_in":{"type":"integer","title":"Expires In","examples":[900]}},"type":"object","required":["access_token","refresh_token","expires_in"],"title":"TokenResponse","description":"OAuth2 token response."},"TransportMode":{"type":"string","enum":["SEA","RAIL","TRUCK","BARGE","AIR"],"title":"TransportMode"},"UploadResponse":{"properties":{"job_id":{"type":"string","title":"Job Id"},"filename":{"type":"string","title":"Filename"},"template":{"type":"string","title":"Template"},"rows_total":{"type":"integer","minimum":0.0,"title":"Rows Total"},"rows_imported":{"type":"integer","minimum":0.0,"title":"Rows Imported"},"rows_rejected":{"type":"integer","minimum":0.0,"title":"Rows Rejected"},"errors":{"items":{"$ref":"#/components/schemas/UploadRowError"},"type":"array","title":"Errors"},"created_shipment_ids":{"items":{"type":"string"},"type":"array","title":"Created Shipment Ids"},"status":{"type":"string","title":"Status","examples":["COMPLETED","PARTIAL","FAILED"]},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["job_id","filename","template","rows_total","rows_imported","rows_rejected","errors","created_shipment_ids","status","created_at"],"title":"UploadResponse","description":"Result of a manual data upload (spec §5.1.4)."},"UploadRowError":{"properties":{"row":{"type":"integer","minimum":1.0,"title":"Row","examples":[7]},"field":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Field","examples":["planned_arrival"]},"message":{"type":"string","title":"Message","examples":["Invalid ISO 8601 datetime."]}},"type":"object","required":["row","message"],"title":"UploadRowError","description":"A row-level validation error from a CSV/XLSX import (spec §5.1.4)."},"UploadTemplate":{"properties":{"name":{"type":"string","title":"Name","examples":["shipment_manifest"]},"description":{"type":"string","title":"Description"},"columns":{"items":{"$ref":"#/components/schemas/UploadTemplateColumn"},"type":"array","title":"Columns"}},"type":"object","required":["name","description","columns"],"title":"UploadTemplate","description":"A documented upload template (spec §5.1.4)."},"UploadTemplateColumn":{"properties":{"name":{"type":"string","title":"Name"},"required":{"type":"boolean","title":"Required"},"example":{"type":"string","title":"Example"},"description":{"type":"string","title":"Description"}},"type":"object","required":["name","required","example","description"],"title":"UploadTemplateColumn"},"User":{"properties":{"id":{"type":"string","title":"Id"},"username":{"type":"string","title":"Username","examples":["dispatcher"]},"full_name":{"type":"string","title":"Full Name","examples":["Aigerim Nsurlanova"]},"role":{"$ref":"#/components/schemas/UserRole"},"organization_id":{"type":"string","title":"Organization Id"},"active":{"type":"boolean","title":"Active","default":true},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["id","username","full_name","role","organization_id","created_at"],"title":"User"},"UserCreate":{"properties":{"username":{"type":"string","minLength":3,"title":"Username"},"full_name":{"type":"string","minLength":2,"title":"Full Name"},"role":{"$ref":"#/components/schemas/UserRole","default":"viewer"},"organization_id":{"type":"string","title":"Organization Id"}},"type":"object","required":["username","full_name","organization_id"],"title":"UserCreate"},"UserPatch":{"properties":{"full_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Full Name"},"role":{"anyOf":[{"$ref":"#/components/schemas/UserRole"},{"type":"null"}]},"active":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Active"}},"type":"object","title":"UserPatch"},"UserRole":{"type":"string","enum":["viewer","operator","dispatcher","admin","api_client"],"title":"UserRole","description":"Mirror of core RBAC roles for admin schemas (spec §6.3)."},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"VesselLineupEntry":{"properties":{"vessel_name":{"type":"string","title":"Vessel Name","examples":["MV Turan"]},"imo_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Imo Number","examples":["9123456"]},"eta":{"type":"string","format":"date-time","title":"Eta"},"etd":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Etd"},"berth":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Berth","examples":["B-3"]},"status":{"type":"string","title":"Status","examples":["EXPECTED","AT_BERTH","AT_ANCHOR"]}},"type":"object","required":["vessel_name","eta","status"],"title":"VesselLineupEntry","description":"A vessel in a port's expected/at-berth lineup."},"WebhookCreate":{"properties":{"url":{"type":"string","title":"Url","examples":["https://partner.example.com/hooks/caspian"]},"event_types":{"items":{"$ref":"#/components/schemas/EventType"},"type":"array","minItems":1,"title":"Event Types"},"secret":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Secret","description":"HMAC signing secret (write-only)."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"}},"type":"object","required":["url","event_types"],"title":"WebhookCreate","description":"Register a webhook subscription (spec §5.1.5, §6.2)."},"WebhookSubscription":{"properties":{"id":{"type":"string","title":"Id"},"url":{"type":"string","title":"Url"},"event_types":{"items":{"$ref":"#/components/schemas/EventType"},"type":"array","title":"Event Types"},"secret_set":{"type":"boolean","title":"Secret Set"},"active":{"type":"boolean","title":"Active"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["id","url","event_types","secret_set","active","created_at"],"title":"WebhookSubscription"},"WebhookTestResult":{"properties":{"subscription_id":{"type":"string","title":"Subscription Id","examples":["whk_0003"]},"delivered":{"type":"boolean","title":"Delivered","examples":[true]},"sample_event_id":{"type":"string","title":"Sample Event Id","examples":["evt_0182"]},"response_status":{"type":"integer","title":"Response Status","examples":[200]}},"type":"object","required":["subscription_id","delivered","sample_event_id","response_status"],"title":"WebhookTestResult"},"WorldStats":{"properties":{"seed":{"type":"integer","title":"Seed","examples":[42]},"built_at":{"type":"string","format":"date-time","title":"Built At"},"organizations":{"type":"integer","title":"Organizations","examples":[6]},"users":{"type":"integer","title":"Users","examples":[18]},"locations":{"type":"integer","title":"Locations","examples":[12]},"ports":{"type":"integer","title":"Ports","examples":[9]},"assets":{"type":"integer","title":"Assets","examples":[32]},"shipments":{"type":"integer","title":"Shipments","examples":[40]},"legs":{"type":"integer","title":"Legs","examples":[118]},"containers":{"type":"integer","title":"Containers","examples":[64]},"events":{"type":"integer","title":"Events","examples":[210]},"active_legs":{"type":"integer","title":"Active Legs","examples":[37]}},"type":"object","required":["seed","built_at","organizations","users","locations","ports","assets","shipments","legs","containers","events","active_legs"],"title":"WorldStats","description":"Counts that prove the simulated world's scale (GET /api/v1/system/stats)."},"ProblemDetail":{"description":"RFC 7807 problem document.","properties":{"type":{"default":"https://docs.caspian-eye.io/problems/about:blank","description":"A URI reference identifying the problem type.","examples":["https://docs.caspian-eye.io/problems/not-found"],"title":"Type","type":"string"},"title":{"description":"Short, human-readable summary of the problem type.","title":"Title","type":"string"},"status":{"description":"HTTP status code.","examples":[404],"title":"Status","type":"integer"},"detail":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Explanation specific to this occurrence.","title":"Detail"},"instance":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"URI reference for this occurrence.","title":"Instance"},"trace_id":{"default":"-","description":"Correlation id for log lookup.","title":"Trace Id","type":"string"},"errors":{"anyOf":[{"items":{"type":"object"},"type":"array"},{"type":"null"}],"default":null,"description":"Field-level validation errors, when applicable.","title":"Errors"}},"required":["title","status"],"title":"ProblemDetail","type":"object"}},"securitySchemes":{"OAuth2Password":{"type":"oauth2","flows":{"password":{"scopes":{},"tokenUrl":"api/v1/auth/token"}}}}},"tags":[{"name":"Authentication","description":"OAuth2 token issuance, refresh, identity, roles."},{"name":"Shipments","description":"Multimodal shipments + sub-resources (hub)."},{"name":"Legs","description":"Single-mode transport segments."},{"name":"Containers","description":"Intermodal containers (ISO 6346)."},{"name":"Assets & Tracking","description":"Vessels, trains, trucks and live positions."},{"name":"Locations & Ports","description":"Ports, terminals, junctions and congestion."},{"name":"Events","description":"Event taxonomy, query and manual submission."},{"name":"ETA Prediction","description":"Explainable, AI-corrected arrival estimates."},{"name":"Risk Assessment","description":"Composite risk scoring, summaries and heatmaps."},{"name":"NLP Event Processing","description":"Classify/extract/ingest unstructured text."},{"name":"Dashboard","description":"Operational KPIs, arrivals, exceptions, feed health."},{"name":"Data Ingestion","description":"CSV/XLSX upload, webhooks and connector status."},{"name":"Weather","description":"Marine weather by location and along routes."},{"name":"Notifications","description":"Risk/ETA alerts and subscriptions."},{"name":"Admin","description":"Organizations and users (admin only)."},{"name":"System","description":"Service metadata and world statistics."}]}