{ "openapi": "3.1.0", "info": { "title": "TrackingMCP REST API", "version": "1.0.0", "description": "DCSA-aligned ocean container tracking across 227 carriers. Every lookup is cross-checked against 2–4 independent sources (110 direct carrier connectors, fallback providers with automatic failover, 4 fused AIS networks, and sailing schedules). Authenticated endpoints take `Authorization: Bearer ` — create a key at https://trackingmcp.com after signing up (free tier: 5 containers + 100 MCP calls/mo, no card). AI agents can use the hosted MCP server at https://mcp.trackingmcp.com/mcp instead (registry name io.github.lxxmng/container-tracking).", "contact": { "name": "TrackingMCP", "url": "https://trackingmcp.com", "email": "hello@trackingmcp.com" } }, "servers": [ { "url": "https://api.trackingmcp.com" } ], "paths": { "/v1/track/public": { "post": { "operationId": "trackPublic", "summary": "Anonymous one-off tracking lookup (no API key)", "description": "Free, unauthenticated lookup of a container, bill of lading, or booking. Per-browser allowance of 1 lookup per reference type; returns HTTP 429 with `gated: true` once spent. Send a stable per-browser UUID in `X-Anon-Id`.", "security": [], "parameters": [ { "name": "X-Anon-Id", "in": "header", "required": false, "description": "Stable anonymous browser id (e.g. a UUID persisted in localStorage) used to meter the free allowance.", "schema": { "type": "string", "maxLength": 80 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "reference" ], "properties": { "reference": { "type": "string", "description": "Container number (4 letters + 7 digits), bill of lading, or booking reference." }, "reference_type": { "type": "string", "enum": [ "container_id", "bill_of_lading", "booking_number" ], "description": "Client-side guess; the server refines it." }, "carrier_code": { "type": "string", "description": "Optional SCAC hint." } } } } } }, "responses": { "200": { "description": "Live tracking result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/PublicTrackResult" } } } } } }, "400": { "description": "Missing or invalid reference (e.g. bad ISO 6346 container number)." }, "404": { "description": "No live data found for the reference." }, "429": { "description": "Free anonymous allowance spent — create a free account to continue.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": false }, "gated": { "type": "boolean", "const": true } } } } } } } } }, "/v1/containers": { "post": { "operationId": "addContainer", "summary": "Start tracking a container, bill of lading, or booking", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "identifier", "identifier_type" ], "properties": { "identifier": { "type": "string", "minLength": 1, "maxLength": 50 }, "identifier_type": { "type": "string", "enum": [ "container_id", "bill_of_lading", "booking" ] }, "carrier_code": { "type": "string", "minLength": 2, "maxLength": 10, "description": "Optional SCAC hint; auto-resolved from the container prefix when omitted." }, "tags": { "type": "array", "items": { "type": "string" }, "maxItems": 20 }, "tracked_from": { "type": "string", "format": "date-time", "description": "Journey floor for a re-used container number (ISO 8601 date or date-time). Events dated before it are dropped from derivation and the timeline, so a container reused on a new booking scopes to the current sailing instead of a delivered prior journey. Applies to container-number registrations; bill_of_lading and booking references already pin the journey and ignore it." }, "bl_number": { "type": "string", "maxLength": 50, "description": "Bill of lading number sent with a container identifier. Required when carrier_code names a line that tracks only by the bill of lading and the container number together (JJCU, Shanghai Jinjiang); ignored for every other line." }, "container_number": { "type": "string", "maxLength": 50, "description": "Container number (4 letters and 7 digits) sent with a bill_of_lading or booking identifier. Required when carrier_code names a line that tracks only by the bill of lading and the container number together (JJCU, Shanghai Jinjiang); ignored for every other line." } } } } } }, "responses": { "200": { "description": "Container accepted and tracking started.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "api_version": { "type": "string", "description": "The response contract this build answers, as a date. Pin it in your client." }, "data": { "$ref": "#/components/schemas/CreatedContainer" } } } } } }, "400": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key." }, "409": { "description": "Already in your tracking list." } } }, "get": { "operationId": "listContainers", "summary": "List tracked containers", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "Filter by container status." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 500 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Pagination cursor from the previous page." }, { "name": "tags", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated tag filter." }, { "name": "archived", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "true → archived (delivered/removed) boxes instead of the active fleet." } ], "responses": { "200": { "description": "Page of tracked containers.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "api_version": { "type": "string", "description": "The response contract this build answers, as a date. Pin it in your client." }, "data": { "$ref": "#/components/schemas/ContainerPage" } } } } } }, "401": { "description": "Missing or invalid API key." } } } }, "/v1/containers/summary": { "get": { "operationId": "getContainersSummary", "summary": "Portfolio summary — counts, exceptions, arriving soon", "parameters": [ { "name": "filter", "in": "query", "required": false, "description": "Which boxes to list in `data.containers`. The four headline counts (`total_active`, `exceptions`, `arriving_this_week`, `demurrage_risk_usd`) always cover the whole active fleet and are NOT narrowed by this filter — only the container list is. `exceptions` = status in customs_hold / rolled / delayed / at_transshipment; `arriving_soon` = an ETA inside the next 7 days; `demurrage_risk` = boxes with live demurrage exposure. Anything unrecognised behaves as `all`.", "schema": { "type": "string", "enum": [ "all", "exceptions", "arriving_soon", "demurrage_risk" ], "default": "all" } } ], "responses": { "200": { "description": "Aggregated fleet summary.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "api_version": { "type": "string", "description": "The response contract this build answers, as a date. Pin it in your client." }, "data": { "$ref": "#/components/schemas/PortfolioSummary" } } } } } }, "401": { "description": "Missing or invalid API key." } } } }, "/v1/usage": { "get": { "operationId": "getUsage", "summary": "Your usage and limits, over your own API key", "description": "The counters and limits for the org the key belongs to, from the same ledgers the API enforces against and the sales console shows, so this number, your bill and your rep never disagree. Also mounted at /v1/account/usage.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Per-product usage for the current calendar month.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "data": { "type": "object", "properties": { "period": { "type": "string", "example": "2026-09", "description": "UTC calendar month these counters cover." }, "next_expiry": { "type": "string", "nullable": true, "format": "date", "description": "Earliest valid_until across enabled products; access ends after this date." }, "invalid_references_this_month": { "type": "integer", "description": "Requests refused because YOUR reference was malformed or its carrier is unsupported. Your input errors, never billed, kept apart from consumption." }, "products": { "type": "array", "items": { "type": "object", "properties": { "product": { "type": "string", "example": "container" }, "channel": { "type": "string", "example": "api" }, "plan": { "type": "string", "enum": [ "free", "paid" ] }, "billing_mode": { "type": "string", "enum": [ "monthly", "per_shipment" ] }, "valid_until": { "type": "string", "nullable": true, "format": "date" }, "start_date": { "type": "string", "nullable": true, "format": "date" }, "refused_this_month": { "type": "integer", "description": "Requests we turned away this month (over the unique allowance, expired access, or a per-key rate cap). Never billed." }, "last_refused_at": { "type": "string", "nullable": true, "format": "date-time" }, "calls": { "type": "object", "description": "API-call traffic against your plan's call allowance. `used` is this product's calls this month (your own reads of usage/account/api-keys are excluded); `limit`/`remaining` are the call ceiling and what is left of it; `test_used` is the slice of `used` spent on a test key. Distinct from `allowance`, the unique-reference budget that actually bills.", "properties": { "used": { "type": "integer" }, "limit": { "type": "integer", "nullable": true, "description": "Calls allowed this period (your plan allowance, lowered by any per-key rate cap). Null only when neither is set." }, "remaining": { "type": "integer", "nullable": true }, "test_used": { "type": "integer", "description": "Of `used`, the calls made on a test key. A test key spends a sandbox, never your commercial allowance." } } }, "allowance": { "type": "object", "description": "What you can consume, in the unit you are billed: one unique reference per period. This is the ceiling the add/lookup gate enforces.", "properties": { "basis": { "type": "string", "enum": [ "unique_reference" ] }, "limit": { "type": "integer", "nullable": true, "description": "Maximum unique references this period; null means no ceiling is set." }, "used": { "type": "integer", "description": "Unique references charged this period." }, "remaining": { "type": "integer", "nullable": true } } } } } } } } } } } } }, "401": { "description": "Missing or invalid API key." } } } }, "/v1/containers/demurrage": { "get": { "operationId": "getDemurrageRisk", "summary": "Demurrage risk across all tracked containers", "responses": { "200": { "description": "Containers at demurrage/detention risk with free days remaining.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "api_version": { "type": "string", "description": "The response contract this build answers, as a date. Pin it in your client." }, "data": { "$ref": "#/components/schemas/DemurrageReport" } } } } } }, "401": { "description": "Missing or invalid API key." } } } }, "/v1/containers/lookup/{identifier}": { "get": { "operationId": "lookupContainer", "summary": "Look up a tracked container by its identifier", "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Container detail.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "api_version": { "type": "string", "description": "The response contract this build answers, as a date. Pin it in your client." }, "data": { "$ref": "#/components/schemas/ContainerLookup" } } } } } }, "401": { "description": "Missing or invalid API key." }, "404": { "description": "Not in your tracking list." } } } }, "/v1/containers/{id}": { "get": { "operationId": "getContainer", "summary": "Full container detail — route, ETA, vessel, events", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Container detail with normalized DCSA events.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "api_version": { "type": "string", "description": "The response contract this build answers, as a date. Pin it in your client." }, "data": { "$ref": "#/components/schemas/ContainerRecord" } } } } } }, "401": { "description": "Missing or invalid API key." }, "404": { "description": "Unknown container id." } } }, "delete": { "operationId": "deleteContainer", "summary": "Stop tracking (archive) a container", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Archived.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "api_version": { "type": "string", "description": "The response contract this build answers, as a date. Pin it in your client." }, "data": { "$ref": "#/components/schemas/ArchivedContainer" } } } } } }, "401": { "description": "Missing or invalid API key." }, "404": { "description": "Unknown container id." } } } }, "/v1/containers/{id}/recheck": { "post": { "operationId": "recheckContainer", "summary": "Force an immediate re-poll of a container", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Recheck queued.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "api_version": { "type": "string", "description": "The response contract this build answers, as a date. Pin it in your client." }, "data": { "$ref": "#/components/schemas/RecheckStarted" } } } } } }, "401": { "description": "Missing or invalid API key." }, "404": { "description": "Unknown container id." } } } }, "/v2/events": { "get": { "operationId": "listDcsaEvents", "summary": "DCSA Track & Trace 2.2 event feed", "description": "Standards-aligned event feed (DCSA T&T 2.2.0). Returns a bare JSON array of event objects for the containers on your account, newest first. Filter with the DCSA query parameters. IMPORTANT — two fields customers ask about:\n\n1. `emptyIndicatorCode` is present ONLY on EQUIPMENT events and ONLY when the carrier reported the fill state. Per DCSA it is a required `EMPTY | LADEN` enum with no 'unknown' member, so rather than fabricate a value we OMIT the field when the line didn't report it (most equipment events). Do NOT rely on it as your end-of-shipment trigger — many carriers (e.g. MSC) never stamp it on the empty return. Where the carrier described the move only in words ('Empty received at CY'), we now infer `EMPTY` from that phrase, but coverage is still partial.\n\n2. There is NO container-level status in this feed — it is events only. `delivered` / `returned_empty` are CONTAINER statuses, not events; read them from `GET /v1/containers/{id}` (the `status` field). To detect end-of-shipment, poll the container status: `delivered` = laden box handed to the consignee at the destination port; `returned_empty` = the empty box was returned to the depot (the true, terminal end of shipment, which happens AFTER `delivered`).", "parameters": [ { "name": "equipmentReference", "in": "query", "required": false, "description": "Filter to a single container number (e.g. MSCU1234567).", "schema": { "type": "string" } }, { "name": "eventType", "in": "query", "required": false, "description": "DCSA event type filter.", "schema": { "type": "string", "enum": [ "SHIPMENT", "TRANSPORT", "EQUIPMENT" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 100, "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "DCSA event array (the `API-Version` response header reports the T&T version, e.g. 2.2.0).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DcsaEvent" } } } } }, "401": { "description": "Missing or invalid API key." } } } }, "/v1/webhooks": { "post": { "operationId": "createWebhook", "summary": "Register a webhook endpoint", "description": "Register an https:// endpoint to receive shipment events for your organisation. Accounts have an active-endpoint limit (three by default); inactive endpoints do not consume a slot. `event_types` is filtered against the supported list on the way in: an unrecognised name is dropped silently rather than rejected, so send only values from the enum and read the returned `event_types` back to confirm what was stored. An empty or omitted `event_types` stores an empty list. Every type in the enum has a live producer.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "Destination endpoint. Must start with https://." }, "event_types": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEventType" }, "description": "Events to receive. Names outside the enum are discarded." }, "description": { "type": "string", "description": "Free-text label for your own bookkeeping." } } } } } }, "responses": { "201": { "description": "Endpoint registered. THE `secret` IS RETURNED ONCE, HERE, AND NEVER AGAIN — no later endpoint returns it and it cannot be re-read. Store it now: it is the HMAC key you verify each delivery's signature against. Losing it means deleting the endpoint and registering a new one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "data": { "allOf": [ { "$ref": "#/components/schemas/WebhookEndpoint" }, { "type": "object", "properties": { "secret": { "type": "string", "description": "Signing secret. Returned only on this response." } }, "required": [ "secret" ] } ] } } } } } }, "400": { "description": "`INVALID_URL` — url missing or not an https:// URL.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key." }, "409": { "description": "`WEBHOOK_ENDPOINT_LIMIT` — the account has reached its active webhook endpoint limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "`INTERNAL_ERROR` — the endpoint could not be stored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "get": { "operationId": "listWebhooks", "summary": "List your webhook endpoints", "description": "Every endpoint registered by your organisation, newest first. The signing secret is never returned here.", "responses": { "200": { "description": "Your endpoints, under `data.items`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } } } } } } } } }, "401": { "description": "Missing or invalid API key." }, "500": { "description": "`INTERNAL_ERROR` — the list could not be read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/webhooks/usage": { "get": { "operationId": "getWebhookUsage", "summary": "Read webhook limits and today's delivery counters", "description": "Returns the effective active-endpoint limit, sustained delivery rate and burst allowance together with UTC-day enqueue, attempt, success, failure and dead-letter counters. Delivery traffic above the rate is retained in the durable queue rather than rejected.", "responses": { "200": { "description": "Effective webhook limits, active endpoint count and today's UTC counters.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "limits": { "type": "object", "properties": { "active_endpoint_limit": { "type": "integer", "example": 3 }, "deliveries_per_second": { "type": "number", "example": 5 }, "burst_deliveries": { "type": "integer", "example": 25 } }, "required": [ "active_endpoint_limit", "deliveries_per_second", "burst_deliveries" ] }, "active_endpoints": { "type": "integer" }, "day": { "type": "string", "format": "date" }, "usage": { "type": "object", "properties": { "enqueued": { "type": "integer" }, "attempted": { "type": "integer" }, "delivered": { "type": "integer" }, "failed": { "type": "integer" }, "dead": { "type": "integer" } }, "required": [ "enqueued", "attempted", "delivered", "failed", "dead" ] } }, "required": [ "limits", "active_endpoints", "day", "usage" ] } }, "required": [ "ok", "data" ] } } } }, "401": { "description": "Missing or invalid API key." } } } }, "/v1/webhooks/{id}": { "get": { "operationId": "getWebhook", "summary": "One endpoint plus its 20 most recent delivery attempts", "description": "The endpoint's current configuration and its delivery history — the first place to look when an integration goes quiet, since `last_error` and `last_status_code` say whether we failed to reach you or never had anything to send.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Endpoint detail with recent deliveries.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "data": { "allOf": [ { "$ref": "#/components/schemas/WebhookEndpoint" }, { "type": "object", "properties": { "recent_deliveries": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" }, "description": "Up to 20 attempts, newest first." } } } ] } } } } } }, "401": { "description": "Missing or invalid API key." }, "404": { "description": "`NOT_FOUND` — no such endpoint on your organisation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "patch": { "operationId": "updateWebhook", "summary": "Update an endpoint's url, events, description or active flag", "description": "Partial update. An invalid or non-public HTTPS `url` fails with HTTP 400. `event_types` is filtered against the supported list exactly as on create; read the response back to confirm what was stored. Setting `active: true` also resets `failure_count` to 0, which is how you re-enable an endpoint we auto-disabled after repeated delivery failures.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "event_types": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEventType" } }, "description": { "type": "string" }, "active": { "type": "boolean", "description": "true also clears the failure counter." } } } } } }, "responses": { "200": { "description": "Updated endpoint (id, url, event_types, description, active).", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "data": { "$ref": "#/components/schemas/WebhookEndpoint" } } } } } }, "401": { "description": "Missing or invalid API key." }, "404": { "description": "`NOT_FOUND` — no such endpoint on your organisation, or the update failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "operationId": "deleteWebhook", "summary": "Delete a webhook endpoint", "description": "Removes the endpoint permanently. Its signing secret goes with it; a replacement endpoint gets a new one. Deleting an id that is not yours is a no-op and still answers 200.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "deleted": { "type": "boolean", "const": true } } } } } } } }, "401": { "description": "Missing or invalid API key." }, "500": { "description": "`INTERNAL_ERROR` — the delete failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/webhooks/{id}/test": { "post": { "operationId": "testWebhook", "summary": "Queue a `ping` delivery to verify wiring and signature", "description": "Queues a delivery with event type `ping` and a body of `{ type: \"ping\", occurred_at, data: { message } }` so you can confirm your endpoint is reachable and your signature check is correct before any real shipment event arrives. The response returns as soon as the delivery is QUEUED, not when it lands: read the outcome from `recent_deliveries` on GET /v1/webhooks/{id}. `ping` is not a subscribable event type and does not need to be in `event_types`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Test delivery queued.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "test_queued": { "type": "boolean", "const": true } } } } } } } }, "401": { "description": "Missing or invalid API key." }, "404": { "description": "`NOT_FOUND` — no such endpoint on your organisation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "`INTERNAL_ERROR` — the test delivery could not be queued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "TrackingMCP API key (or a session JWT). Create keys in the dashboard — https://trackingmcp.com/developers." } }, "schemas": { "OkEnvelope": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "data": { "description": "Endpoint-specific payload." } }, "required": [ "ok" ] }, "ErrorEnvelope": { "type": "object", "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "severity": { "type": "string" } } }, "carrier_notice": { "type": "object", "nullable": true, "description": "Latest reference-specific reply from the named carrier. SHIPMENT_CANCELLED is an explicit matched Maersk cancellation, independent of retained movement history. no_longer_available is Swire stating it no longer serves tracking details for this shipment. ZIM notices clear after useful tracking.", "properties": { "carrier_code": { "type": "string", "enum": [ "ZIMU", "MAEU", "CHVW" ] }, "reference": { "type": "string" }, "reference_type": { "type": "string", "enum": [ "container", "bl", "booking" ] }, "status": { "type": "string", "enum": [ "other_carrier", "temporarily_unavailable", "not_found", "invalid_reference", "SHIPMENT_CANCELLED", "no_longer_available" ] }, "message": { "type": "string" }, "checked_at": { "type": "string", "format": "date-time" }, "suggested_carrier": { "type": "string", "nullable": true }, "suggested_url": { "type": "string", "nullable": true, "format": "uri" } } } } }, "WebhookEventType": { "type": "string", "description": "A subscribable webhook event. `shipment_updated` is the general push signal for REST reconciliation: fresh carrier persistence added movements or changed a core shipment summary, and the receiver should fetch the canonical shipment resource. Shipment lifecycle alerts remain more specific. `api_change_announced` is platform lifecycle and is better wired to CI or an on-call channel.", "enum": [ "api_change_announced", "container_arrived", "container_available", "container_delivered", "container_misrouted", "customs_hold", "demurrage_started", "demurrage_warning", "eta_changed", "schedule_disruption", "shipment_updated", "vessel_departed", "vessel_rollover" ] }, "WebhookEndpoint": { "type": "object", "description": "A registered webhook endpoint. The signing secret is NOT part of this shape: it is returned once, on create, and never again. `failure_count` and `last_delivery_at` are present on the list and detail responses but not on the create or update responses.", "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "event_types": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEventType" }, "description": "The stored subscription, after unrecognised names were filtered out." }, "description": { "type": [ "string", "null" ] }, "active": { "type": "boolean" }, "failure_count": { "type": "integer", "description": "Consecutive delivery failures. Reset to 0 by a PATCH setting active: true." }, "last_delivery_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } }, "WebhookDelivery": { "type": "object", "description": "One delivery attempt against an endpoint, as returned under `recent_deliveries`.", "properties": { "id": { "type": "string", "format": "uuid" }, "event_type": { "type": "string", "description": "The event delivered. `ping` for a test delivery; otherwise a WebhookEventType." }, "status": { "type": "string" }, "attempt_count": { "type": "integer" }, "last_status_code": { "type": [ "integer", "null" ], "description": "HTTP status your endpoint returned on the last attempt." }, "last_error": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "delivered_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "ContainerStatus": { "type": "string", "description": "Derived container status (from `GET /v1/containers/{id}`). Ocean lifecycle order — `discharged` → `available` → `delivered` → `returned_empty`. Two terminal end-of-shipment values: `delivered` (laden container gated out to the consignee at the destination port) and `returned_empty` (the empty box was returned to the depot AFTER delivery — the true end of shipment). `returned_empty` outranks `delivered`; a box that has been returned reads `returned_empty` even though it was `delivered` earlier.", "enum": [ "pre_departure", "in_transit", "at_transshipment", "at_anchor", "at_berth", "arriving", "discharged", "customs_hold", "available", "delivered", "returned_empty", "cancelled", "unknown" ] }, "DcsaEvent": { "type": "object", "description": "A DCSA Track & Trace 2.2 event. Common fields plus a per-type block (SHIPMENT / TRANSPORT / EQUIPMENT). Null/absent fields are omitted from the payload rather than sent as null.", "properties": { "eventID": { "type": "string", "format": "uuid" }, "eventCreatedDateTime": { "type": "string", "format": "date-time" }, "eventType": { "type": "string", "enum": [ "SHIPMENT", "TRANSPORT", "EQUIPMENT" ] }, "eventClassifierCode": { "type": "string", "enum": [ "ACT", "PLN", "EST" ], "description": "ACT = actual (happened), EST = estimated, PLN = planned. Never assume a PLN/EST move has occurred." }, "eventDateTime": { "type": "string", "format": "date-time" }, "equipmentEventTypeCode": { "type": "string", "description": "EQUIPMENT events only. E.g. GTOT (gate-out), GTIN (gate-in), LOAD, DISC, PICK, DROP.", "enum": [ "LOAD", "DISC", "GTIN", "GTOT", "STUF", "STRP", "PICK", "DROP", "INSP", "RSEA", "RMVD" ] }, "emptyIndicatorCode": { "type": "string", "enum": [ "EMPTY", "LADEN" ], "description": "EQUIPMENT events only. Present ONLY when the carrier reported the fill state (a minority of events). Absent when not reported — DCSA has no 'unknown' value and we do not fabricate one. Not a reliable end-of-shipment signal; use the container `status` field instead." }, "equipmentReference": { "type": "string", "description": "Container number." }, "ISOEquipmentCode": { "type": [ "string", "null" ] }, "transportEventTypeCode": { "type": "string", "description": "TRANSPORT events only. E.g. ARRI (arrival), DEPA (departure).", "enum": [ "ARRI", "DEPA" ] }, "shipmentEventTypeCode": { "type": [ "string", "null" ], "description": "SHIPMENT events only." }, "transportCall": { "type": [ "object", "null" ], "description": "Location / vessel / voyage of the call." } }, "required": [ "eventID", "eventType", "eventClassifierCode", "eventDateTime" ] }, "PublicTrackResult": { "type": "object", "properties": { "identifier": { "type": "string" }, "identifier_type": { "type": "string", "enum": [ "container_id", "bill_of_lading", "booking_number" ] }, "carrier_code": { "type": [ "string", "null" ] }, "carrier_name": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "eta": { "type": [ "string", "null" ], "format": "date-time" }, "origin": { "type": [ "string", "null" ] }, "destination": { "type": [ "string", "null" ] }, "vessel": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ] }, "lat": { "type": [ "number", "null" ] }, "lng": { "type": [ "number", "null" ] } } }, "events": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string" }, "location": { "type": [ "string", "null" ] }, "datetime": { "type": [ "string", "null" ], "format": "date-time" }, "actual": { "type": "boolean" } } } }, "observability": { "type": [ "object", "null" ], "properties": { "lenses": { "type": "object", "properties": { "actuals": { "type": "boolean" }, "position": { "type": "boolean" }, "plan": { "type": "boolean" }, "probability": { "type": "boolean" } } }, "active_count": { "type": "integer" } } } } }, "WebhookStatusEventData": { "type": "object", "description": "`data` for the status family: container_arrived, container_available, container_delivered, customs_hold, vessel_departed, demurrage_started, demurrage_warning. The demurrage figures are null unless demurrage alerting is armed and applicable.", "properties": { "container_id": { "type": "string", "format": "uuid", "description": "Our internal shipment UUID. Not a shipping reference; useful only if you store our ids." }, "identifier": { "type": [ "string", "null" ], "description": "The reference the shipment is tracked by: a container number, a bill of lading or a booking number, whichever it was added with." }, "identifier_type": { "type": [ "string", "null" ], "enum": [ "container_id", "bill_of_lading", "booking", null ], "description": "What kind of reference `identifier` is. Null when unknown (shipments recorded before the type was stored). Additive field, added 2026-08-19; absent on deliveries produced by older builds." }, "previous_status": { "$ref": "#/components/schemas/ContainerStatus" }, "new_status": { "$ref": "#/components/schemas/ContainerStatus" }, "eta": { "type": [ "string", "null" ], "format": "date-time", "description": "Current ETA at the moment the event fired. UTC." }, "demurrage_days_overdue": { "type": [ "integer", "null" ] }, "demurrage_accrued_usd": { "type": [ "number", "null" ] } }, "required": [ "container_id", "previous_status", "new_status" ], "additionalProperties": true }, "WebhookEtaChangedData": { "type": "object", "description": "`data` for eta_changed: the carrier moved the ETA by 24 hours or more. Fires at most once per box per day.", "properties": { "container_id": { "type": "string", "format": "uuid", "description": "Our internal shipment UUID. Not a shipping reference; useful only if you store our ids." }, "identifier": { "type": [ "string", "null" ], "description": "The reference the shipment is tracked by: a container number, a bill of lading or a booking number, whichever it was added with." }, "identifier_type": { "type": [ "string", "null" ], "enum": [ "container_id", "bill_of_lading", "booking", null ], "description": "What kind of reference `identifier` is. Null when unknown (shipments recorded before the type was stored). Additive field, added 2026-08-19; absent on deliveries produced by older builds." }, "old_eta": { "type": [ "string", "null" ], "format": "date-time" }, "new_eta": { "type": [ "string", "null" ], "format": "date-time" }, "delta_hours": { "type": "number", "description": "Signed shift in hours; positive means later." } }, "required": [ "container_id", "new_eta" ], "additionalProperties": true }, "WebhookScheduleDisruptionData": { "type": "object", "description": "`data` for schedule_disruption: the matched sailing slipped materially or did not depart. Fired once per distinct disruption per box.", "properties": { "container_id": { "type": "string", "format": "uuid", "description": "Our internal shipment UUID. Not a shipping reference; useful only if you store our ids." }, "identifier": { "type": [ "string", "null" ], "description": "The reference the shipment is tracked by. Additive, added 2026-08-19." }, "identifier_type": { "type": [ "string", "null" ], "enum": [ "container_id", "bill_of_lading", "booking", null ], "description": "What kind of reference `identifier` is. Null when unknown (shipments recorded before the type was stored). Additive field, added 2026-08-19; absent on deliveries produced by older builds." }, "kind": { "type": "string", "description": "slipped or not_departed." }, "dedup_key": { "type": "string" }, "headline": { "type": "string", "description": "One human-readable sentence for the disruption." }, "delay_hours": { "type": [ "number", "null" ] } }, "required": [ "container_id", "kind", "headline" ], "additionalProperties": true }, "WebhookMisroutedData": { "type": "object", "description": "`data` for container_misrouted: a laden box was discharged at a port that is neither its destination nor a transshipment on its route.", "properties": { "container_id": { "type": "string", "format": "uuid", "description": "Our internal shipment UUID. Not a shipping reference; useful only if you store our ids." }, "identifier": { "type": [ "string", "null" ], "description": "The reference the shipment is tracked by: a container number, a bill of lading or a booking number, whichever it was added with." }, "identifier_type": { "type": [ "string", "null" ], "enum": [ "container_id", "bill_of_lading", "booking", null ], "description": "What kind of reference `identifier` is. Null when unknown (shipments recorded before the type was stored). Additive field, added 2026-08-19; absent on deliveries produced by older builds." }, "discharge_port": { "type": [ "string", "null" ], "description": "UN/LOCODE of the actual discharge." }, "expected_port": { "type": [ "string", "null" ], "description": "UN/LOCODE of the expected destination." } }, "required": [ "container_id" ], "additionalProperties": true }, "WebhookApiChangeData": { "type": "object", "description": "`data` for api_change_announced: an API change announced ahead of its effective date. The fields mirror the public changelog entry.", "properties": { "notice_days": { "type": "integer", "description": "Days between this announcement and the effective date." } }, "required": [ "notice_days" ], "additionalProperties": true }, "WebhookDeliveryEnvelope": { "type": "object", "description": "Every queued webhook delivery, test pings included, is this envelope POSTed to your endpoint. Headers: X-TrackingMCP-Event (the type), X-TrackingMCP-Delivery (equals body id), X-TrackingMCP-Signature: sha256=hex(HMAC-SHA256(secret, raw body)) where secret is the one returned ONCE at registration. Verify the signature before trusting the payload. Answer any 2xx; a non-2xx or 10-second timeout is retried after 10s, 1m, 5m, 30m and 2h, then marked dead after the sixth failed attempt (about a 2h36m retry window). Delivery is at-least-once, duplicates are possible, and ordering is not guaranteed; deduplicate by delivery id and fetch canonical shipment state. There is no replay endpoint. Enqueueing shipment_updated is currently best-effort, so REST reconciliation/polling remains required after receiver or platform outages. After 20 consecutive failed deliveries the endpoint is disabled automatically; one success resets the counter. Alert events can be suppressed for 24 hours by their alert policy; shipment_updated is emitted only for a newly persisted material change.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Delivery id. Equals the X-TrackingMCP-Delivery header." }, "type": { "description": "A WebhookEventType, or `ping` for a test delivery.", "anyOf": [ { "$ref": "#/components/schemas/WebhookEventType" }, { "const": "ping" } ] }, "occurred_at": { "type": "string", "format": "date-time" }, "data": { "description": "Shape depends on `type`.", "oneOf": [ { "$ref": "#/components/schemas/WebhookStatusEventData" }, { "$ref": "#/components/schemas/WebhookEtaChangedData" }, { "$ref": "#/components/schemas/WebhookScheduleDisruptionData" }, { "$ref": "#/components/schemas/WebhookMisroutedData" }, { "$ref": "#/components/schemas/WebhookApiChangeData" }, { "type": "object", "description": "ping: { message }", "properties": { "message": { "type": "string" } } } ] } }, "required": [ "id", "type", "occurred_at", "data" ] }, "CreatedContainer": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable identifier for the record. On the tracking endpoints this is the container UUID, except on a portfolio summary row, where it is the container number." }, "identifier": { "type": "string", "description": "The container number, bill of lading or booking this record tracks." }, "status": { "type": "string", "description": "Current normalised status of the shipment. Ocean lifecycle order: discharged, available, delivered, returned_empty. Two values end a shipment, delivered and returned_empty, and returned_empty outranks delivered." }, "carrier_code": { "type": "string", "description": "Carrier SCAC." } }, "description": "The payload. Everything an endpoint returns sits under this key." }, "ContainerPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable identifier for the record. On the tracking endpoints this is the container UUID, except on a portfolio summary row, where it is the container number." }, "org_id": { "type": "string", "description": "Your organisation. Every keyed read is scoped to it, so this is always your own id: it exists so a record stays self-describing once exported." }, "identifier": { "type": "string", "description": "The container number, bill of lading or booking this record tracks." }, "identifier_type": { "type": "string", "description": "What the identifier is. The keyed surface uses container_id, bill_of_lading or booking; the public tracker returns booking_number for the third." }, "carrier_code": { "type": "string", "description": "Carrier SCAC." }, "carrier_name": { "type": "string", "description": "Carrier name." }, "tags": { "type": "array", "items": {}, "description": "Your own labels on this box. Filter the list endpoint with them." }, "status": { "type": "string", "description": "Current normalised status of the shipment. Ocean lifecycle order: discharged, available, delivered, returned_empty. Two values end a shipment, delivered and returned_empty, and returned_empty outranks delivered." }, "eta": { "type": "string", "description": "Arrival time (ISO 8601). Null when the carrier publishes none and we cannot predict one." }, "eta_is_estimated": { "type": "boolean", "description": "True when the ETA is still a forecast, false when it is the actual arrival, null when there is no ETA at all. Never read a date alone as a promise." }, "planned_departure_at": { "type": "string", "description": "Departure the carrier planned or actually filed for the load port. Null when the carrier publishes none." }, "current_vessel_imo": { "type": "string", "description": "IMO of the hull carrying the box now. Null before loading and after discharge." }, "poll_priority": { "type": "string", "description": "Which polling cadence this box sits in (pre_departure, transit, arrival, dwell). It decides how often we ask the carrier, and moves on its own as the shipment progresses." }, "demurrage_at_risk": { "type": "boolean", "description": "True when the free-time clock on this box is a concern." }, "demurrage_accrued_usd": { "type": [ "number", "null" ], "description": "Demurrage charged so far on this box, US dollars. Null when no rate applies, which is not the same as zero owed." }, "demurrage_last_free_day": { "type": [ "string", "null" ], "description": "The last day before demurrage accrues, or null when no terms are on file." }, "customs_hold_reason": { "type": [ "string", "null" ], "description": "Why customs is holding the box, when the carrier names a reason. Null when there is no hold." }, "customs_hold_since": { "type": [ "string", "null" ], "description": "When the hold started. Null when there is no hold." }, "origin_unlocode": { "type": "string", "description": "Origin port UN/LOCODE, or null when the carrier named no origin we could resolve." }, "destination_unlocode": { "type": "string", "description": "Destination port UN/LOCODE, or null when unresolved." }, "destination_name": { "type": "string", "description": "Destination port name, falling back to its UN/LOCODE." }, "container_size": { "type": [ "string", "null" ], "description": "Equipment size, for example 40HC. Null when the carrier did not state it." }, "equipment_type": { "type": [ "string", "null" ], "description": "Equipment family as the carrier names it. Null when unstated." }, "iso_type_code": { "type": [ "string", "null" ], "description": "The type half of the ISO 6346 code (G1 for a general-purpose box, R1 for a reefer). Null when unstated." }, "equipment_owner": { "type": [ "string", "null" ], "description": "Registered owner of the box, resolved from its BIC prefix. Null when the prefix is unregistered." }, "equipment_lessor": { "type": [ "string", "null" ], "description": "Leasing company, when the box is leased rather than carrier-owned. Null otherwise." }, "lessee_name": { "type": [ "string", "null" ], "description": "Who holds the box on lease. Null unless the lessor publishes it." }, "carrier_hint_code": { "type": [ "string", "null" ], "description": "An unconfirmed carrier candidate derived from lessor data. Never a confirmed carrier: read carrier_code for that." }, "lessor_status": { "type": [ "string", "null" ], "description": "The box status as the lessor reports it, for example on-hire or off-hire. Null when we hold no lessor record." }, "lessor_checked_at": { "type": [ "string", "null" ], "description": "When we last asked the lessor. Null when we never have." }, "connector_status": { "type": [ "string", "null" ], "description": "Where a request to connect this carrier stands, when the line needs one. Null when the carrier is already connected." }, "connector_notify_requested_at": { "type": [ "string", "null" ], "description": "When you asked to be told the connector went live. Null when you did not ask." }, "redelivery_reference": { "type": [ "string", "null" ], "description": "Redelivery booking for the empty. Null until one exists." }, "redelivery_date": { "type": [ "string", "null" ], "description": "When the empty is due back. Null until scheduled." }, "redelivery_location": { "type": [ "string", "null" ], "description": "Where the empty is due back. Null until scheduled." }, "redelivery_yard": { "type": [ "string", "null" ], "description": "The depot the empty is due back at. Null until scheduled." }, "lessor_contract_number": { "type": [ "string", "null" ], "description": "Lease contract the box sits on. Null unless published." }, "lessor_contract_type": { "type": [ "string", "null" ], "description": "Lease type, for example long-term or one-way. Null unless published." }, "equipment_manufacturer": { "type": [ "string", "null" ], "description": "Who built the box. Null unless the lessor publishes it." }, "last_polled_at": { "type": "string", "description": "When we last asked the carrier (ISO 8601)." }, "added_at": { "type": "string", "description": "When you started tracking this box (ISO 8601)." }, "archived_at": { "type": [ "string", "null" ], "description": "When tracking stopped, or null while the box is still active." }, "archived_reason": { "type": [ "string", "null" ], "description": "Why tracking stopped: your delete call, or an automatic close-out once the box finished its cycle. Null while active." }, "unresolvable_since": { "type": [ "string", "null" ], "description": "When we gave up resolving this reference. Null while we are still trying, which is the normal state." }, "unresolved_reason": { "type": [ "string", "null" ], "description": "Why a reference could not be resolved: invalid_number, not_found or bl_booking_unresolved. Null means resolved or still resolving." }, "route_alert": { "type": [ "string", "null" ], "description": "A route problem we detected, for example a destination change or a missed connection. Null when the route is behaving." }, "source": { "type": "string", "description": "Where the answer on this call came from: direct_carrier or warm_db." }, "delay_bars": { "type": "array", "items": { "type": [ "string", "null" ], "description": "Days late at each of the five voyage stages. Positive is late, negative is early, null means we cannot tell." }, "description": "Days late at each of the five voyage stages. Positive is late, negative is early, null means we cannot tell." }, "route_ports": { "type": [ "string", "null" ], "description": "The ports on the route, in order." }, "is_demo": { "type": "boolean", "description": "True on a sample reference. Sample boxes return typical data and have no live carrier feed." }, "vessel_position": { "type": "object", "properties": { "imo": { "type": "string", "description": "IMO number of the vessel." }, "name": { "type": "string", "description": "Human-readable name." }, "lat": { "type": "number", "description": "Latitude." }, "lng": { "type": "number", "description": "Longitude." }, "speed_knots": { "type": "integer", "description": "Speed over ground, in knots." }, "heading_deg": { "type": "integer", "description": "Heading in degrees." }, "nav_status": { "type": "string", "description": "Navigational status as reported by AIS, for example \"Under way using engine\" or \"Moored\". We drop a moored or anchored claim that the position contradicts." }, "position_updated_at": { "type": "string", "description": "When we last wrote the position row." }, "position_fix_at": { "type": "string", "description": "When the hull was actually observed. This, not position_updated_at, is the age that matters." }, "position_age_hours": { "type": "number", "description": "How old the fix is, in hours." }, "position_freshness": { "type": "string", "description": "live, recent, stale, outdated, or unknown when we hold no usable fix." } }, "description": "Live AIS position of the carrying vessel. Null when we hold no IMO or no fix yet." }, "carrier_notice": { "$ref": "#/components/schemas/CarrierNotice", "description": "Latest reference-specific reply from the named carrier. SHIPMENT_CANCELLED is an explicit matched Maersk cancellation, independent of retained movement history. no_longer_available is Swire stating it no longer serves tracking details for this shipment. ZIM notices clear after useful tracking." }, "carrier_document_reply": { "$ref": "#/components/schemas/CarrierDocumentReply", "description": "Latest retained, exact-reference OOCL document reply. Separate from shipment event history; does not imply a fresh carrier check." } }, "description": "The list of results." }, "description": "The list of results." }, "has_more": { "type": "boolean", "description": "True when another page is waiting behind next_cursor." }, "next_cursor": { "type": "string", "description": "Cursor for the next page, or null when there are no more." } }, "description": "The payload. Everything an endpoint returns sits under this key." }, "PortfolioSummary": { "type": "object", "properties": { "total_active": { "type": "integer", "description": "Containers you are tracking, excluding archived ones." }, "exceptions": { "type": "integer", "description": "Count of shipments in an exception state: customs hold, rolled, delayed or at transshipment." }, "arriving_this_week": { "type": "integer", "description": "Count with an ETA in the next seven days." }, "demurrage_risk_usd": { "type": "integer", "description": "Demurrage already accrued across the book, in USD." }, "containers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "string", "null" ], "description": "Stable identifier for the record. On the tracking endpoints this is the container UUID, except on a portfolio summary row, where it is the container number." }, "status": { "type": "string", "description": "Current normalised status of the shipment. Ocean lifecycle order: discharged, available, delivered, returned_empty. Two values end a shipment, delivered and returned_empty, and returned_empty outranks delivered." }, "eta": { "type": [ "string", "null" ], "description": "Arrival time (ISO 8601). Null when the carrier publishes none and we cannot predict one." }, "vessel_name": { "type": [ "string", "null" ], "description": "Name of the carrying vessel, or null when the carrier named none." }, "vessel_imo": { "type": [ "string", "null" ], "description": "IMO number of the carrying vessel, or null when unknown." } }, "description": "Tracked containers on the account." }, "description": "Tracked containers on the account." } }, "description": "The payload. Everything an endpoint returns sits under this key." }, "DemurrageReport": { "type": "object", "properties": { "total_at_risk_usd": { "type": "integer", "description": "Projected demurrage across the assessable boxes, in USD." }, "containers_at_risk": { "type": "integer", "description": "How many boxes the projection covers." }, "items": { "type": "array", "items": { "type": "object", "properties": { "container_id": { "type": "string", "description": "The container number this row is about." }, "port": { "type": "string", "description": "Port UN/LOCODE." }, "free_days_left": { "type": "integer", "description": "Days before free time runs out. Negative once charges are accruing, null when we hold no last free day." }, "daily_rate_usd": { "type": "integer", "description": "Daily demurrage rate in USD." }, "projected_usd": { "type": "integer", "description": "Demurrage accrued so far on this box, in USD." }, "status": { "type": "string", "description": "Current normalised status of the shipment. Ocean lifecycle order: discharged, available, delivered, returned_empty. Two values end a shipment, delivered and returned_empty, and returned_empty outranks delivered." }, "discharge_datetime": { "type": "string", "description": "When the box was discharged, which is when free time starts counting. Null when no discharge is on file yet." }, "free_days": { "type": "integer", "description": "Free days the terms allow at this port. Null when no terms and no published tariff apply." }, "last_free_day": { "type": "string", "description": "The last day free of charge, computed from the discharge and the free days. Null when either is missing." }, "days_overdue": { "type": "integer", "description": "Days past the last free day. Zero while still inside free time." }, "terms_source": { "type": "string", "description": "Which terms priced this box: your_contract_terms when you filed terms, carrier_published_tariff when we used the published tariff for that carrier, port and equipment size." }, "terms_lane": { "type": "string", "description": "The tariff lane the published rate was read from: us_import, eu_import or asia_import. Absent when your own terms were used." }, "confidence": { "type": "string", "description": "On a card, whether the slot partners agree with each other. On a prediction, how much to trust the shifted arrival." }, "costed": { "type": "boolean", "description": "True when the row carries a real money figure. False means the timing is known but no rate applied, so treat the amount as unknown rather than zero." } }, "description": "The list of results." }, "description": "The list of results." }, "unassessable_containers": { "type": "integer", "description": "Discharged boxes we cannot assess because no free-time terms are on file. An empty risk list with a number here is not a clean bill of health." }, "coverage_note": { "type": "string", "description": "Plain-English account of what the report could not measure. Null when nothing was missing." }, "assessed_containers": { "type": "integer", "description": "How many boxes in your book we could actually assess." }, "uncosted_containers": { "type": "integer", "description": "Boxes we could time but not price, because no rate applied." }, "candidates_considered": { "type": "integer", "description": "How many boxes were examined before filtering. Read it with truncated below." }, "truncated": { "type": "boolean", "description": "True when the book was larger than one report can carry and the list was cut. An untruncated empty list means nothing was at risk; a truncated one does not." } }, "description": "The payload. Everything an endpoint returns sits under this key." }, "ContainerLookup": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable identifier for the record. On the tracking endpoints this is the container UUID, except on a portfolio summary row, where it is the container number." }, "container_number": { "type": "string", "description": "The container number, or null when the record was tracked by a bill of lading or booking that has not yet resolved to a box." }, "bl_number": { "type": [ "string", "null" ], "description": "The bill of lading, or null when the record was not tracked by one." }, "identifier": { "type": "string", "description": "The container number, bill of lading or booking this record tracks." }, "identifier_type": { "type": "string", "description": "What the identifier is. The keyed surface uses container_id, bill_of_lading or booking; the public tracker returns booking_number for the third." }, "booking_number": { "type": [ "string", "null" ], "description": "The booking reference, or null when the record was not tracked by one." }, "container_size": { "type": "string", "description": "Equipment size, for example 40HC. Null when the carrier did not state it." }, "equipment_type": { "type": "string", "description": "Equipment family as the carrier names it. Null when unstated." }, "iso_type_code": { "type": "string", "description": "The type half of the ISO 6346 code (G1 for a general-purpose box, R1 for a reefer). Null when unstated." }, "child_containers": { "type": [ "string", "null" ], "description": "The boxes a bill of lading or booking resolves to, each with its own timeline. Null on a plain container lookup." }, "status": { "type": "string", "description": "Current normalised status of the shipment. Ocean lifecycle order: discharged, available, delivered, returned_empty. Two values end a shipment, delivered and returned_empty, and returned_empty outranks delivered." }, "carrier": { "type": "string", "description": "Carrier name, falling back to the SCAC when we hold no name." }, "vessel_name": { "type": "string", "description": "Name of the carrying vessel, or null when the carrier named none." }, "vessel_imo": { "type": "string", "description": "IMO number of the carrying vessel, or null when unknown." }, "vessel_position": { "type": "object", "properties": { "lat": { "type": "number", "description": "Latitude." }, "lng": { "type": "number", "description": "Longitude." } }, "description": "Live AIS position of the carrying vessel. Null when we hold no IMO or no fix yet." }, "origin_name": { "type": "string", "description": "Origin port name, falling back to its UN/LOCODE." }, "destination_name": { "type": "string", "description": "Destination port name, falling back to its UN/LOCODE." }, "eta": { "type": "string", "description": "Arrival time (ISO 8601). Null when the carrier publishes none and we cannot predict one." }, "eta_confidence_pct": { "type": "integer", "description": "How often this lane arrives on time, as a percentage. Null on a lane too thin to score." }, "last_updated_at": { "type": "string", "description": "The more recent of the carrier check and the AIS fix: when we last learned anything about this shipment." }, "last_updated_source": { "type": "string", "description": "Which of the two produced last_updated_at: carrier_poll or ais_vessel_position. Null when neither has happened yet." }, "last_polled_at": { "type": "string", "description": "When we last asked the carrier (ISO 8601)." }, "last_ais_fix_at": { "type": "string", "description": "When the vessel was last actually observed by AIS, or null when we hold no fix." }, "field_provenance": { "type": "object", "description": "Per-field account of WHY a declared field is empty, keyed by field name. This is the difference between \"the carrier does not publish it\", \"your contract terms would unlock it\" and \"it does not apply to this shipment\". Keys are data, not contract: they vary by shipment.", "additionalProperties": { "type": "object", "properties": { "state": { "type": "string", "description": "Why the field stands where it does: resolved, contract_required, not_published, not_applicable or awaiting_carrier." }, "action": { "type": "string", "description": "What would change the state: supply_terms, wait, or do_not_expect when nothing will." }, "source": { "type": "string", "description": "Where the answer on this call came from: direct_carrier or warm_db." }, "confidence": { "type": "string", "description": "On a card, whether the slot partners agree with each other. On a prediction, how much to trust the shifted arrival." }, "evidence": { "type": "string", "description": "The reasoning behind the state, in one sentence, so a support answer does not need our source." } } } }, "demurrage_free_days_left": { "type": [ "string", "null" ], "description": "Days of free time left, or null when no terms are on file." }, "ai_narrative": { "type": [ "string", "null" ], "description": "Reserved for a written summary of the shipment. Currently always null." }, "events": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Event code, for example DEPA or LOAD." }, "classifier": { "type": "string", "description": "DCSA classifier: ACT for actual, EST for estimated, PLN for planned." }, "is_actual": { "type": "boolean", "description": "True when the event happened. False means planned or estimated." }, "label": { "type": "string", "description": "The event in plain words. A non-actual event is tagged \"(planned)\"." }, "timestamp": { "type": "string", "description": "Event timestamp (ISO 8601)." }, "event_local_datetime": { "type": "string", "description": "The port wall-clock for the same moment, naive and with no offset, exactly as a terminal prints it. Null when we could not place the port, and a null here means we do not know, never assume UTC." }, "utc_offset_minutes": { "type": "integer", "description": "Minutes to add to the UTC instant to reach the local wall-clock. Null with the local time." }, "event_timezone": { "type": "string", "description": "IANA zone of the port, which survives a DST change in a way a bare offset cannot. Null when the port could not be resolved." }, "date_only": { "type": "boolean", "description": "True when the carrier published a calendar date with no time of day. The instant then reads midnight UTC, which is padding, not an observed time: read `event_date` instead and do not convert it to another zone." }, "event_date": { "type": [ "string", "null" ], "description": "The calendar date, YYYY-MM-DD, when `date_only` is true. Null for events that carry a real time of day." }, "location": { "type": "string", "description": "UN/LOCODE for the event, or null when the carrier gave no place." } }, "description": "Milestone timeline, oldest to newest." }, "description": "Milestone timeline, oldest to newest." }, "carrier_document_reply": { "$ref": "#/components/schemas/CarrierDocumentReply", "description": "Latest retained, exact-reference OOCL document reply. Separate from shipment event history; does not imply a fresh carrier check." }, "carrier_notice": { "$ref": "#/components/schemas/CarrierNotice", "description": "Latest reference-specific reply from the named carrier. SHIPMENT_CANCELLED is an explicit matched Maersk cancellation, independent of retained movement history. no_longer_available is Swire stating it no longer serves tracking details for this shipment. ZIM notices clear after useful tracking." } }, "description": "The payload. Everything an endpoint returns sits under this key." }, "ContainerRecord": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable identifier for the record. On the tracking endpoints this is the container UUID, except on a portfolio summary row, where it is the container number." }, "org_id": { "type": "string", "description": "Your organisation. Every keyed read is scoped to it, so this is always your own id: it exists so a record stays self-describing once exported." }, "container_number": { "type": "string", "description": "The container number, or null when the record was tracked by a bill of lading or booking that has not yet resolved to a box." }, "bl_number": { "type": [ "string", "null" ], "description": "The bill of lading, or null when the record was not tracked by one." }, "booking_number": { "type": [ "string", "null" ], "description": "The booking reference, or null when the record was not tracked by one." }, "carrier_code": { "type": "string", "description": "Carrier SCAC." }, "carrier_name": { "type": "string", "description": "Carrier name." }, "iso_code": { "type": [ "string", "null" ], "description": "ISO 6346 size and type code as the carrier filed it, for example 45G1. Null when the carrier stated none." }, "size_teu": { "type": [ "integer", "null" ], "description": "Size in TEU: 1 for a 20ft box, 2 for a 40ft. Null when the size is unknown." }, "container_type": { "type": [ "string", "null" ], "description": "Plain-language equipment type, for example Reefer or Dry. Null when the carrier stated none." }, "status": { "type": "string", "description": "Current normalised status of the shipment. Ocean lifecycle order: discharged, available, delivered, returned_empty. Two values end a shipment, delivered and returned_empty, and returned_empty outranks delivered." }, "origin_unlocode": { "type": "string", "description": "Origin port UN/LOCODE, or null when the carrier named no origin we could resolve." }, "destination_unlocode": { "type": "string", "description": "Destination port UN/LOCODE, or null when unresolved." }, "origin_name": { "type": "string", "description": "Origin port name, falling back to its UN/LOCODE." }, "destination_name": { "type": "string", "description": "Destination port name, falling back to its UN/LOCODE." }, "eta": { "type": "string", "description": "Arrival time (ISO 8601). Null when the carrier publishes none and we cannot predict one." }, "eta_is_estimated": { "type": "boolean", "description": "True when the ETA is still a forecast, false when it is the actual arrival, null when there is no ETA at all. Never read a date alone as a promise." }, "eta_confidence_pct": { "type": "integer", "description": "How often this lane arrives on time, as a percentage. Null on a lane too thin to score." }, "discharge_datetime": { "type": [ "string", "null" ], "description": "When the box was discharged, which is when free time starts counting. Null when no discharge is on file yet." }, "free_days": { "type": [ "integer", "null" ], "description": "Free days the terms allow at this port. Null when no terms and no published tariff apply." }, "last_free_day": { "type": [ "string", "null" ], "description": "The last day free of charge, computed from the discharge and the free days. Null when either is missing." }, "demurrage_at_risk": { "type": "boolean", "description": "True when the free-time clock on this box is a concern." }, "demurrage_accrued_usd": { "type": [ "number", "null" ], "description": "Demurrage charged so far on this box, US dollars. Null when no rate applies, which is not the same as zero owed." }, "tags": { "type": "array", "items": {}, "description": "Your own labels on this box. Filter the list endpoint with them." }, "notes": { "type": [ "string", "null" ], "description": "Your own free-text note on this box. Null when you have written none." }, "added_at": { "type": "string", "description": "When you started tracking this box (ISO 8601)." }, "last_polled_at": { "type": "string", "description": "When we last asked the carrier (ISO 8601)." }, "poll_priority": { "type": "string", "description": "Which polling cadence this box sits in (pre_departure, transit, arrival, dwell). It decides how often we ask the carrier, and moves on its own as the shipment progresses." }, "archived_at": { "type": [ "string", "null" ], "description": "When tracking stopped, or null while the box is still active." }, "identifier": { "type": "string", "description": "The container number, bill of lading or booking this record tracks." }, "identifier_type": { "type": "string", "description": "What the identifier is. The keyed surface uses container_id, bill_of_lading or booking; the public tracker returns booking_number for the third." }, "current_vessel_imo": { "type": "string", "description": "IMO of the hull carrying the box now. Null before loading and after discharge." }, "current_voyage_id": { "type": [ "string", "null" ], "description": "Carrier voyage number for the current leg. Null when the carrier publishes none." }, "demurrage_daily_rate_usd": { "type": [ "number", "null" ], "description": "Daily demurrage rate in force at the destination, US dollars. Null when neither your terms nor a published tariff cover the port." }, "demurrage_last_free_day": { "type": [ "string", "null" ], "description": "The last day before demurrage accrues, or null when no terms are on file." }, "last_poll_trigger": { "type": [ "string", "null" ], "description": "What caused the most recent carrier check: a schedule, your recheck call, or a webhook. Null when the box has only ever been polled by the scheduler." }, "tracker_lat": { "type": [ "string", "null" ], "description": "Latitude from a physical IoT tracker on the box, when you feed us one. Null on the great majority of boxes, which have no device." }, "tracker_lng": { "type": [ "string", "null" ], "description": "Longitude from that device. Null with the latitude." }, "tracker_updated_at": { "type": [ "string", "null" ], "description": "When the device last reported. Null when there is no device." }, "tracker_has_alert": { "type": "boolean", "description": "True when the device raised an alert, for example a door opening or a temperature excursion." }, "customs_hold_reason": { "type": [ "string", "null" ], "description": "Why customs is holding the box, when the carrier names a reason. Null when there is no hold." }, "customs_hold_since": { "type": [ "string", "null" ], "description": "When the hold started. Null when there is no hold." }, "container_size": { "type": [ "string", "null" ], "description": "Equipment size, for example 40HC. Null when the carrier did not state it." }, "equipment_type": { "type": [ "string", "null" ], "description": "Equipment family as the carrier names it. Null when unstated." }, "iso_type_code": { "type": [ "string", "null" ], "description": "The type half of the ISO 6346 code (G1 for a general-purpose box, R1 for a reefer). Null when unstated." }, "unresolvable_since": { "type": [ "string", "null" ], "description": "When we gave up resolving this reference. Null while we are still trying, which is the normal state." }, "route_alert": { "type": [ "string", "null" ], "description": "A route problem we detected, for example a destination change or a missed connection. Null when the route is behaving." }, "planned_departure_at": { "type": "string", "description": "Departure the carrier planned or actually filed for the load port. Null when the carrier publishes none." }, "current_vessel_name": { "type": "string", "description": "Name of that hull. Null when we hold no name for the IMO." }, "cargo_cutoff_at": { "type": [ "string", "null" ], "description": "Cargo (gate) cutoff at the load port. Null when the carrier does not publish it, or when the ship has already sailed: read field_provenance to tell those apart." }, "vgm_cutoff_at": { "type": [ "string", "null" ], "description": "VGM filing cutoff. Null under the same rules as cargo_cutoff_at." }, "si_cutoff_at": { "type": [ "string", "null" ], "description": "Shipping-instruction cutoff. Null under the same rules as cargo_cutoff_at." }, "customs_release_cutoff_at": { "type": [ "string", "null" ], "description": "Customs-release cutoff at the load port. Null under the same rules as cargo_cutoff_at." }, "cutoff_enrichment": { "type": [ "string", "null" ], "description": "Where the cutoffs came from when they were not on the carrier response, for example a terminal schedule. Null when no enrichment ran." }, "unresolved_reason": { "type": [ "string", "null" ], "description": "Why a reference could not be resolved: invalid_number, not_found or bl_booking_unresolved. Null means resolved or still resolving." }, "updated_at": { "type": "string", "description": "When the record itself last changed in our database, which includes bookkeeping writes. For \"when did we last learn something about the shipment\", read last_updated_at." }, "archived_reason": { "type": [ "string", "null" ], "description": "Why tracking stopped: your delete call, or an automatic close-out once the box finished its cycle. Null while active." }, "identified_notified_at": { "type": [ "string", "null" ], "description": "Internal bookkeeping: when the \"container identified\" digest was sent for this box. Null when none was sent." }, "intermediary_enriched_at": { "type": [ "string", "null" ], "description": "Internal bookkeeping: when a lessor or intermediary lookup last enriched this record. Null when none has run." }, "import_batch_id": { "type": [ "string", "null" ], "description": "Groups every box created by one bulk import, so their digest fires once per batch. Null on a single manual add." }, "seal_number": { "type": [ "string", "null" ], "description": "Carrier seal on the box. Null unless the carrier publishes it, which most do not on a track response." }, "move_type": { "type": [ "string", "null" ], "description": "The scope of the move the carrier is performing, for example port to port or door to door. Null when unstated." }, "vgm_kg": { "type": [ "number", "null" ], "description": "Verified gross mass, kilograms. Null until the shipper files a VGM and the carrier publishes it." }, "gross_weight_kg": { "type": [ "number", "null" ], "description": "Gross weight of the loaded box, kilograms. Null when the carrier publishes none." }, "package_count": { "type": [ "integer", "null" ], "description": "Pieces inside the box. Null when the carrier publishes no cargo particulars." }, "package_unit": { "type": [ "string", "null" ], "description": "Unit the package count is in, for example CTN or PLT. Null with the count." }, "measurement_cbm": { "type": [ "number", "null" ], "description": "Cargo volume, cubic metres. Null when the carrier publishes none." }, "service_requirement": { "type": [ "string", "null" ], "description": "A special handling requirement filed on the shipment, for example a reefer set point. Null when none." }, "commercial_raw": { "type": [ "string", "null" ], "description": "Cargo and commercial particulars exactly as the carrier filed them, when a carrier publishes any. Null on most lines. Read the typed fields above instead: this is kept so a value we did not map is never lost." }, "tracked_from": { "type": [ "string", "null" ], "description": "The surface the box was added from. Null on records added before we recorded it." }, "source": { "type": "string", "description": "Where the answer on this call came from: direct_carrier or warm_db." }, "route_data": { "type": "object", "properties": { "route": { "type": "array", "items": { "type": "object", "properties": { "from": { "$ref": "#/components/schemas/RoutePlace", "description": "Where the leg starts." }, "to": { "$ref": "#/components/schemas/RoutePlace", "description": "Where the leg ends." }, "path": { "type": "array", "items": {}, "description": "The drawn geometry of the leg as lat and lng pairs. Empty on an inland leg, where we do not draw a line we cannot verify." }, "type": { "type": "string", "description": "Event code, for example DEPA or LOAD." }, "vessel": { "type": [ "string", "null" ], "description": "Vessel currently carrying the container, or null when we hold neither a name nor an IMO. Its lat and lng are always null here; the keyed endpoints carry the live position under vessel_position." }, "transport_type": { "type": [ "string", "null" ], "description": "The mode carrying the leg, for example VESSEL or TRUCK, when the carrier names it. Null when it does not." } }, "description": "The legs of the drawn route. This is the map geometry, and it is not the four-point route block above." }, "description": "The legs of the drawn route. This is the map geometry, and it is not the four-point route block above." }, "pin": { "type": "array", "items": { "type": "number", "description": "Where to draw the box right now, as a lat and lng pair. Null when we have nothing solid enough to place it." }, "description": "Where to draw the box right now, as a lat and lng pair. Null when we have nothing solid enough to place it." }, "pin_source": { "type": "string", "description": "How the pin was placed: ais_vessel_position from a real fix, route_reckoning when computed along the route, or a port when the box is sitting at one." }, "ais": { "type": "object", "properties": { "data": { "type": "object", "properties": { "vessel": { "type": "object", "properties": { "imo": { "type": "integer", "description": "IMO number of the vessel." }, "flag": { "type": "string", "description": "Flag state of the vessel, as a two-letter code. Null when we hold none." }, "mmsi": { "type": "integer", "description": "Vessel MMSI. Null when we hold none." }, "name": { "type": "string", "description": "Human-readable name." }, "call_sign": { "type": "string", "description": "Vessel radio call sign. Null when we hold none." } }, "description": "The hull these dates belong to." }, "last_event": { "type": "object", "properties": { "date": { "type": "string", "description": "When it happened, as a port wall-clock string without an offset, which is the layout this block has always used." }, "voyage": { "type": [ "string", "null" ], "description": "Carrier voyage number, when published. Null otherwise." }, "description": { "type": "string", "description": "The carrier own phrasing for the event, falling back to our word for the code." } }, "description": "The most recent vessel move behind these dates." }, "updated_at": { "type": "string", "description": "When this AIS block was last rebuilt." }, "arrival_port": { "$ref": "#/components/schemas/AisPortCall", "description": "The arrival call these dates describe." }, "departure_port": { "$ref": "#/components/schemas/AisPortCall", "description": "The departure call these dates describe." }, "discharge_port": { "type": "object", "properties": { "code": { "type": "string", "description": "The short port code, as above. Read locode for the standard one." }, "locode": { "type": "string", "description": "UN/LOCODE of the place." }, "date": { "type": "string", "description": "The date of the sea discharge, in the same wall-clock layout. Read date_label before treating it as an actual." }, "date_label": { "type": "string", "description": "Which kind of date the neighbouring value is: ETA, ETD, ATA or ATD. Read it before treating a date as an actual." }, "country_code": { "type": "string", "description": "ISO 3166-1 alpha-2 country code." }, "name": { "type": "string", "description": "Human-readable name." } }, "description": "The discharge call these dates describe." }, "last_vessel_position": { "type": "object", "properties": { "lat": { "type": "number", "description": "Latitude." }, "lng": { "type": "number", "description": "Longitude." }, "updated_at": { "type": "string", "description": "When the fix was taken." } }, "description": "The most recent fix for the hull, with the time it was taken." } }, "description": "The AIS-shaped payload. It is nested under a data key because that is the layout of the API this surface is compatible with, not because it is a second envelope." }, "status": { "type": "string", "description": "Whether the AIS block carries data, and why not when it does not." } }, "description": "The vessel and port dates as an AIS-shaped block, kept in the layout integrators migrating from the older API already parse. Null when we hold no vessel." }, "source": { "type": "object", "properties": { "provider": { "type": "string", "description": "Machine name of the producer." }, "provider_name": { "type": "string", "description": "Display name of the producer." }, "route_geometry": { "type": "string", "description": "How the drawn line was produced, for example trackingmcp_computed." }, "ais": { "type": "string", "description": "Which vessel-position source fed the AIS block." }, "note": { "type": "string", "description": "One sentence of provenance in plain language." } }, "description": "Who produced the route and the AIS in this block. Read it before attributing our route to anybody else." }, "pin_estimated": { "type": "boolean", "description": "True when the pin was computed rather than observed. Never present a computed pin as a sighting." }, "pin_estimated_from": { "type": [ "string", "null" ], "description": "The observation the estimate was anchored to. Null when there was none to anchor to." }, "geometry_version": { "type": "integer", "description": "Which generation of our route-drawing produced this geometry. Bumped when the drawing changes, so a cached line can be invalidated." } }, "description": "The route in the shape our map consumers read: the legs, the current pin and the AIS block. Also returned on the compatibility surface, field for field." }, "route_data_computed_at": { "type": "string", "description": "When this route block was last built." }, "equipment_owner": { "type": [ "string", "null" ], "description": "Registered owner of the box, resolved from its BIC prefix. Null when the prefix is unregistered." }, "equipment_lessor": { "type": [ "string", "null" ], "description": "Leasing company, when the box is leased rather than carrier-owned. Null otherwise." }, "lessee_name": { "type": [ "string", "null" ], "description": "Who holds the box on lease. Null unless the lessor publishes it." }, "carrier_hint_code": { "type": [ "string", "null" ], "description": "An unconfirmed carrier candidate derived from lessor data. Never a confirmed carrier: read carrier_code for that." }, "lessor_status": { "type": [ "string", "null" ], "description": "The box status as the lessor reports it, for example on-hire or off-hire. Null when we hold no lessor record." }, "lessor_checked_at": { "type": [ "string", "null" ], "description": "When we last asked the lessor. Null when we never have." }, "redelivery_reference": { "type": [ "string", "null" ], "description": "Redelivery booking for the empty. Null until one exists." }, "redelivery_date": { "type": [ "string", "null" ], "description": "When the empty is due back. Null until scheduled." }, "redelivery_location": { "type": [ "string", "null" ], "description": "Where the empty is due back. Null until scheduled." }, "redelivery_yard": { "type": [ "string", "null" ], "description": "The depot the empty is due back at. Null until scheduled." }, "lessor_contract_number": { "type": [ "string", "null" ], "description": "Lease contract the box sits on. Null unless published." }, "lessor_contract_type": { "type": [ "string", "null" ], "description": "Lease type, for example long-term or one-way. Null unless published." }, "equipment_manufacturer": { "type": [ "string", "null" ], "description": "Who built the box. Null unless the lessor publishes it." }, "lessor_on_hire_date": { "type": [ "string", "null" ], "description": "When the box went on hire. Null unless published." }, "lessor_on_hire_location": { "type": [ "string", "null" ], "description": "Where it went on hire. Null unless published." }, "lessor_on_hire_yard": { "type": [ "string", "null" ], "description": "The depot it went on hire at. Null unless published." }, "connector_status": { "type": [ "string", "null" ], "description": "Where a request to connect this carrier stands, when the line needs one. Null when the carrier is already connected." }, "connector_notify_requested_at": { "type": [ "string", "null" ], "description": "When you asked to be told the connector went live. Null when you did not ask." }, "connector_notified_at": { "type": [ "string", "null" ], "description": "When we told you it went live. Null when we have not." }, "field_provenance": { "type": "object", "description": "Per-field account of WHY a declared field is empty, keyed by field name. This is the difference between \"the carrier does not publish it\", \"your contract terms would unlock it\" and \"it does not apply to this shipment\". Keys are data, not contract: they vary by shipment.", "additionalProperties": { "type": "object", "properties": { "state": { "type": "string", "description": "Why the field stands where it does: resolved, contract_required, not_published, not_applicable or awaiting_carrier." }, "action": { "type": "string", "description": "What would change the state: supply_terms, wait, or do_not_expect when nothing will." }, "source": { "type": [ "string", "null" ], "description": "Where the answer on this call came from: direct_carrier or warm_db." }, "confidence": { "type": [ "string", "null" ], "description": "On a card, whether the slot partners agree with each other. On a prediction, how much to trust the shifted arrival." }, "evidence": { "type": "string", "description": "The reasoning behind the state, in one sentence, so a support answer does not need our source." } } } }, "field_provenance_summary": { "type": "object", "properties": { "resolved": { "type": "integer", "description": "Declared fields we hold a value for." }, "contract_required": { "type": "integer", "description": "Declared fields that stay empty until you supply your own free-time terms." }, "not_published": { "type": "integer", "description": "Declared fields this carrier does not publish." }, "not_applicable": { "type": "integer", "description": "Declared fields that do not apply to this shipment." }, "awaiting_carrier": { "type": "integer", "description": "Declared fields we expect but have not received yet." }, "unblocked_by_contract_terms": { "type": "boolean", "description": "True when supplying free-time terms would fill at least one empty field." } }, "description": "Counts of the declared cutoff and demurrage fields by state, so you can tell \"we do not have it\" from \"your contract terms would unlock it\"." }, "carrier_response_raw": { "type": [ "string", "null" ], "description": "The carrier payload behind this record, kept for support and replay. Null unless retention is on for your organisation. Not a stable shape: it is whatever that carrier sent." }, "origin_coord": { "$ref": "#/components/schemas/Coordinate", "description": "Coordinate of the origin port. Null when the port could not be placed." }, "destination_coord": { "$ref": "#/components/schemas/Coordinate", "description": "Coordinate of the destination port. Null when the port could not be placed." }, "is_demo": { "type": "boolean", "description": "True on a sample reference. Sample boxes return typical data and have no live carrier feed." }, "child_containers": { "type": [ "string", "null" ], "description": "The boxes a bill of lading or booking resolves to, each with its own timeline. Null on a plain container lookup." }, "ais_eta": { "type": [ "string", "null" ], "description": "Kept for older clients: the AIS-broadcast ETA, also present as vessel_position.eta_ais. Null when the hull broadcasts none." }, "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable identifier for the record. On the tracking endpoints this is the container UUID, except on a portfolio summary row, where it is the container number." }, "org_id": { "type": "string", "description": "Your organisation. Every keyed read is scoped to it, so this is always your own id: it exists so a record stays self-describing once exported." }, "container_id": { "type": "string", "description": "The container number this row is about." }, "dcsa_event_id": { "type": "string", "description": "The id this event carries on the DCSA /v2 surface, so the same physical event can be matched across both surfaces." }, "event_type": { "type": "string", "description": "DCSA event category: SHIPMENT, TRANSPORT or EQUIPMENT." }, "event_classifier_code": { "type": "string", "description": "DCSA classifier: ACT, EST or PLN." }, "event_date_time": { "type": "string", "description": "When the event happened or is forecast to (ISO 8601)." }, "event_created_date_time": { "type": "string", "description": "When we recorded the event, not when it happened. A late-filed event can be recorded days after the fact." }, "transport_event_type_code": { "type": [ "string", "null" ], "description": "DCSA transport code on a vessel move: ARRI for arrival, DEPA for departure. Null on an equipment event." }, "delay_reason_code": { "type": [ "string", "null" ], "description": "Carrier code for why a move slipped. Null on most lines, which publish no reason." }, "change_remark": { "type": [ "string", "null" ], "description": "The carrier own free-text remark about a change to this event. Null when it sent none." }, "equipment_event_type_code": { "type": "string", "description": "DCSA equipment code on a box move, for example GTOT for a gate-out or LOAD for a load. Null on a transport event." }, "empty_indicator_code": { "type": "string", "description": "EMPTY or LADEN on an equipment event. Present only when the carrier reported the fill state: the standard has no unknown value and we do not invent one. It is not an end-of-shipment signal." }, "equipment_reference": { "type": "string", "description": "The container the event happened to." }, "iso_equipment_code": { "type": [ "string", "null" ], "description": "ISO 6346 equipment code as filed on this event. Null when the carrier stated none." }, "shipment_event_type_code": { "type": [ "string", "null" ], "description": "DCSA shipment code on a documentation move. Null on the other two families." }, "document_id": { "type": [ "string", "null" ], "description": "The document the shipment event refers to, on the lines that publish one. Null otherwise." }, "document_type_code": { "type": [ "string", "null" ], "description": "What that document is, for example a bill of lading. Null with the id." }, "reason": { "type": [ "string", "null" ], "description": "The carrier stated reason for the event, on the lines that publish one. Null otherwise." }, "transport_call": { "type": "object", "properties": { "location": { "type": "object", "properties": { "locationName": { "type": "string", "description": "Port name as the carrier wrote it, unmapped. Read the UN/LOCODE next to it for the resolved port." }, "UNLocationCode": { "type": "string", "description": "UN/LOCODE." } }, "description": "UN/LOCODE for the event, or null when the carrier gave no place." } }, "description": "The location, vessel and voyage of the port call. Null when the carrier gave no call." }, "references": { "type": [ "string", "null" ], "description": "Extra carrier references filed against the event. Null when the carrier filed none." }, "seals": { "type": [ "string", "null" ], "description": "Seal numbers filed against the event. Null when the carrier filed none." }, "normalisation_confidence": { "type": "string", "description": "How sure we are of the normalised code: REPORTED when the carrier gave a code we map directly, INFERRED when we derived it from its wording, UNKNOWN when neither was possible." }, "supplier_raw_event_code": { "type": [ "string", "null" ], "description": "The code the source used, before normalisation. Null when the source sent no code." }, "supplier_raw_payload": { "type": [ "string", "null" ], "description": "The source own event object, kept verbatim. Null when nothing needed keeping. Not a stable shape." }, "created_at": { "type": "string", "description": "When the record was created (ISO 8601)." }, "event_id": { "type": [ "string", "null" ], "description": "The carrier own id for the event, when it publishes one. Null on most lines. Read id for our stable id." }, "event_datetime": { "type": "string", "description": "Same instant as event_date_time, under the name the earlier API used. Kept so old integrations keep working." }, "event_code": { "type": "string", "description": "Machine-readable event code, for example LOAD, DISC, GTIN, GTOT, ARRI, DEPA. Null when the carrier sent none." }, "raw_payload": { "type": "object", "properties": { "datetime": { "type": "string", "description": "Event timestamp (ISO 8601), or null when the carrier gave none." }, "timezone": { "type": "string", "description": "IANA time zone of the place. Null when we could not resolve the port." }, "unlocode": { "type": "string", "description": "UN/LOCODE port code. On a tracking event it is canonicalised, and null when the carrier named no port." }, "is_actual": { "type": "boolean", "description": "True when the event happened. False means planned or estimated." }, "port_name": { "type": "string", "description": "Resolved port name." }, "event_code": { "type": "string", "description": "Machine-readable event code, for example LOAD, DISC, GTIN, GTOT, ARRI, DEPA. Null when the carrier sent none." }, "vessel_imo": { "type": [ "string", "null" ], "description": "IMO number of the carrying vessel, or null when unknown." }, "description": { "type": "string", "description": "The carrier own phrasing for the event, falling back to our word for the code." }, "source_kind": { "type": "string", "description": "Which kind of source produced the event: carrier when the line answered directly; any other value means the event reached us another way." }, "vessel_name": { "type": [ "string", "null" ], "description": "Name of the carrying vessel, or null when the carrier named none." }, "event_family": { "type": "string", "description": "Which family the code belongs to: EQUIPMENT, TRANSPORT or SHIPMENT." }, "voyage_number": { "type": [ "string", "null" ], "description": "Carrier voyage number." }, "datetime_basis": { "type": "string", "description": "What the stored instant MEANS: utc for a true instant, port_local for a wall-clock we could not place. Every value on the documented fields above is already a true instant." }, "datetime_local": { "type": "string", "description": "The port wall-clock carried alongside the instant, inside the raw payload." }, "time_semantics": { "type": "string", "description": "How the instant was established during normalisation. Diagnostic, not contract." }, "transport_mode": { "type": [ "string", "null" ], "description": "Mode the source named for the move. Null when it named none." }, "datetime_precision": { "type": "string", "description": "How precise the carrier was: datetime, or date when it gave a day with no time. A date-only event must never be read as midnight." }, "utc_offset_minutes": { "type": "integer", "description": "Minutes to add to the UTC instant to reach the local wall-clock. Null with the local time." }, "source_resolve_method": { "type": "string", "description": "The exact rung the source was resolved on, kept verbatim so a coarse bucket never hides the detail. Diagnostic." } }, "description": "The connector event exactly as it was stored, so a value we did not map is never lost. Treat it as evidence, not as API surface: its keys vary by carrier." }, "event_local_datetime": { "type": "string", "description": "The port wall-clock for the same moment, naive and with no offset, exactly as a terminal prints it. Null when we could not place the port, and a null here means we do not know, never assume UTC." }, "utc_offset_minutes": { "type": "integer", "description": "Minutes to add to the UTC instant to reach the local wall-clock. Null with the local time." }, "event_timezone": { "type": "string", "description": "IANA zone of the port, which survives a DST change in a way a bare offset cannot. Null when the port could not be resolved." }, "date_only": { "type": "boolean", "description": "True when the carrier published a calendar date with no time of day. The instant then reads midnight UTC, which is padding, not an observed time: read `event_date` instead and do not convert it to another zone." }, "event_date": { "type": [ "string", "null" ], "description": "The calendar date, YYYY-MM-DD, when `date_only` is true. Null for events that carry a real time of day." }, "event_time_semantics": { "type": "string", "description": "Internal marker for how this row timestamp was established. Do not branch on it: read the UTC instant and, if you need port time, its three local companions." }, "event_name": { "type": "string", "description": "The step in plain language, for example Gated out." } }, "description": "Milestone timeline, oldest to newest." }, "description": "Milestone timeline, oldest to newest." }, "journey_timeline": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable identifier for the record. On the tracking endpoints this is the container UUID, except on a portfolio summary row, where it is the container number." }, "kind": { "type": "string", "description": "carrier_event when a carrier filed it, trackingmcp_inference when we derived the step from surrounding events." }, "classifier": { "type": "string", "description": "DCSA classifier: ACT for actual, EST for estimated, PLN for planned." }, "occurred_at": { "type": "string", "description": "When the step happened (UTC). Null when the source gave a wall-clock we could not place." }, "event_name": { "type": "string", "description": "The step in plain language, for example Gated out." }, "port_unlocode": { "type": "string", "description": "Resolved port UN/LOCODE. Null when the carrier location could not be placed." }, "port_name": { "type": "string", "description": "Resolved port name." }, "facility_name": { "type": [ "string", "null" ], "description": "Terminal or depot inside the port, when the carrier names one. Null otherwise." }, "evidence_event_ids": { "type": "array", "items": { "type": "string", "description": "The event ids this step was built from, so an inference can always be traced back." }, "description": "The event ids this step was built from, so an inference can always be traced back." }, "confidence": { "type": "string", "description": "On a card, whether the slot partners agree with each other. On a prediction, how much to trust the shifted arrival." }, "label": { "type": "string", "description": "The event in plain words. A non-actual event is tagged \"(planned)\"." }, "port_role": { "type": [ "string", "null" ], "description": "The role the port plays on this route: origin, transshipment or destination. Null when the route is not resolved enough to say." }, "milestone": { "type": [ "string", "null" ], "description": "The voyage milestone this step marks, when it marks one. Null on ordinary steps." } }, "description": "The shipment as a reader story: carrier events plus the moves we inferred between them, in order. Empty until the first event lands." }, "description": "The shipment as a reader story: carrier events plus the moves we inferred between them, in order. Empty until the first event lands." }, "exceptions": { "type": "array", "items": {}, "description": "Count of shipments in an exception state: customs hold, rolled, delayed or at transshipment." }, "history_days": { "type": "integer", "description": "How far back the timeline reaches on your plan, in days." }, "current_leg": { "type": [ "string", "null" ], "description": "The leg the box is on now. Null before departure and after final discharge." }, "legs": { "type": "array", "items": {}, "description": "The voyage broken into legs. Empty when we cannot yet split it." }, "vessel_position": { "type": "object", "properties": { "imo": { "type": "string", "description": "IMO number of the vessel." }, "name": { "type": "string", "description": "Human-readable name." }, "lat": { "type": "number", "description": "Latitude." }, "lng": { "type": "number", "description": "Longitude." }, "speed_knots": { "type": "integer", "description": "Speed over ground, in knots." }, "heading_deg": { "type": "integer", "description": "Heading in degrees." }, "nav_status": { "type": "string", "description": "Navigational status as reported by AIS, for example \"Under way using engine\" or \"Moored\". We drop a moored or anchored claim that the position contradicts." }, "position_updated_at": { "type": "string", "description": "When we last wrote the position row." }, "position_fix_at": { "type": "string", "description": "When the hull was actually observed. This, not position_updated_at, is the age that matters." }, "eta_ais": { "type": "string", "description": "The destination ETA the vessel itself is broadcasting, which is the master own entry and often disagrees with the carrier. Null when the hull broadcasts none." }, "destination_unlocode": { "type": "string", "description": "Destination port UN/LOCODE, or null when unresolved." }, "photo_url": { "type": "string", "description": "Photograph of the hull. Null when we hold none." }, "particulars_updated_at": { "type": "string", "description": "When the vessel particulars were last refreshed." }, "reported_nav_status": { "type": "string", "description": "The navigational status the vessel broadcasts, unchecked." }, "nav_status_verified": { "type": "boolean", "description": "False when the broadcast status contradicts where the vessel actually is, for example Moored while far from any port. Then read nav_status, which we correct." }, "nav_status_reason": { "type": "string", "description": "Why the broadcast status was not trusted, for example outside_port_geofence. Null when it was trusted." }, "nearest_port_nm": { "type": "number", "description": "Distance to the nearest port, nautical miles, which is the evidence behind the check. Null when the status needed no checking." } }, "description": "Live AIS position of the carrying vessel. Null when we hold no IMO or no fix yet." }, "pin_source": { "type": "string", "description": "How the pin was placed: ais_vessel_position from a real fix, route_reckoning when computed along the route, or a port when the box is sitting at one." }, "pin_basis": { "type": "string", "description": "What the reckoning leaned on when the pin was computed rather than observed, for example a published schedule." }, "pin_estimated_from": { "type": [ "string", "null" ], "description": "The observation the estimate was anchored to. Null when there was none to anchor to." }, "observed_position": { "type": "object", "properties": { "lat": { "type": "number", "description": "Latitude." }, "lng": { "type": "number", "description": "Longitude." }, "observed_at": { "type": "string", "description": "When the fix was taken." }, "quality": { "type": "string", "description": "How exact the fix is: precise for a terrestrial fix, coarse for a satellite one." }, "accuracy_km": { "type": [ "number", "null" ], "description": "Radius the fix is good to, kilometres. Null when the source states no accuracy." } }, "description": "The last position we actually observed, never a computed one. Null when the hull has no fix on record." }, "estimated_position": { "type": "object", "properties": { "lat": { "type": "number", "description": "Latitude." }, "lng": { "type": "number", "description": "Longitude." }, "estimated_at": { "type": "string", "description": "The moment the estimate describes." }, "based_on_observation_at": { "type": [ "string", "null" ], "description": "The observation the estimate was reckoned from. Null when the reckoning had no fix to start from and leaned on the schedule alone." }, "classification": { "type": "string", "description": "Which reckoning class produced the estimate. Diagnostic detail for support, not something to branch on." }, "method": { "type": "string", "description": "How the position was produced, for example route_reckoning." } }, "description": "A computed position, for when there is no fresh fix. Always labelled as computed; never merge the two blocks." }, "vessel_photo": { "type": "object", "properties": { "url": { "type": "string", "description": "Where we POST the events." }, "source": { "type": "string", "description": "Where the answer on this call came from: direct_carrier or warm_db." }, "retrieved_at": { "type": "string", "description": "When we fetched the photograph." } }, "description": "Photograph of the current hull with its attribution. Null when we hold none." }, "last_updated_at": { "type": "string", "description": "The more recent of the carrier check and the AIS fix: when we last learned anything about this shipment." }, "last_updated_source": { "type": "string", "description": "Which of the two produced last_updated_at: carrier_poll or ais_vessel_position. Null when neither has happened yet." }, "last_ais_fix_at": { "type": "string", "description": "When the vessel was last actually observed by AIS, or null when we hold no fix." }, "vessel_names": { "type": "object", "description": "IMO to name map covering every leg, so an onward vessel can be named without a second call. Empty when no leg carries a hull we can name. Keys are data, not contract: they vary by shipment.", "additionalProperties": {} }, "transshipment": { "type": [ "string", "null" ], "description": "The hub the box is dwelling at and its onward vessel. Null unless it is dwelling." }, "schedule_overlay": { "type": "object", "properties": { "source": { "type": "string", "description": "Where the answer on this call came from: direct_carrier or warm_db." }, "match": { "type": "string", "description": "How strongly the sailing matches the box, strongest first: vessel_voyage, vessel_lane, vessel_route, onward_vessel_lane, lane, carrier_lane. Weaker matches are context, not proof." }, "carrier_code": { "type": "string", "description": "Carrier SCAC." }, "service_name": { "type": "string", "description": "Carrier service or loop name." }, "vessel_imo": { "type": "string", "description": "IMO number of the carrying vessel, or null when unknown." }, "voyage_number": { "type": "string", "description": "Carrier voyage number." }, "published_departure": { "type": "string", "description": "The departure the carrier published (ISO 8601). Null when it published none." }, "published_arrival": { "type": "string", "description": "The arrival the carrier published (ISO 8601). Null when it published none." }, "transit_days": { "type": "integer", "description": "Port-to-port transit in days." }, "is_transshipment": { "type": "boolean", "description": "True when the box changes vessel on the way." }, "legs": { "type": "array", "items": { "type": "object", "properties": { "seq": { "type": "integer", "description": "Position of the leg in the rotation, starting at 1." }, "from_unlocode": { "type": "string", "description": "UN/LOCODE the leg departs." }, "to_unlocode": { "type": "string", "description": "UN/LOCODE the leg arrives at." }, "from_name": { "type": "string", "description": "Name of the departure port." }, "to_name": { "type": "string", "description": "Name of the arrival port." }, "vessel_name": { "type": "string", "description": "Name of the carrying vessel, or null when the carrier named none." }, "voyage": { "type": "string", "description": "Carrier voyage number, when published. Null otherwise." }, "service": { "type": "string", "description": "Carrier service or loop name." }, "etd": { "type": "string", "description": "Estimated time of departure (ISO 8601)." }, "eta": { "type": "string", "description": "Arrival time (ISO 8601). Null when the carrier publishes none and we cannot predict one." } }, "description": "The voyage broken into legs. Empty when we cannot yet split it." }, "description": "The voyage broken into legs. Empty when we cannot yet split it." } }, "description": "The published vessel rotation we matched this box to, which is the plan against which actuals can be read. Null when nothing matched." }, "eta_intel": { "type": "object", "properties": { "basis": { "type": "string", "description": "What the reliability figures were computed from, which tells you how much to lean on them." }, "carrier_scoped": { "type": "boolean", "description": "True when the statistics are for THIS carrier on this lane, false when they are lane-level across all carriers and therefore coarser." }, "confidence_pct": { "type": "integer", "description": "On-time percentage for the lane, which is the same number the ring shows." }, "on_time_pct": { "type": "integer", "description": "Share of sailings that arrived on time." }, "median_delay_hours": { "type": [ "number", "null" ], "description": "Typical delay on the lane, hours. Null on a lane too thin to score." }, "p90_delay_hours": { "type": "integer", "description": "Delay that 90 percent of arrivals stay inside, hours. Null on a thin lane." }, "observations": { "type": "integer", "description": "Number of observed sailings behind the figure." }, "window_days": { "type": "integer", "description": "How far back those observations reach, days." }, "band_low": { "type": "string", "description": "Best case: the published ETA, arriving on time. Null when there is no ETA to anchor to." }, "band_high": { "type": "string", "description": "The date 90 percent of arrivals land by. Null when there is no ETA to anchor to." }, "expected": { "type": "string", "description": "The typical outcome: the ETA plus the median delay. Null when there is no ETA to anchor to." }, "transit_p50_hours": { "type": [ "number", "null" ], "description": "Median transit time on the lane, hours. Null on a thin lane." }, "transit_p90_hours": { "type": [ "number", "null" ], "description": "Transit time 90 percent of sailings stay inside, hours. Null on a thin lane." } }, "description": "Probability envelope and reliability context. Null on thin lanes." }, "eta_at_risk": { "type": [ "string", "null" ], "description": "Congestion warning. Null unless the next port is congested or the vessel has waited at anchor." }, "observability": { "type": "object", "properties": { "lenses": { "type": "object", "properties": { "actuals": { "type": "boolean", "description": "True when we hold carrier milestones." }, "position": { "type": "boolean", "description": "True when we hold a vessel." }, "plan": { "type": "boolean", "description": "On LoadingMCP, the computed load plan. Inside a tracking observability lens, true when we hold a schedule for the shipment." }, "probability": { "type": "boolean", "description": "True when the ETA can carry a confidence figure." } }, "description": "actuals (carrier milestones), position (the vessel), plan (a schedule) and probability (a confidence figure)." }, "active_count": { "type": "integer", "description": "How many of the four lenses are present." }, "agreement": { "type": "string", "description": "Whether the sources tell the same story: aligned, diverging, partial, or insufficient when there are too few to compare." }, "eta_sources": { "type": "array", "items": { "type": "object", "properties": { "lens": { "type": "string", "description": "Which source this ETA came from: carrier, published or ais." }, "eta": { "type": "string", "description": "Arrival time (ISO 8601). Null when the carrier publishes none and we cannot predict one." } }, "description": "The ETA each cross-checkable source implies, so a disagreement can be seen rather than averaged away." }, "description": "The ETA each cross-checkable source implies, so a disagreement can be seen rather than averaged away." }, "max_spread_hours": { "type": "integer", "description": "Hours between the furthest-apart ETA sources. Null when fewer than two sources have an ETA." } }, "description": "Which of the four lenses we can offer on this shipment, and how many are active." }, "ai_insight": { "type": [ "string", "null" ], "description": "A written read of the shipment state. Null when none has been generated for this box." }, "ai_insight_pending": { "type": "boolean", "description": "True while one is being generated, so a client can poll instead of showing an empty space." }, "carrier_document_reply": { "$ref": "#/components/schemas/CarrierDocumentReply", "description": "Latest retained, exact-reference OOCL document reply. Separate from shipment event history; does not imply a fresh carrier check." }, "carrier_notice": { "$ref": "#/components/schemas/CarrierNotice", "description": "Latest reference-specific reply from the named carrier. SHIPMENT_CANCELLED is an explicit matched Maersk cancellation, independent of retained movement history. no_longer_available is Swire stating it no longer serves tracking details for this shipment. ZIM notices clear after useful tracking." } }, "description": "The payload. Everything an endpoint returns sits under this key." }, "ArchivedContainer": { "type": "object", "properties": { "archived": { "type": "boolean", "description": "True when the container was archived." }, "id": { "type": "string", "description": "Stable identifier for the record. On the tracking endpoints this is the container UUID, except on a portfolio summary row, where it is the container number." } }, "description": "The payload. Everything an endpoint returns sits under this key." }, "RecheckStarted": { "type": "object", "properties": { "recheck": { "type": "string", "description": "Reads \"started\" once the re-poll is queued." }, "id": { "type": "string", "description": "Stable identifier for the record. On the tracking endpoints this is the container UUID, except on a portfolio summary row, where it is the container number." } }, "description": "The payload. Everything an endpoint returns sits under this key." }, "RoutePlace": { "type": "object", "properties": { "lat": { "type": "number", "description": "Latitude." }, "lng": { "type": "number", "description": "Longitude." }, "name": { "type": "string", "description": "Human-readable name." }, "state": { "type": "string", "description": "State, province or region of the port, when the gazetteer holds one." }, "locode": { "type": "string", "description": "UN/LOCODE of the place." }, "country": { "type": "string", "description": "Country name." }, "timezone": { "type": "string", "description": "IANA time zone of the place. Null when we could not resolve the port." }, "country_code": { "type": "string", "description": "ISO 3166-1 alpha-2 country code." } }, "description": "Where the leg starts." }, "AisPortCall": { "type": "object", "properties": { "code": { "type": "string", "description": "The short port code the compatible API prints next to the UN/LOCODE. Read locode for the standard one." }, "locode": { "type": "string", "description": "UN/LOCODE of the place." }, "date": { "type": "string", "description": "The date of the call, as a port wall-clock string with no offset, which is the layout this block has always used. Read date_label to know whether it is an estimate or an actual." }, "date_label": { "type": "string", "description": "Which kind of date the neighbouring value is: ETA, ETD, ATA or ATD. Read it before treating a date as an actual." }, "country_code": { "type": "string", "description": "ISO 3166-1 alpha-2 country code." } }, "description": "The arrival call these dates describe." }, "Coordinate": { "type": "object", "properties": { "lat": { "type": "number", "description": "Latitude." }, "lng": { "type": "number", "description": "Longitude." }, "approximate": { "type": "boolean", "description": "True when the coordinate is a place centroid rather than a terminal position. Do not measure distances against an approximate point." }, "approx_from": { "type": [ "string", "null" ], "description": "What the approximate point was derived from. Null when the coordinate is exact." } }, "description": "Coordinate of the origin port. Null when the port could not be placed." }, "CarrierNotice": { "type": "object", "nullable": true, "description": "Latest reference-specific reply from the named carrier. SHIPMENT_CANCELLED is an explicit matched Maersk cancellation, independent of retained movement history. no_longer_available is Swire stating it no longer serves tracking details for this shipment. ZIM notices clear after useful tracking.", "properties": { "carrier_code": { "type": "string", "enum": [ "ZIMU", "MAEU", "CHVW" ] }, "reference": { "type": "string" }, "reference_type": { "type": "string", "enum": [ "container", "bl", "booking" ] }, "status": { "type": "string", "enum": [ "other_carrier", "temporarily_unavailable", "not_found", "invalid_reference", "SHIPMENT_CANCELLED", "no_longer_available" ] }, "message": { "type": "string" }, "checked_at": { "type": "string", "format": "date-time" }, "suggested_carrier": { "type": "string", "nullable": true }, "suggested_url": { "type": "string", "nullable": true, "format": "uri" } } }, "CarrierDocumentReply": { "type": "object", "nullable": true, "description": "Latest retained, exact-reference OOCL document reply. Separate from shipment event history; does not imply a fresh carrier check.", "properties": { "carrier_code": { "type": "string", "enum": [ "OOLU" ] }, "reference": { "type": "string" }, "reference_type": { "type": "string", "enum": [ "bl", "booking" ] }, "status": { "type": "string", "enum": [ "cancelled", "declined" ] }, "carrier_reference": { "type": "string" } } } } }, "security": [ { "bearerAuth": [] } ], "webhooks": { "containerStatusEvent": { "post": { "summary": "A status transition: container_arrived, container_available, container_delivered, customs_hold, vessel_departed, demurrage_started or demurrage_warning. Shown here under container_arrived; the other six carry the same data shape with their own type.", "operationId": "webhook_container_arrived", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookDeliveryEnvelope" } ], "properties": { "type": { "const": "container_arrived" }, "data": { "$ref": "#/components/schemas/WebhookStatusEventData" } } } } } }, "responses": { "2XX": { "description": "Acknowledged. Any 2xx stops retries." } } } }, "etaChanged": { "post": { "summary": "The carrier moved the ETA by 24h or more.", "operationId": "webhook_eta_changed", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookDeliveryEnvelope" } ], "properties": { "type": { "const": "eta_changed" }, "data": { "$ref": "#/components/schemas/WebhookEtaChangedData" } } } } } }, "responses": { "2XX": { "description": "Acknowledged. Any 2xx stops retries." } } } }, "scheduleDisruption": { "post": { "summary": "The matched sailing slipped materially or did not depart.", "operationId": "webhook_schedule_disruption", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookDeliveryEnvelope" } ], "properties": { "type": { "const": "schedule_disruption" }, "data": { "$ref": "#/components/schemas/WebhookScheduleDisruptionData" } } } } } }, "responses": { "2XX": { "description": "Acknowledged. Any 2xx stops retries." } } } }, "containerMisrouted": { "post": { "summary": "Discharged at a port that is neither destination nor transshipment.", "operationId": "webhook_container_misrouted", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookDeliveryEnvelope" } ], "properties": { "type": { "const": "container_misrouted" }, "data": { "$ref": "#/components/schemas/WebhookMisroutedData" } } } } } }, "responses": { "2XX": { "description": "Acknowledged. Any 2xx stops retries." } } } }, "apiChangeAnnounced": { "post": { "summary": "An API change announced ahead of its effective date.", "operationId": "webhook_api_change_announced", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookDeliveryEnvelope" } ], "properties": { "type": { "const": "api_change_announced" }, "data": { "$ref": "#/components/schemas/WebhookApiChangeData" } } } } } }, "responses": { "2XX": { "description": "Acknowledged. Any 2xx stops retries." } } } } } }