{"openapi":"3.1.0","info":{"contact":{"email":"support@navlo.io","name":"Navlo","url":"https://navlo.io"},"description":"Track ocean and air shipments, read Navlo's shipment intelligence, manage customers, webhooks and Navlo AI. Authenticate with the X-API-Key header.","title":"Navlo API","version":"v1"},"servers":[{"url":"https://api.navlo.io","description":"Production"}],"security":[{"ApiKeyAuth":[]}],"tags":[{"description":"The tracking widget's backend: look up one of your tracked shipments by the number your customer typed.","name":"Embed"},{"description":"Credit balances and the usage report you re-bill your customers from.","name":"Usage & credits"},{"description":"Register https endpoints that Navlo POSTs shipment events to, signed with HMAC-SHA256.","name":"Webhooks"},{"description":"Follow a vessel on its voyage: live position, ETA, port calls and events, like Vessel Tracking in the app. A voyage costs 2 tracking credits, nothing when one of your active container shipments is on the vessel.","name":"Vessels"},{"description":"Your customers (shown as Companies in the app) and your own reference for each.","name":"Customers"},{"description":"Start tracking ocean and air shipments, list and read them, file them under your customers, and stop, resume or delete them.","name":"Shipments"},{"description":"Navlo's view of a shipment beyond the carrier's data, opt-in on GET /v1/shipments/{id} with `include`: risk, recommended actions, Navlo ETA, D&D free time, carbon, route alerts, customer, tags and operational details.","name":"Shipment intelligence"},{"description":"Ask Navlo AI about your shipments. Answers stream as Server-Sent Events by default; send `\"stream\": false` for one JSON answer. Costs AI credits; 10 requests per minute per key, and at most 2 answers running at once per organization.","name":"Navlo AI"},{"description":"Port congestion (vessels waiting at anchor and their waiting time, judged against each port's own baseline, sampled daily) and airport delays, as Navlo's map layers show them.","name":"Ports & airports"}],"paths":{"/api/embed/resolve":{"get":{"description":"Exact-match lookup of a container, Master B/L, booking or Master AWB number among the shipments your organization already tracks. Never starts a tracking or spends credits. Answers the read-only public shipment view the share links use. 401 invalid or revoked embed key, 403 origin not allowed, 404 not tracked, 429 more than 60 lookups in a minute for this key (see `Retry-After`).","operationId":"resolveEmbed","parameters":[{"description":"The embed key (nvle_…) as a query parameter, for the iframe. Prefer the X-Embed-Key header.","in":"query","name":"key","required":false,"schema":{"type":"string"}},{"description":"The exact number your customer typed: container, Master B/L, booking or Master AWB.","example":"MEDU1234562","in":"query","name":"number","required":true,"schema":{"type":"string"}},{"description":"The origin of the page embedding the widget. Required, and checked, when the key pins allowed origins.","in":"query","name":"parentOrigin","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicShipmentResponse"}}},"description":"The public shipment view."}},"security":[{"EmbedKeyAuth":[]}],"summary":"Resolve a tracked shipment for the embed widget","tags":["Embed"]}},"/v1/ai/ask":{"post":{"description":"Starts a new conversation and answers its first question. Pass `shipmentId` to ask about one shipment, `customer` to bill the AI credits to one of your customers in the usage report.\n\n**Streaming (default).** The response is `text/event-stream`; every `data:` line is one JSON object. Send `\"stream\": false` to get the `result` object as one JSON body instead.\n\n- `started` `{conversationId, messageId}` — your question is stored (`messageId` is its id). Always first.\n- `step` `{label}` — Navlo AI started a lookup; `label` is the text the app shows. Text streamed before a `step` was Navlo AI thinking aloud and is not part of the answer — clear it.\n- `text` `{delta}` — answer text as it is written (raw markdown, ```chart fences included).\n- `result` `{conversationId, messageId, answer, shipments, charts, files, creditsUsed}` — the finished answer; render this one. `answer` is markdown without ```chart blocks (those are parsed into `charts`), `files` are the documents it generated (download links valid for 7 days), `shipments` are your shipments it is about.\n- `error` `{message, code}` — no answer: `insufficient_credits`, `rejected` (not a logistics question), `busy` (retry in a minute), `timeout` (5 minutes), `internal`.\n\nThe stream ends after `result` or `error`. Problems found before it starts (invalid body, unknown shipment or conversation, or `429` while your organization already has 2 answers running) are ordinary HTTP errors. With `stream: false` the codes answer as 402, 422, 503, 504 and 500 with the body `{error, message, code}`. Each answer uses AI credits; `creditsUsed` says how many.","operationId":"askNavloAi","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiAskRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiResult"}},"text/event-stream":{"schema":{"type":"string"}}},"description":"An event stream, or with `stream: false` the finished answer."},"400":{"content":{"application/json":{}},"description":"Invalid body or customer."},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiError"}}},"description":"`stream: false` — no AI credits (`insufficient_credits`). A stream reports it as an `error` event."},"404":{"content":{"application/json":{}},"description":"Unknown shipment."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiError"}}},"description":"`stream: false` — not a logistics question (`rejected`). A stream reports it as an `error` event."},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiError"}}},"description":"`stream: false` — the AI service is busy; retry in a minute (`busy`)."},"504":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiError"}}},"description":"`stream: false` — no answer within 5 minutes (`timeout`). If it finishes later, it is stored on the conversation."}},"summary":"Ask a question","tags":["Navlo AI"]}},"/v1/ai/conversations":{"get":{"description":"The key creator's Navlo AI conversations, most recently active first — the ones started in the app included.","operationId":"listConversations","parameters":[{"description":"0-based page.","in":"query","name":"page","required":false,"schema":{"type":"integer","format":"int32","default":0}},{"description":"Page size, 1–100.","in":"query","name":"size","required":false,"schema":{"type":"integer","format":"int32","default":20}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiConversationPage"}}},"description":"OK"}},"summary":"List conversations","tags":["Navlo AI"]},"post":{"description":"An empty conversation to ask follow-up questions in. Without a `title`, Navlo AI titles it from its first exchange.","operationId":"createConversation","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiConversationCreateRequest"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiConversation"}}},"description":"OK"}},"summary":"Start a conversation","tags":["Navlo AI"]}},"/v1/ai/conversations/{id}":{"delete":{"description":"Removes it here and from the app. The credits it used stay in your usage report.","operationId":"deleteConversation","parameters":[{"description":"Conversation id.","in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Deleted."}},"summary":"Delete a conversation","tags":["Navlo AI"]},"get":{"description":"The conversation with every message, oldest first.","operationId":"getConversation","parameters":[{"description":"Conversation id.","in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiConversationDetail"}}},"description":"OK"}},"summary":"Get a conversation","tags":["Navlo AI"]}},"/v1/ai/conversations/{id}/messages":{"post":{"description":"Asks the next question in a conversation; Navlo AI reads the earlier turns.\n\n**Streaming (default).** The response is `text/event-stream`; every `data:` line is one JSON object. Send `\"stream\": false` to get the `result` object as one JSON body instead.\n\n- `started` `{conversationId, messageId}` — your question is stored (`messageId` is its id). Always first.\n- `step` `{label}` — Navlo AI started a lookup; `label` is the text the app shows. Text streamed before a `step` was Navlo AI thinking aloud and is not part of the answer — clear it.\n- `text` `{delta}` — answer text as it is written (raw markdown, ```chart fences included).\n- `result` `{conversationId, messageId, answer, shipments, charts, files, creditsUsed}` — the finished answer; render this one. `answer` is markdown without ```chart blocks (those are parsed into `charts`), `files` are the documents it generated (download links valid for 7 days), `shipments` are your shipments it is about.\n- `error` `{message, code}` — no answer: `insufficient_credits`, `rejected` (not a logistics question), `busy` (retry in a minute), `timeout` (5 minutes), `internal`.\n\nThe stream ends after `result` or `error`. Problems found before it starts (invalid body, unknown shipment or conversation, or `429` while your organization already has 2 answers running) are ordinary HTTP errors. With `stream: false` the codes answer as 402, 422, 503, 504 and 500 with the body `{error, message, code}`. Each answer uses AI credits; `creditsUsed` says how many.","operationId":"sendMessage","parameters":[{"description":"Conversation id.","in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiMessageRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiResult"}},"text/event-stream":{"schema":{"type":"string"}}},"description":"An event stream, or with `stream: false` the finished answer."},"400":{"content":{"application/json":{}},"description":"Invalid body."},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiError"}}},"description":"`stream: false` — no AI credits (`insufficient_credits`). A stream reports it as an `error` event."},"404":{"content":{"application/json":{}},"description":"Unknown conversation."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiError"}}},"description":"`stream: false` — not a logistics question (`rejected`). A stream reports it as an `error` event."},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiError"}}},"description":"`stream: false` — the AI service is busy; retry in a minute (`busy`)."},"504":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiError"}}},"description":"`stream: false` — no answer within 5 minutes (`timeout`). If it finishes later, it is stored on the conversation."}},"summary":"Ask a follow-up","tags":["Navlo AI"]}},"/v1/airports/delays":{"get":{"description":"The latest delay sample of each airport Navlo watches: average delay and ground stops.","operationId":"airportDelays","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AirportDelayList"}}},"description":"OK"}},"summary":"List airport delays","tags":["Ports & airports"]}},"/v1/credits":{"get":{"description":"What the API key can spend now: tracking credits (shipments, vessel tracking) and Navlo AI credits. For a key created by an organization admin these are the organization's pools.","operationId":"getCredits","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditBalances"}}},"description":"OK"}},"summary":"Credit balances","tags":["Usage & credits"]}},"/v1/customers":{"get":{"description":"Your customers in name order, archived ones only with includeArchived=true. `search` matches name, ref or tax id (contains, case-insensitive); `ref` is an exact, case-insensitive match.","operationId":"listCustomers","parameters":[{"description":"Text contained in the name, ref or tax id.","example":"acme","in":"query","name":"search","required":false,"schema":{"type":"string"}},{"description":"Your own reference, exact match (case-insensitive).","example":"C-1042","in":"query","name":"ref","required":false,"schema":{"type":"string"}},{"description":"Include archived customers.","in":"query","name":"includeArchived","required":false,"schema":{"type":"boolean","default":false}},{"description":"0-based page number.","in":"query","name":"page","required":false,"schema":{"type":"integer","format":"int32","default":0}},{"description":"Page size, 1 to 100.","in":"query","name":"size","required":false,"schema":{"type":"integer","format":"int32","default":20}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerPage"}}},"description":"OK"}},"summary":"List customers","tags":["Customers"]},"post":{"description":"Only `name` is required. A name or ref another customer already has is refused (400 for a name, 409 for a ref) — archived customers count too.","operationId":"createCustomer","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerCreateRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Customer"}}},"description":"OK"}},"summary":"Create a customer","tags":["Customers"]}},"/v1/customers/{id}":{"get":{"description":"Archived customers are returned too (`archived: true`).","operationId":"getCustomer","parameters":[{"description":"Navlo's customer id.","in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Customer"}}},"description":"OK"}},"summary":"Get a customer","tags":["Customers"]},"patch":{"description":"Partial update: only the keys you send change; `null` or \"\" clears an optional field; `contacts` replaces the whole list.","operationId":"updateCustomer","parameters":[{"description":"Navlo's customer id.","in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerPatchRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Customer"}}},"description":"OK"}},"summary":"Update a customer","tags":["Customers"]}},"/v1/customers/{id}/archive":{"post":{"description":"Hides the customer from the app's directory and pickers; its shipments keep it and its reports pause. Archived customers still resolve by id or ref. Idempotent.","operationId":"archiveCustomer","parameters":[{"description":"Navlo's customer id.","in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Customer"}}},"description":"OK"}},"summary":"Archive a customer","tags":["Customers"]}},"/v1/customers/{id}/restore":{"post":{"description":"Idempotent.","operationId":"restoreCustomer","parameters":[{"description":"Navlo's customer id.","in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Customer"}}},"description":"OK"}},"summary":"Restore an archived customer","tags":["Customers"]}},"/v1/ports/congestion":{"get":{"description":"The latest daily congestion sample per port, most congested first. By default the ports on your active ocean shipments (origin, destination, current port); scope=all lists every port Navlo samples.","operationId":"portCongestion","parameters":[{"description":"shipments (default) or all.","in":"query","name":"scope","required":false,"schema":{"type":"string","default":"shipments"}},{"description":"Only ports in this country, ISO 3166-1 alpha-2.","example":"TR","in":"query","name":"country","required":false,"schema":{"type":"string"}},{"description":"At most this many ports (1 to 500).","in":"query","name":"limit","required":false,"schema":{"type":"integer","format":"int32","default":100}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortCongestionList"}}},"description":"OK"}},"summary":"List port congestion","tags":["Ports & airports"]}},"/v1/ports/{locode}/congestion":{"get":{"description":"The port's daily congestion samples, oldest first. Navlo keeps 90 days. 404 for an unknown UN/LOCODE.","operationId":"portCongestionHistory","parameters":[{"description":"The port's UN/LOCODE.","example":"TRAMR","in":"path","name":"locode","required":true,"schema":{"type":"string"}},{"description":"Days back from now (1 to 90).","in":"query","name":"days","required":false,"schema":{"type":"integer","format":"int32","default":30}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortCongestionHistory"}}},"description":"OK"}},"summary":"Get a port's congestion history","tags":["Ports & airports"]}},"/v1/reports":{"post":{"description":"Builds the same Excel workbook Navlo AI produces when you ask it for a status report (up to 500 shipments), a cost analysis or a D&D risk report (up to 200 shipments) — straight from your data, with no AI credits used. Answers with a download link valid for 7 days. A filter the report type cannot apply is a 400; nothing is silently ignored.","operationId":"createReport","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateReportRequest"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Report"}}},"description":"Created"}},"summary":"Generate a report","tags":["Reports"]}},"/v1/shipments":{"get":{"description":"Your organization's shipments, a page at a time. Filter by status, mode, carrier, customer, tag, risk and date ranges, sort, and add per-item keys with `include`. Without any of these the list keeps its original order; for a stable order across pages pass `sort`. Sync changes incrementally with `updatedSince` and `include=lastChangedAt`.","operationId":"listShipments","parameters":[{"description":"0-based page number.","in":"query","name":"page","required":false,"schema":{"type":"integer","format":"int32","default":0}},{"description":"Page size, 1 to 100.","in":"query","name":"size","required":false,"schema":{"type":"integer","format":"int32","default":20}},{"description":"Statuses, comma-separated: discovering, resolving, active, tracking, completed, stopped. `active` also matches `tracking`, the status of a live air shipment.","example":"active","in":"query","name":"status","required":false,"schema":{"type":"string"}},{"description":"OCEAN or AIR.","example":"OCEAN","in":"query","name":"mode","required":false,"schema":{"type":"string"}},{"description":"Carrier code, as on the shipment (case-insensitive).","example":"MSC","in":"query","name":"carrier","required":false,"schema":{"type":"string"}},{"description":"Only shipments of this customer (Navlo's customer id).","in":"query","name":"customerId","required":false,"schema":{"type":"string"}},{"description":"Only shipments of the customer with this reference of yours.","example":"C-1042","in":"query","name":"customerRef","required":false,"schema":{"type":"string"}},{"description":"Tag names, comma-separated: shipments carrying any of them.","example":"Urgent,Q4","in":"query","name":"tag","required":false,"schema":{"type":"string"}},{"description":"Risk levels, comma-separated: LOW, MEDIUM, HIGH. Only current assessments count.","example":"HIGH","in":"query","name":"risk","required":false,"schema":{"type":"string"}},{"description":"ETA on or after this time (any container or waybill). Carrier times are port-local with a Z suffix and are compared as written. ISO-8601 timestamp or date.","example":"2026-11-01","in":"query","name":"etaFrom","required":false,"schema":{"type":"string"}},{"description":"ETA on or before this time; a date means the end of that day.","example":"2026-11-30","in":"query","name":"etaTo","required":false,"schema":{"type":"string"}},{"description":"Created in Navlo on or after this time (UTC).","example":"2026-10-01T00:00:00Z","in":"query","name":"createdFrom","required":false,"schema":{"type":"string"}},{"description":"Created in Navlo on or before this time (UTC); a date means the end of that day.","in":"query","name":"createdTo","required":false,"schema":{"type":"string"}},{"description":"Only shipments that changed (status, ETA, discovery outcome) at or after this time, UTC. Pass the newest lastChangedAt you have seen to sync incrementally.","example":"2026-10-22T08:00:00Z","in":"query","name":"updatedSince","required":false,"schema":{"type":"string"}},{"description":"createdAt, -createdAt (newest first), updatedAt, -updatedAt, eta, -eta (shipments without an ETA last). Without sort and filters the list keeps its original order.","example":"-updatedAt","in":"query","name":"sort","required":false,"schema":{"type":"string"}},{"description":"Extra keys on each item, comma-separated: customer, tags, risk, lastChangedAt.","example":"customer,risk","in":"query","name":"include","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiShipmentPageWithIncludes"}}},"description":"One page. Items carry the include keys only when requested."},"400":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"An unknown filter, sort or include value (the message lists the allowed ones)."}},"summary":"List shipments","tags":["Shipments"]},"post":{"description":"Starts tracking a container, B/L, booking or air waybill number. A number your organization already tracks is returned as it is and costs nothing; a new one costs 1 tracking credit. With `customer`, the shipment is filed under that customer — also when it already existed.","operationId":"startTracking","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiStartTrackingRequest"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiShipmentSummary"}}},"description":"The shipment, new or existing."},"400":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Blank identifier, missing mode, or a customer that cannot be used."},"402":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Not enough tracking credits."}},"summary":"Start tracking a shipment","tags":["Shipments"]}},"/v1/shipments/batch":{"post":{"description":"One call, one rate-limit hit. Items succeed or fail on their own: a failing item reports its error and the others still start. Each item takes the same fields as a single start, `customer` included.","operationId":"batchStartTracking","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiBatchStartRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiBatchResponse"}}},"description":"One result per submitted item, in order."},"400":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Empty batch, or more than 50 items."}},"summary":"Start tracking up to 50 shipments","tags":["Shipments"]}},"/v1/shipments/export":{"get":{"description":"The same file as the Export button on the Shipments page — same columns, same order, same formatting — for every shipment the filters select (no paging). Without filters: all of your organization's shipments. A status, mode, format, column or customerId the API does not know is a 400 that lists the allowed values; a tag name none of your tags carry matches no shipment, as on GET /v1/shipments.","operationId":"exportShipments","parameters":[{"description":"csv (default) or xlsx.","in":"query","name":"format","required":false,"schema":{"type":"string"}},{"description":"Comma-separated: discovering, resolving, active, completed, stopped.","in":"query","name":"status","required":false,"schema":{"type":"string"}},{"description":"OCEAN or AIR.","in":"query","name":"mode","required":false,"schema":{"type":"string"}},{"description":"Carrier code or name (partial match).","in":"query","name":"carrier","required":false,"schema":{"type":"string"}},{"description":"One of your customer ids, or `none` for shipments without a customer.","in":"query","name":"customerId","required":false,"schema":{"type":"string"}},{"description":"Comma-separated tag names (any case); a shipment matches when it carries any of them.","in":"query","name":"tag","required":false,"schema":{"type":"string"}},{"description":"ETA on or after (ISO date or timestamp).","in":"query","name":"etaFrom","required":false,"schema":{"type":"string"}},{"description":"ETA on or before (a date covers the whole day).","in":"query","name":"etaTo","required":false,"schema":{"type":"string"}},{"description":"Created on or after (ISO date or timestamp).","in":"query","name":"createdFrom","required":false,"schema":{"type":"string"}},{"description":"Created on or before (a date covers the whole day).","in":"query","name":"createdTo","required":false,"schema":{"type":"string"}},{"description":"Comma-separated column keys, as in the app's column picker. Omitted = every column.","in":"query","name":"columns","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"type":"string","format":"binary"}},"text/csv":{"schema":{"type":"string","format":"binary"}}},"description":"The file, as an attachment (navlo-trackings-YYYY-MM-DD.csv / .xlsx)."}},"summary":"Export shipments as CSV or Excel","tags":["Reports"]}},"/v1/shipments/{id}":{"delete":{"description":"Removes the shipment and its history. Credits already spent are not refunded — use /stop to just end updates.","operationId":"deleteTracking","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Deleted."},"404":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"No such shipment in your organization."}},"summary":"Delete a shipment","tags":["Shipments"]},"get":{"description":"The shipment with its containers or air waybills, merged timeline, ETA history and vessel position. Add Shipment intelligence with `include`; each requested key is always present, null when there is nothing.","operationId":"shipmentDetail","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}},{"description":"Comma-separated: risk, recommendations, navloEta, dnd, carbon, alerts, customer, tags, details — or all.","example":"risk,navloEta,dnd","in":"query","name":"include","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiShipmentDetailWithIncludes"}}},"description":"The shipment. Keys after `vessel` appear only when requested with `include`."},"400":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"An unknown include value (the message lists the allowed ones)."},"404":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"No such shipment in your organization."}},"summary":"Get a shipment","tags":["Shipment intelligence","Shipments"]},"patch":{"description":"Changes only the keys you send. Today that is `customer`: an object files the shipment under that customer (a new `ref` creates the customer), `null` clears it.","operationId":"updateShipment","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiShipmentPatchRequest"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiShipmentCustomerUpdate"}}},"description":"The shipment's customer after the change."},"400":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Not a JSON object, or a customer that cannot be used."},"404":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"No such shipment in your organization."}},"summary":"Update a shipment","tags":["Shipments"]}},"/v1/shipments/{id}/carrier":{"post":{"description":"When Navlo picked the wrong carrier: the carrier data is discarded and the shipment is discovered again with the carrier you name. Notes, tags, documents and the customer stay. Allowed once per shipment — a second change is a 409. An unknown carrier is a 400 and does not use up the change.","operationId":"changeShipmentCarrier","parameters":[{"description":"Shipment id.","in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangeCarrierRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangeCarrierResult"}}},"description":"OK"}},"summary":"Change the carrier","tags":["Shipment actions"]}},"/v1/shipments/{id}/complete":{"post":{"description":"Declares the shipment done: polling stops and it leaves the active views. No completion email is sent for your own action. Idempotent.","operationId":"completeShipment","parameters":[{"description":"Shipment id.","in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShipmentStatusResult"}}},"description":"OK"}},"summary":"Mark as completed","tags":["Shipment actions"]}},"/v1/shipments/{id}/documents":{"get":{"description":"Files attached on the shipment's Documents tab, newest first.","operationId":"listShipmentDocuments","parameters":[{"description":"Shipment id.","in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ShipmentDocument"}}}},"description":"OK"}},"summary":"List a shipment's documents","tags":["Shipment actions"]},"post":{"description":"multipart/form-data with the file in `file`. Same limits as the app: up to 10 MB; PDF, PNG, JPG, TIFF, BMP, CSV, XLS, XLSX, DOC or DOCX.","operationId":"uploadShipmentDocument","parameters":[{"description":"Shipment id.","in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"documentType":{"type":"string","description":"BILL_OF_LADING, INVOICE, PACKING_LIST, CUSTOMS_DECLARATION or OTHER (default)."},"file":{"type":"string","format":"binary","description":"The file."}},"required":["file"]}}}},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShipmentDocument"}}},"description":"Created"}},"summary":"Upload a document","tags":["Shipment actions"]}},"/v1/shipments/{id}/documents/{documentId}":{"delete":{"operationId":"deleteShipmentDocument","parameters":[{"description":"Shipment id.","in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}},{"description":"Document id.","in":"path","name":"documentId","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"No Content"}},"summary":"Delete a document","tags":["Shipment actions"]}},"/v1/shipments/{id}/documents/{documentId}/download":{"get":{"description":"A signed link to the file, valid for 15 minutes.","operationId":"downloadShipmentDocument","parameters":[{"description":"Shipment id.","in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}},{"description":"Document id.","in":"path","name":"documentId","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentDownload"}}},"description":"OK"}},"summary":"Get a download link","tags":["Shipment actions"]}},"/v1/shipments/{id}/mute":{"delete":{"description":"Same permission as muting. Idempotent.","operationId":"unmuteShipment","parameters":[{"description":"Shipment id.","in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShipmentMuteState"}}},"description":"OK"}},"summary":"Unmute notifications","tags":["Shipment actions"]},"put":{"description":"No Navlo email, push, in-app or digest notification about this shipment reaches anyone — your team, subscribers or share recipients. Webhooks keep firing. Allowed for organization admins and whoever added the shipment. Idempotent.","operationId":"muteShipment","parameters":[{"description":"Shipment id.","in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShipmentMuteState"}}},"description":"OK"}},"summary":"Mute notifications","tags":["Shipment actions"]}},"/v1/shipments/{id}/notes":{"get":{"description":"The notes your team wrote on the shipment, newest first.","operationId":"listShipmentNotes","parameters":[{"description":"Shipment id.","in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}},{"description":"0-based page number.","in":"query","name":"page","required":false,"schema":{"type":"integer","format":"int32","default":0}},{"description":"Page size, 1–100.","in":"query","name":"size","required":false,"schema":{"type":"integer","format":"int32","default":20}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShipmentNotePage"}}},"description":"OK"}},"summary":"List a shipment's notes","tags":["Shipment actions"]},"post":{"description":"Written as the API key's creator; teammates mentioned with the app's markup are notified as in the app.","operationId":"addShipmentNote","parameters":[{"description":"Shipment id.","in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShipmentNoteRequest"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShipmentNote"}}},"description":"Created"}},"summary":"Add a note","tags":["Shipment actions"]}},"/v1/shipments/{id}/notes/{noteId}":{"delete":{"description":"Only the note's author can delete it (403 otherwise), as in the app.","operationId":"deleteShipmentNote","parameters":[{"description":"Shipment id.","in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}},{"description":"Note id.","in":"path","name":"noteId","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"No Content"}},"summary":"Delete a note","tags":["Shipment actions"]},"put":{"description":"Only the note's author can edit it (403 otherwise), as in the app.","operationId":"updateShipmentNote","parameters":[{"description":"Shipment id.","in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}},{"description":"Note id.","in":"path","name":"noteId","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShipmentNoteRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShipmentNote"}}},"description":"OK"}},"summary":"Edit a note","tags":["Shipment actions"]}},"/v1/shipments/{id}/resume":{"post":{"description":"Restarts refreshing a stopped shipment. Idempotent.","operationId":"resumeTracking","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiPollingState"}}},"description":"OK"},"404":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"No such shipment in your organization."}},"summary":"Resume tracking","tags":["Shipments"]}},"/v1/shipments/{id}/route":{"get":{"description":"The map geometry Navlo draws for the shipment, as GeoJSON: sea legs follow shipping lanes, inland and air legs are straight. Coordinates are [longitude, latitude].","operationId":"shipmentRoute","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiRouteResponse"}}},"description":"Ports in order, one GeoJSON line per leg, and the vessel position when known."},"404":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"No such shipment, or nothing on its route is located yet."}},"summary":"Get a shipment's route","tags":["Shipments"]}},"/v1/shipments/{id}/share-link":{"delete":{"description":"The old link stops working. Idempotent.","operationId":"revokeShipmentShareLink","parameters":[{"description":"Shipment id.","in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"No Content"}},"summary":"Revoke the public share link","tags":["Shipment actions"]},"post":{"description":"A read-only page anyone with the link can open — carrier facts only, no notes, documents or customer. Idempotent: an existing link is returned unchanged.","operationId":"createShipmentShareLink","parameters":[{"description":"Shipment id.","in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShareLink"}}},"description":"OK"}},"summary":"Create the public share link","tags":["Shipment actions"]}},"/v1/shipments/{id}/stop":{"post":{"description":"Stops refreshing the shipment. Its history and last status stay, and /resume restarts it. Idempotent.","operationId":"stopTracking","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiPollingState"}}},"description":"OK"},"404":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"No such shipment in your organization."}},"summary":"Stop tracking","tags":["Shipments"]}},"/v1/shipments/{id}/subscribers":{"get":{"description":"People outside Navlo who get an email when this shipment's status changes.","operationId":"listShipmentSubscribers","parameters":[{"description":"Shipment id.","in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ShipmentSubscriber"}}}},"description":"OK"}},"summary":"List email subscribers","tags":["Shipment actions"]},"post":{"description":"Emails the shipment's share link to each address (creating the link if there is none) and subscribes them to status-change emails until they unsubscribe — the app's Share by email with status updates on. Adding an address again updates its event selection. Your organization can email at most 500 recipients per 24 hours, app and API together; a request that would go over answers `429` and emails nobody.","operationId":"addShipmentSubscribers","parameters":[{"description":"Shipment id.","in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddSubscribersRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddSubscribersResult"}}},"description":"OK"}},"summary":"Share by email and subscribe","tags":["Shipment actions"]}},"/v1/shipments/{id}/subscribers/{subscriberId}":{"delete":{"description":"Same effect as the recipient's own unsubscribe link. Idempotent.","operationId":"removeShipmentSubscriber","parameters":[{"description":"Shipment id.","in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}},{"description":"Subscriber id.","in":"path","name":"subscriberId","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"No Content"}},"summary":"Unsubscribe an address","tags":["Shipment actions"]}},"/v1/shipments/{id}/tags":{"post":{"description":"Send `tagId`, or `name` — a name is matched regardless of case and the tag is created when it does not exist. Adding a tag the shipment already has changes nothing. Answers with the shipment's tags.","operationId":"addShipmentTag","parameters":[{"description":"Shipment id.","in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssignTagRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Tag"}}}},"description":"OK"}},"summary":"Tag a shipment","tags":["Tags"]}},"/v1/shipments/{id}/tags/{tagId}":{"delete":{"description":"Idempotent. The tag itself stays in your organization. Answers with the shipment's remaining tags.","operationId":"removeShipmentTag","parameters":[{"description":"Shipment id.","in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}},{"description":"Tag id.","in":"path","name":"tagId","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Tag"}}}},"description":"OK"}},"summary":"Remove a tag from a shipment","tags":["Tags"]}},"/v1/tags":{"get":{"description":"Every tag in your organization, by name.","operationId":"listTags","responses":{"200":{"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Tag"}}}},"description":"OK"}},"summary":"List tags","tags":["Tags"]},"post":{"description":"A name already used in your organization (any case) is a 409.","operationId":"createTag","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTagRequest"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Tag"}}},"description":"Created"}},"summary":"Create a tag","tags":["Tags"]}},"/v1/tags/{tagId}":{"delete":{"description":"Removes the tag from every shipment. Organization admins only (403 otherwise), as in the app.","operationId":"deleteTag","parameters":[{"description":"Tag id.","in":"path","name":"tagId","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"No Content"}},"summary":"Delete a tag","tags":["Tags"]}},"/v1/usage":{"get":{"description":"Credits charged and refunded in a period, attributed to the CURRENT customer of each shipment, vessel follow or Navlo AI conversation. Days are UTC; `from` is inclusive, `to` exclusive; the default is the current calendar month and a report covers at most 366 days. format=csv returns one line per ledger row instead (charges positive, refunds negative).","operationId":"getUsage","parameters":[{"description":"First day, inclusive (YYYY-MM-DD, UTC). Default: the first day of the current month.","example":"2026-10-01","in":"query","name":"from","required":false,"schema":{"type":"string"}},{"description":"Day after the last day, exclusive (YYYY-MM-DD, UTC). Default: one month after `from`.","example":"2026-11-01","in":"query","name":"to","required":false,"schema":{"type":"string"}},{"description":"customer (default), shipment, day or none.","example":"customer","in":"query","name":"groupBy","required":false,"schema":{"type":"string"}},{"description":"Only this customer's usage (Navlo id).","in":"query","name":"customerId","required":false,"schema":{"type":"string"}},{"description":"Only this customer's usage (your reference).","example":"C-1042","in":"query","name":"customerRef","required":false,"schema":{"type":"string"}},{"description":"json (default) or csv.","example":"json","in":"query","name":"format","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageReport"}},"text/csv":{"schema":{"type":"string"}}},"description":"The report (JSON), or the ledger rows as CSV with format=csv."}},"summary":"Usage report","tags":["Usage & credits"]}},"/v1/vessels/follows":{"get":{"description":"Active follows first, then completed ones; newest first within each.","operationId":"listVesselFollows","parameters":[{"description":"Page number, 0-based.","in":"query","name":"page","required":false,"schema":{"type":"integer","format":"int32","default":0}},{"description":"Page size, at most 100.","in":"query","name":"size","required":false,"schema":{"type":"integer","format":"int32","default":20}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VesselFollowPage"}}},"description":"OK"}},"summary":"List followed vessels","tags":["Vessels"]},"post":{"description":"Starts tracking the vessel's voyage and charges it (see the quote). Following a vessel you already track returns that follow and charges nothing; following one whose voyage is completed starts its next voyage. 402 when your credits do not cover the voyage, 409 when your organization already follows 50 vessels.","operationId":"followVessel","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VesselFollowRequest"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VesselFollow"}}},"description":"Created"}},"summary":"Follow a vessel","tags":["Vessels"]}},"/v1/vessels/follows/quote":{"post":{"description":"What following this vessel will cost, before you follow it. Nothing is written or charged.","operationId":"quoteVesselFollow","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VesselFollowRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VesselTrackingQuote"}}},"description":"OK"}},"summary":"Quote a follow","tags":["Vessels"]}},"/v1/vessels/follows/{id}":{"delete":{"description":"Removes the vessel from your list. Credits already spent are not refunded.","operationId":"unfollowVessel","parameters":[{"description":"Follow id.","in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"No Content"}},"summary":"Stop following a vessel","tags":["Vessels"]},"get":{"description":"The follow with its position, voyage, ETA history, port calls and events.","operationId":"getVesselFollow","parameters":[{"description":"Follow id.","in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VesselFollowDetail"}}},"description":"OK"}},"summary":"Get a followed vessel","tags":["Vessels"]}},"/v1/vessels/follows/{id}/complete":{"post":{"description":"Marks the voyage completed: it stays in the list as completed. Idempotent.","operationId":"completeVesselFollow","parameters":[{"description":"Follow id.","in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VesselFollow"}}},"description":"OK"}},"summary":"Complete a voyage","tags":["Vessels"]}},"/v1/vessels/search":{"get":{"description":"Searches Navlo's vessel catalogue by name (3+ characters), IMO (7 digits) or MMSI (9 digits). Free. A vessel the catalogue does not know can still be followed by its IMO or MMSI.","operationId":"searchVessels","parameters":[{"description":"Vessel name, IMO or MMSI.","example":"MSC ANNA","in":"query","name":"q","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VesselSearch"}}},"description":"OK"}},"summary":"Search vessels","tags":["Vessels"]}},"/v1/webhooks":{"get":{"description":"Every endpoint of your organization, including ones Navlo switched off.","operationId":"listWebhooks","responses":{"200":{"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"}}}},"description":"OK"}},"summary":"List webhooks","tags":["Webhooks"]},"post":{"description":"Organization admins only. The URL must be https; at most 10 endpoints per organization. The response carries the signing secret — the only time it is shown.","operationId":"createWebhook","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWebhookRequest"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookCreated"}}},"description":"Created; store the secret now."}},"summary":"Create a webhook","tags":["Webhooks"]}},"/v1/webhooks/topics":{"get":{"description":"The events an endpoint can subscribe to.","operationId":"listWebhookTopics","responses":{"200":{"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/WebhookTopicInfo"}}}},"description":"OK"}},"summary":"List topics","tags":["Webhooks"]}},"/v1/webhooks/{id}":{"delete":{"description":"Organization admins only. Deliveries stop at once.","operationId":"deleteWebhook","parameters":[{"description":"Webhook id.","in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Deleted."}},"summary":"Delete a webhook","tags":["Webhooks"]},"get":{"operationId":"getWebhook","parameters":[{"description":"Webhook id.","in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Webhook"}}},"description":"OK"}},"summary":"Get a webhook","tags":["Webhooks"]},"patch":{"description":"Organization admins only. Only the keys you send change. Re-activating an endpoint clears its failure count.","operationId":"updateWebhook","parameters":[{"description":"Webhook id.","in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateWebhookRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Webhook"}}},"description":"OK"}},"summary":"Update a webhook","tags":["Webhooks"]}},"/v1/webhooks/{id}/deliveries":{"get":{"description":"What Navlo sent this endpoint and how it answered, newest first. Kept 30 days.","operationId":"listWebhookDeliveries","parameters":[{"description":"Webhook id.","in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}},{"description":"0-based page.","in":"query","name":"page","required":false,"schema":{"type":"integer","format":"int32","default":0}},{"description":"Page size, 1 to 100.","in":"query","name":"size","required":false,"schema":{"type":"integer","format":"int32","default":20}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDeliveryPage"}}},"description":"OK"}},"summary":"List deliveries","tags":["Webhooks"]}},"/v1/webhooks/{id}/rotate-secret":{"post":{"description":"Organization admins only. Returns the new secret once; every delivery from now on, retries included, is signed with it.","operationId":"rotateWebhookSecret","parameters":[{"description":"Webhook id.","in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSecret"}}},"description":"OK"}},"summary":"Rotate the signing secret","tags":["Webhooks"]}},"/v1/webhooks/{id}/test":{"post":{"description":"Organization admins only. Queues a sample event of the topic (default shipment.status_changed) to this endpoint, signed and retried like a real one, with \"test\": true and a sample shipment. Arrives within a minute.","operationId":"sendWebhookTest","parameters":[{"description":"Webhook id.","in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookTestRequest"}}}},"responses":{"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookTestEvent"}}},"description":"Queued."}},"summary":"Send a test event","tags":["Webhooks"]}}},"components":{"schemas":{"AddSubscribersRequest":{"type":"object","properties":{"emails":{"type":["array","null"],"description":"Up to 10 addresses. Each gets the share email now and status-change emails until they unsubscribe.","example":["ops@acme-trading.example"],"items":{"type":"string"}},"events":{"type":["array","null"],"description":"Limit the status-change emails to these milestone groups: PRE_SHIPMENT, ORIGIN, TRANSIT, DESTINATION, COMPLETED. Omitted or empty = every status change.","example":["TRANSIT","DESTINATION"],"items":{"type":"string"}},"note":{"type":["string","null"],"description":"Personal message printed in the share email (max 2,000 characters).","example":"Here is the live status of your order."}},"required":["emails"]},"AddSubscribersResult":{"type":"object","properties":{"failed":{"type":"array","description":"Addresses the email could not be delivered to; they stay subscribed.","items":{"type":"string"}},"sent":{"type":"integer","format":"int32","description":"Emails sent."}}},"AiAskRequest":{"type":"object","description":"One question. Starts a new conversation, listed in the app's Navlo AI for the key's creator.","properties":{"customer":{"description":"Assign the conversation, and the AI credits it uses, to one of your customers.","oneOf":[{"$ref":"#/components/schemas/CustomerInput"},{"type":"null"}]},"question":{"type":"string","description":"Your question, in any language.","example":"Which of my shipments to Rotterdam are running late?","maxLength":10000,"minLength":0},"shipmentId":{"type":["string","null"],"format":"uuid","description":"Ask about this shipment (a Navlo shipment id). Navlo AI is told which shipment you mean."},"stream":{"type":["boolean","null"],"default":true,"description":"true or omitted: Server-Sent Events as the answer is written. false: one JSON answer when it is ready."}},"required":["question"]},"AiChart":{"type":"object","description":"A chart from the answer, ready for any charting library.","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AiChartPoint"}},"title":{"type":["string","null"]},"type":{"type":"string","enum":["bar","line","pie"]},"xlabel":{"type":"string"},"ylabel":{"type":"string"}}},"AiChartPoint":{"type":"object","properties":{"label":{"type":"string","example":"Maersk"},"value":{"type":"number","format":"double","example":4200}}},"AiConversation":{"type":"object","properties":{"createdAt":{"type":"string","format":"date-time"},"customer":{"description":"The customer the conversation is assigned to; null when none.","oneOf":[{"$ref":"#/components/schemas/CustomerRef"},{"type":"null"}]},"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"updatedAt":{"type":"string","format":"date-time"}}},"AiConversationCreateRequest":{"type":"object","properties":{"customer":{"description":"Assign the conversation, and the AI credits it uses, to one of your customers.","oneOf":[{"$ref":"#/components/schemas/CustomerInput"},{"type":"null"}]},"title":{"type":["string","null"],"description":"Omit it and Navlo AI titles the conversation from its first exchange.","example":"Rotterdam delays","maxLength":255,"minLength":0}}},"AiConversationDetail":{"type":"object","properties":{"createdAt":{"type":"string","format":"date-time"},"customer":{"oneOf":[{"$ref":"#/components/schemas/CustomerRef"},{"type":"null"}]},"id":{"type":"string","format":"uuid"},"messages":{"type":"array","description":"Oldest first.","items":{"$ref":"#/components/schemas/AiMessage"}},"title":{"type":"string"},"updatedAt":{"type":"string","format":"date-time"}}},"AiConversationPage":{"type":"object","properties":{"conversations":{"type":"array","items":{"$ref":"#/components/schemas/AiConversation"}},"page":{"type":"integer","format":"int32"},"size":{"type":"integer","format":"int32"},"totalElements":{"type":"integer","format":"int64"},"totalPages":{"type":"integer","format":"int32"}}},"AiError":{"type":"object","description":"Error body of a `stream: false` call that produced no answer.","properties":{"code":{"type":"string","enum":["insufficient_credits","rejected","busy","timeout","internal"]},"error":{"type":"string"},"message":{"type":"string"}}},"AiFile":{"type":"object","description":"A document Navlo AI generated (Excel report, invoice, packing list…).","properties":{"expiresAt":{"type":["string","null"],"format":"date-time","description":"When the link stops working (7 days after it was made)."},"name":{"type":"string","example":"shipment-status-report-20261022.xlsx"},"url":{"type":"string","description":"Download link. No API key needed: the signed link is the credential, so share it with care.","example":"https://api.navlo.io/api/ai/d/AbC123.xYz789"}}},"AiMessage":{"type":"object","properties":{"charts":{"type":"array","items":{"$ref":"#/components/schemas/AiChart"}},"content":{"type":"string","description":"Markdown. Assistant answers come without ```chart blocks; those are in `charts`."},"createdAt":{"type":"string","format":"date-time"},"files":{"type":"array","items":{"$ref":"#/components/schemas/AiFile"}},"id":{"type":"string","format":"uuid"},"role":{"type":"string","enum":["user","assistant"]}}},"AiMessageRequest":{"type":"object","description":"A follow-up question in an existing conversation.","properties":{"content":{"type":"string","description":"Your question, in any language.","example":"And which of those are with MSC?","maxLength":10000,"minLength":0},"stream":{"type":["boolean","null"],"default":true,"description":"true or omitted: Server-Sent Events as the answer is written. false: one JSON answer when it is ready."}},"required":["content"]},"AiResult":{"type":"object","description":"The finished answer: the `result` event of a stream, or the whole body of a `stream: false` call.","properties":{"answer":{"type":"string","description":"Markdown, without ```chart blocks. Links to Navlo pages are absolute app.navlo.io links."},"charts":{"type":"array","items":{"$ref":"#/components/schemas/AiChart"}},"conversationId":{"type":"string","format":"uuid"},"creditsUsed":{"type":"number","description":"AI credits this answer used.","example":0.2},"files":{"type":"array","description":"Documents this answer generated.","items":{"$ref":"#/components/schemas/AiFile"}},"messageId":{"type":["string","null"],"format":"uuid","description":"The stored answer's id (the assistant message in the conversation)."},"shipments":{"type":"array","description":"Your shipments the answer is about, in the order it mentions them.","items":{"$ref":"#/components/schemas/AiShipmentRef"}}}},"AiShipmentRef":{"type":"object","description":"A shipment the answer is about.","properties":{"id":{"type":"string","format":"uuid"},"identifier":{"type":"string","example":"MSCU1234567"}}},"AirShipmentPartFlightResponse":{"type":"object","properties":{"flightDate":{"type":["string","null"],"format":"date"},"flightNumber":{"type":"string"}}},"AirShipmentPartResponse":{"type":"object","properties":{"flights":{"type":"array","items":{"$ref":"#/components/schemas/AirShipmentPartFlightResponse"}},"piecesCount":{"type":["integer","null"],"format":"int32"},"piecesVolume":{"type":["number","null"]},"piecesVolumeUnit":{"type":["string","null"]},"piecesWeight":{"type":["number","null"]},"piecesWeightUnit":{"type":["string","null"]}}},"AirportDelay":{"type":"object","properties":{"averageDelayMinutes":{"type":["integer","null"],"format":"int32","description":"Average delay of departures and arrivals, minutes.","example":35},"delayed":{"type":"boolean","description":"Flights are delayed on average, or a ground stop is in force."},"groundStop":{"type":"boolean"},"groundStopReason":{"type":["string","null"],"description":"The ground stop's reason, when one is given."},"iataCode":{"type":"string","description":"IATA airport code.","example":"IST"},"latitude":{"type":["number","null"],"format":"double"},"longitude":{"type":["number","null"],"format":"double"},"name":{"type":["string","null"],"example":"Istanbul Airport"},"sampledAt":{"type":["string","null"],"format":"date-time","description":"When the sample was taken (UTC)."}}},"AirportDelayList":{"type":"object","properties":{"airports":{"type":"array","description":"Ground stops first, then the longest average delay.","items":{"$ref":"#/components/schemas/AirportDelay"}},"available":{"type":"boolean","description":"False when Navlo's airport data could not be read just now; `airports` is then empty. Retry later."}}},"ApiAirShipment":{"type":"object","properties":{"ata":{"type":["string","null"],"format":"date-time"},"atd":{"type":["string","null"],"format":"date-time"},"awbNumber":{"type":["string","null"],"description":"Dashed IATA form; the carrier's own number for non-AWB tracking.","example":"871-12345675"},"chargeableWeight":{"type":["number","null"]},"currentAirport":{"oneOf":[{"$ref":"#/components/schemas/ApiPort"},{"type":"null"}]},"destination":{"$ref":"#/components/schemas/ApiPort"},"eta":{"type":["string","null"],"format":"date-time"},"etd":{"type":["string","null"],"format":"date-time"},"flights":{"type":"array","description":"Booked and flown legs in order; empty until the carrier publishes the routing.","items":{"$ref":"#/components/schemas/ApiFlight"}},"origin":{"$ref":"#/components/schemas/ApiPort"},"pieces":{"type":["integer","null"],"format":"int32"},"status":{"type":["string","null"],"description":"Current milestone code for the waybill.","example":"IN_TRANSIT"},"volume":{"type":["number","null"]},"volumeUnit":{"type":["string","null"]},"weight":{"type":["number","null"]},"weightUnit":{"type":["string","null"],"description":"KILOGRAM or POUND when the carrier reports one; null reads as kilograms.","example":"KILOGRAM"}}},"ApiBatchItemResult":{"type":"object","properties":{"error":{"type":["string","null"],"description":"Why this item failed; null unless status is error."},"id":{"type":["string","null"],"format":"uuid"},"identifier":{"type":"string"},"status":{"type":"string","enum":["created","existing","error"],"example":"created"}}},"ApiBatchResponse":{"type":"object","properties":{"created":{"type":"integer","format":"int32"},"errors":{"type":"integer","format":"int32"},"existing":{"type":"integer","format":"int32"},"results":{"type":"array","items":{"$ref":"#/components/schemas/ApiBatchItemResult"}},"submitted":{"type":"integer","format":"int32"}}},"ApiBatchStartRequest":{"type":"object","description":"Start tracking up to 50 shipments in one call.","properties":{"shipments":{"type":"array","items":{"$ref":"#/components/schemas/ApiStartTrackingRequest"}}}},"ApiContainer":{"type":"object","properties":{"ata":{"type":["string","null"],"format":"date-time","description":"Actual arrival at the destination port, port-local time written with a Z suffix."},"atd":{"type":["string","null"],"format":"date-time","description":"Actual departure, port-local time written with a Z suffix."},"containerNumber":{"type":"string","example":"MEDU1234562"},"containerType":{"type":["string","null"],"example":"40' High Cube"},"currentVessel":{"type":["string","null"],"example":"MSC MARTINA"},"destination":{"$ref":"#/components/schemas/ApiPort"},"eta":{"type":["string","null"],"format":"date-time","description":"Estimated arrival at the destination port, port-local time written with a Z suffix."},"etd":{"type":["string","null"],"format":"date-time","description":"Estimated departure, port-local time written with a Z suffix."},"origin":{"$ref":"#/components/schemas/ApiPort"},"status":{"type":["string","null"],"description":"Current status code of the box, e.g. IN_TRANSIT, DISCHARGED, DELIVERED.","example":"IN_TRANSIT"}}},"ApiEtaRevision":{"type":"object","properties":{"awbNumber":{"type":["string","null"]},"containerNumber":{"type":["string","null"]},"deltaHours":{"type":"integer","format":"int64","description":"Signed hours; positive means later than before (a delay).","example":96},"field":{"type":"string","enum":["ETA","ETD","ATA","ATD"],"example":"ETA"},"newValue":{"type":"string","format":"date-time"},"previousValue":{"type":"string","format":"date-time"},"recordedAt":{"type":"string","format":"date-time","description":"When Navlo observed the change (UTC)."}}},"ApiEvent":{"type":"object","properties":{"flight":{"type":["string","null"],"description":"Air only: the flight the event refers to."},"location":{"type":["string","null"]},"locationCode":{"type":["string","null"]},"pieces":{"type":["integer","null"],"format":"int32","description":"Air only: pieces covered by this event."},"status":{"type":["string","null"],"example":"Loaded on vessel"},"timestamp":{"type":["string","null"],"format":"date-time","description":"When it happened (or is expected), port-local time written with a Z suffix."},"type":{"type":["string","null"],"description":"ACTUAL (it happened) or EXPECTED (carrier projection); null when the carrier doesn't say.","example":"ACTUAL"},"vessel":{"type":["string","null"]},"voyage":{"type":["string","null"]},"weight":{"type":["number","null"],"description":"Air only: weight covered by this event, in the waybill's weight unit."}}},"ApiFlight":{"type":"object","properties":{"ata":{"type":["string","null"],"format":"date-time"},"atd":{"type":["string","null"],"format":"date-time"},"eta":{"type":["string","null"],"format":"date-time"},"etd":{"type":["string","null"],"format":"date-time"},"flightNumber":{"type":"string","example":"TK6371"},"from":{"$ref":"#/components/schemas/ApiPort"},"status":{"type":["string","null"],"description":"The carrier's booking status for the leg, when reported.","example":"BOOKED"},"to":{"$ref":"#/components/schemas/ApiPort"}}},"ApiPollingState":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"polling":{"type":"string","enum":["stopped","active"],"example":"stopped"}}},"ApiPort":{"type":"object","properties":{"code":{"type":["string","null"],"description":"UN/LOCODE for a port, IATA code for an airport.","example":"CNSHA"},"name":{"type":["string","null"],"example":"Shanghai"}}},"ApiRoutePort":{"type":"object","properties":{"code":{"type":["string","null"]},"latitude":{"type":"number","format":"double"},"longitude":{"type":"number","format":"double"},"name":{"type":["string","null"]}}},"ApiRouteResponse":{"type":"object","properties":{"geojson":{"type":"object","additionalProperties":{},"description":"GeoJSON FeatureCollection; one LineString Feature per leg with properties.kind SEA, LAND or AIR. Coordinates are [longitude, latitude]."},"ports":{"type":"array","description":"Ports (or airports) the shipment calls at, in order: origin, transshipments, destination.","items":{"$ref":"#/components/schemas/ApiRoutePort"}},"shipmentId":{"type":"string","format":"uuid"},"vessel":{"oneOf":[{"$ref":"#/components/schemas/ApiVesselPosition"},{"type":"null"}]}}},"ApiShipmentAirWaybillDetails":{"type":"object","properties":{"awbNumber":{"type":["string","null"],"description":"Dashed IATA form.","example":"871-12345675"}}},"ApiShipmentAlert":{"type":"object","description":"A disruption near the shipment's route — the alert strip on the shipment page.","properties":{"description":{"type":["string","null"],"description":"One sentence with the severity and date.","example":"High-severity earthquake reported near this shipment's route on 22 Oct 2026."},"endsAt":{"type":["string","null"],"format":"date-time","description":"When the alert ends; null when not known."},"location":{"oneOf":[{"$ref":"#/components/schemas/ApiShipmentAlertLocation"},{"type":"null"}]},"severity":{"type":"string","example":"HIGH"},"startsAt":{"type":["string","null"],"format":"date-time","description":"When the alert was published (UTC)."},"title":{"type":"string","description":"A short headline from the type.","example":"Earthquake near the route"},"type":{"type":"string","description":"What kind of disruption: TROPICAL_CYCLONE, EARTHQUAKE, FLOOD, TSUNAMI, VOLCANO, DROUGHT, WILDFIRE, SECURITY (piracy, attacks and other maritime security incidents) or OTHER. Treat unknown values as OTHER.","example":"EARTHQUAKE"}}},"ApiShipmentAlertLocation":{"type":"object","properties":{"code":{"type":["string","null"]},"latitude":{"type":["number","null"],"format":"double"},"longitude":{"type":["number","null"],"format":"double"},"name":{"type":["string","null"]}}},"ApiShipmentCarbon":{"type":"object","description":"CO2e emissions of the shipment's journey.","properties":{"co2eKg":{"type":["number","null"],"description":"Shipment total in kg: the sum of the units that have a figure; null when none has."},"source":{"type":["string","null"],"description":"GLEC (Navlo's estimate) or CARRIER (the carrier's own figure) when every unit with a figure agrees; null otherwise."},"units":{"type":"array","items":{"$ref":"#/components/schemas/ApiShipmentCarbonUnit"}}}},"ApiShipmentCarbonUnit":{"type":"object","description":"CO2e of one container (ocean) or air waybill (air).","properties":{"awbNumber":{"type":["string","null"],"description":"Air: the waybill, dashed IATA form. Null for ocean."},"co2eKg":{"type":["number","null"]},"containerNumber":{"type":["string","null"],"description":"Ocean: the container. Null for air."},"source":{"type":["string","null"],"description":"GLEC or CARRIER."}}},"ApiShipmentContainerDetails":{"type":"object","properties":{"aboardVessel":{"type":"boolean","description":"True when the box is verifiably on its vessel right now."},"containerNumber":{"type":"string"},"currentLocation":{"type":["string","null"],"description":"Where the carrier last placed the box."},"currentLocationCode":{"type":["string","null"]},"destinationCountryCode":{"type":["string","null"],"description":"ISO 3166-1 alpha-2.","example":"NL"},"destinationTerminal":{"type":["string","null"]},"nextPlannedVessel":{"description":"The vessel the box is booked onto next, while it waits for it.","oneOf":[{"$ref":"#/components/schemas/ApiShipmentNextPlannedVessel"},{"type":"null"}]},"originCountryCode":{"type":["string","null"],"description":"ISO 3166-1 alpha-2.","example":"CN"},"originTerminal":{"type":["string","null"]},"transshipmentPorts":{"type":"array","description":"Ports where the box changes vessel, in journey order.","items":{"$ref":"#/components/schemas/ApiPort"}},"vesselImo":{"type":["string","null"],"description":"IMO number of the current vessel, when the carrier gives one.","example":"9839131"},"voyage":{"type":["string","null"],"description":"Current voyage number."}}},"ApiShipmentCustomerUpdate":{"type":"object","properties":{"customer":{"description":"The shipment's customer after the change; null when it has none.","oneOf":[{"$ref":"#/components/schemas/CustomerRef"},{"type":"null"}]},"id":{"type":"string","format":"uuid"}}},"ApiShipmentDetailWithIncludes":{"type":"object","description":"A shipment with its timeline. The keys after `vessel` appear only when requested with `include` (Shipment intelligence); once requested they are always present, null when there is nothing.","properties":{"airShipments":{"type":"array","description":"Air: one entry per air waybill. Empty for ocean.","items":{"$ref":"#/components/schemas/ApiAirShipment"}},"alerts":{"type":["array","null"],"description":"Present only when requested with include=alerts. Empty when there are none or alerts are temporarily unavailable.","items":{"$ref":"#/components/schemas/ApiShipmentAlert"}},"carbon":{"description":"Present only when requested with include=carbon.","oneOf":[{"$ref":"#/components/schemas/ApiShipmentCarbon"},{"type":"null"}]},"carrier":{"type":["string","null"]},"containers":{"type":"array","description":"Ocean: one entry per container. Empty for air.","items":{"$ref":"#/components/schemas/ApiContainer"}},"customer":{"description":"Present only when requested with include=customer. Null when the shipment has no customer.","oneOf":[{"$ref":"#/components/schemas/CustomerRef"},{"type":"null"}]},"details":{"description":"Present only when requested with include=details.","oneOf":[{"$ref":"#/components/schemas/ApiShipmentDetails"},{"type":"null"}]},"dnd":{"description":"Present only when requested with include=dnd.","oneOf":[{"$ref":"#/components/schemas/ApiShipmentDnd"},{"type":"null"}]},"etaHistory":{"type":"array","description":"Every recorded ETA/ETD/ATA/ATD change, newest first (at most 100).","items":{"$ref":"#/components/schemas/ApiEtaRevision"}},"events":{"type":"array","description":"Merged timeline across containers or waybills, oldest first.","items":{"$ref":"#/components/schemas/ApiEvent"}},"id":{"type":"string","format":"uuid"},"identifier":{"type":"string"},"mode":{"type":["string","null"],"enum":["OCEAN","AIR"]},"navloEta":{"type":["array","null"],"description":"Present only when requested with include=navloEta. One entry per container; empty for air.","items":{"$ref":"#/components/schemas/ApiShipmentNavloEta"}},"recommendations":{"type":["array","null"],"description":"Present only when requested with include=recommendations. Empty when there are none.","items":{"$ref":"#/components/schemas/ApiShipmentRecommendation"}},"risk":{"description":"Present only when requested with include=risk.","oneOf":[{"$ref":"#/components/schemas/ApiShipmentRisk"},{"type":"null"}]},"status":{"type":["string","null"],"description":"discovering, resolving, active (ocean) or tracking (air) while it runs, completed, stopped.","enum":["discovering","resolving","active","tracking","completed","stopped"]},"tags":{"type":["array","null"],"description":"Present only when requested with include=tags.","items":{"$ref":"#/components/schemas/ApiShipmentTag"}},"vessel":{"oneOf":[{"$ref":"#/components/schemas/ApiVesselPosition"},{"type":"null"}]}}},"ApiShipmentDetails":{"type":"object","description":"Operational details of the shipment page that the default detail leaves out.","properties":{"airShipments":{"type":"array","description":"Air: one entry per air waybill. Empty for ocean.","items":{"$ref":"#/components/schemas/ApiShipmentAirWaybillDetails"}},"containers":{"type":"array","description":"Ocean: one entry per container. Empty for air.","items":{"$ref":"#/components/schemas/ApiShipmentContainerDetails"}},"lastCarrierEventAt":{"type":["string","null"],"format":"date-time","description":"The newest event the carrier reported as happened."},"notificationsMuted":{"type":"boolean","description":"True when notifications for this shipment are muted. Webhooks still fire."},"pollingStoppedAt":{"type":["string","null"],"format":"date-time","description":"When tracking was stopped (POST /v1/shipments/{id}/stop); null while it runs."},"relatedIdentifiers":{"type":"array","description":"Sibling numbers from the same house B/L or house air waybill. Shown only; never tracked or charged.","items":{"type":"string"}}}},"ApiShipmentDnd":{"type":"object","description":"Free time and demurrage & detention (D&D) clock — the shipment page's D&D card.","properties":{"available":{"type":"boolean","description":"False when Navlo has no free-time information; every other field is then null."},"carrierFreeTimeBasis":{"type":["string","null"],"description":"The carrier's counting basis, as the carrier writes it.","example":"Calendar Days"},"carrierFreeTimeDays":{"type":["integer","null"],"format":"int32","description":"Free time the carrier grants, in days."},"demurrageDaysSoFar":{"type":["integer","null"],"format":"int32","description":"Calendar days past free time (day 1 = the first day after it ended); null while within free time."},"demurrageStoppedAt":{"type":["string","null"],"format":"date-time","description":"When the clock stopped for good (empty return or completion); null while it runs."},"freeTimeDaysLeft":{"type":["integer","null"],"format":"int32","description":"Calendar days of free time left while the clock runs; null before it starts or once free time is over."},"freeTimeEndsAt":{"type":["string","null"],"format":"date-time","description":"When free time ends."},"freeTimeStartAt":{"type":["string","null"],"format":"date-time","description":"Free-time start: discharge or arrival (estimated until it happens)."},"freeTimeStarted":{"type":"boolean","description":"True once the clock is actually running (the cargo has arrived); before that the window is a forecast."},"source":{"type":["string","null"],"description":"Where the free time comes from: CARRIER, MANUAL (your entry) or SYSTEM (your accepted tariff)."}}},"ApiShipmentNavloEta":{"type":"object","description":"Navlo's own arrival prediction for one container.","properties":{"carrierEta":{"type":["string","null"],"format":"date-time","description":"The carrier's ETA for the same box, for comparison."},"computedAt":{"type":["string","null"],"format":"date-time","description":"When the prediction was made (UTC)."},"confidence":{"type":["string","null"],"description":"HIGH, MEDIUM or LOW.","example":"MEDIUM"},"containerNumber":{"type":"string"},"predictedEta":{"type":["string","null"],"format":"date-time","description":"Navlo's predicted arrival; null when there is none or the box has arrived. Port-local time with a Z suffix."}}},"ApiShipmentNextPlannedVessel":{"type":"object","properties":{"plannedAt":{"type":["string","null"],"format":"date-time","description":"When it is planned to load."},"portCode":{"type":["string","null"]},"portName":{"type":["string","null"]},"vesselName":{"type":"string"},"voyageNumber":{"type":["string","null"]}}},"ApiShipmentPageWithIncludes":{"type":"object","description":"One page of shipments.","properties":{"page":{"type":"integer","format":"int32","description":"0-based page number, as requested."},"shipments":{"type":"array","items":{"$ref":"#/components/schemas/ApiShipmentSummaryWithIncludes"}},"size":{"type":"integer","format":"int32"},"totalElements":{"type":"integer","format":"int64"},"totalPages":{"type":"integer","format":"int32"}}},"ApiShipmentPatchRequest":{"type":"object","description":"Only the keys you send change. `customer: null` clears the customer; leaving the key out keeps it.","properties":{"customer":{"description":"The customer to file the shipment under, or null to clear it.","oneOf":[{"$ref":"#/components/schemas/CustomerInput"},{"type":"null"}]}}},"ApiShipmentRecommendation":{"type":"object","description":"A recommended action card, the same one the shipment page shows.","properties":{"computedAt":{"type":["string","null"],"format":"date-time","description":"When the card was written (UTC)."},"confidence":{"type":"string","description":"HIGH, MEDIUM or LOW.","example":"HIGH"},"id":{"type":"string","description":"Opaque card id: the same card keeps it across refreshes.","example":"rec_5f2a9c1e7b3d4a60"},"impact":{"type":"string","description":"What the situation means for this shipment."},"kind":{"type":"string","description":"What the card is about, e.g. storm, port, eta, dnd, congestion, idle.","example":"storm"},"recommendation":{"type":"string","description":"What to do about it."},"severity":{"type":"string","description":"CRITICAL, HIGH, MEDIUM or LOW; INFO for informational cards.","example":"HIGH"},"title":{"type":"string"}}},"ApiShipmentRisk":{"type":"object","description":"Navlo's risk assessment. `level` is set only while the assessment is current.","properties":{"computedAt":{"type":["string","null"],"format":"date-time","description":"When Navlo last assessed the shipment (UTC)."},"level":{"type":["string","null"],"description":"LOW, MEDIUM or HIGH while fresh; null when stale, never computed, or the shipment is still discovering. Never LOW for unknown.","example":"MEDIUM"},"score":{"type":["integer","null"],"format":"int32","description":"0–100 risk score behind the level; null without a fresh level.","example":57},"stale":{"type":"boolean","description":"True when there is no current assessment; `level` is then null."},"summary":{"type":["string","null"],"description":"The main reason, in one sentence; null without a fresh level."}}},"ApiShipmentRiskSummary":{"type":"object","description":"Risk on a list item: the same freshness rule as the detail's `risk`.","properties":{"computedAt":{"type":["string","null"],"format":"date-time"},"level":{"type":["string","null"],"description":"LOW, MEDIUM or HIGH while fresh; null otherwise.","example":"HIGH"},"stale":{"type":"boolean"}}},"ApiShipmentSummary":{"type":"object","description":"A shipment as it appears on create and in the list.","properties":{"carrier":{"type":["string","null"],"description":"Carrier code, once Navlo knows the carrier.","example":"MSC"},"createdAt":{"type":["string","null"],"format":"date-time","description":"When the shipment was created in Navlo (UTC)."},"id":{"type":"string","format":"uuid"},"identifier":{"type":"string","description":"The number you track: container, B/L, booking or air waybill.","example":"MEDU1234562"},"mode":{"type":["string","null"],"enum":["OCEAN","AIR"],"example":"OCEAN"},"status":{"type":["string","null"],"description":"discovering, resolving, active (ocean) or tracking (air) while it runs, completed, stopped.","enum":["discovering","resolving","active","tracking","completed","stopped"],"example":"active"}}},"ApiShipmentSummaryWithIncludes":{"type":"object","description":"A list item. The keys after `createdAt` appear only when requested with `include`.","properties":{"carrier":{"type":["string","null"]},"createdAt":{"type":["string","null"],"format":"date-time"},"customer":{"description":"Present only when requested with include=customer. Null when the shipment has no customer.","oneOf":[{"$ref":"#/components/schemas/CustomerRef"},{"type":"null"}]},"id":{"type":"string","format":"uuid"},"identifier":{"type":"string"},"lastChangedAt":{"type":["string","null"],"format":"date-time","description":"Present only when requested with include=lastChangedAt. When the shipment last changed in a way you would see (status, ETA, discovery outcome), UTC — the value to pass back as updatedSince."},"mode":{"type":["string","null"],"enum":["OCEAN","AIR"]},"risk":{"description":"Present only when requested with include=risk.","oneOf":[{"$ref":"#/components/schemas/ApiShipmentRiskSummary"},{"type":"null"}]},"status":{"type":["string","null"],"description":"discovering, resolving, active (ocean) or tracking (air) while it runs, completed, stopped.","enum":["discovering","resolving","active","tracking","completed","stopped"]},"tags":{"type":["array","null"],"description":"Present only when requested with include=tags.","items":{"$ref":"#/components/schemas/ApiShipmentTag"}}}},"ApiShipmentTag":{"type":"object","description":"A tag on the shipment.","properties":{"color":{"type":["string","null"],"description":"Hex color.","example":"#E5484D"},"id":{"type":"string","format":"uuid"},"name":{"type":"string","example":"Urgent"}}},"ApiStartTrackingRequest":{"type":"object","description":"Start tracking one shipment.","properties":{"carrier":{"type":["string","null"],"description":"Carrier code, when you know it. Speeds up the first lookup.","example":"MSC"},"customer":{"description":"Files the shipment under one of your customers. Re-sending a shipment with a customer re-files it.","oneOf":[{"$ref":"#/components/schemas/CustomerInput"},{"type":"null"}]},"identifier":{"type":"string","description":"Container, B/L, booking or air waybill number.","example":"MEDU1234562"},"mode":{"type":["string","null"],"description":"OCEAN or AIR. A valid container number or an air waybill with a known airline prefix wins over the sent value.","enum":["OCEAN","AIR"],"example":"OCEAN"}},"required":["identifier","mode"]},"ApiVesselPosition":{"type":"object","description":"Last known position of the vessel the shipment is on. Branch on `source`: LAST_KNOWN coordinates are the last port passed, not a ship.","properties":{"heading":{"type":["number","null"],"format":"double","description":"Course over ground in degrees, when the fix carries one."},"latitude":{"type":"number","format":"double"},"longitude":{"type":"number","format":"double"},"reportedAt":{"type":["string","null"],"format":"date-time","description":"AIS fix time (UTC) for LIVE and STALE; null for LAST_KNOWN."},"source":{"type":"string","enum":["LIVE","STALE","LAST_KNOWN"],"example":"LIVE"},"vesselName":{"type":["string","null"]}}},"AssignTagRequest":{"type":"object","properties":{"name":{"type":["string","null"],"description":"A tag name; a missing tag is created in the default colour.","example":"Urgent"},"tagId":{"type":["string","null"],"format":"uuid","description":"An existing tag's id. Wins when both fields are sent."}}},"ChangeCarrierRequest":{"type":"object","properties":{"carrier":{"type":["string","null"],"description":"The carrier's code or name, the way you would type it when tracking (\"MSC\", \"Hapag-Lloyd\").","example":"MSC"}},"required":["carrier"]},"ChangeCarrierResult":{"type":"object","properties":{"carrier":{"type":"string","description":"The carrier code the shipment is now tracked with.","example":"MSC"},"id":{"type":"string","format":"uuid"},"status":{"type":"string","description":"Public status after the change; discovery restarts with the new carrier.","example":"discovering"}}},"CompletedDetails":{"type":"object","description":"details of shipment.completed.","properties":{"awbNumber":{"type":["string","null"],"example":"235-12345675"},"completedAt":{"type":"string","description":"When the journey ended: the delivery (or arrival) the carrier reported.","example":"2026-10-21T09:15:00Z"},"containerNumber":{"type":["string","null"],"description":"The container that completed last (ocean).","example":"MSCU7382154"}}},"CreateReportRequest":{"type":"object","properties":{"filters":{"oneOf":[{"$ref":"#/components/schemas/ReportFilters"},{"type":"null"}]},"type":{"type":["string","null"],"description":"STATUS (shipment status list), COST (cost analysis) or DND_RISK (demurrage & detention exposure).","example":"STATUS"}},"required":["type"]},"CreateTagRequest":{"type":"object","properties":{"color":{"type":["string","null"],"description":"Hex colour (#rrggbb or #rgb). Defaults to #3b82f6, the app's first preset.","example":"#ef4444"},"name":{"type":["string","null"],"description":"Up to 50 characters; unique in your organization regardless of case.","example":"Urgent"}},"required":["name"]},"CreateWebhookRequest":{"type":"object","properties":{"name":{"type":"string","description":"Your label for the endpoint (max 120).","example":"ERP production"},"topics":{"type":["array","null"],"description":"Topic names to receive (GET /v1/webhooks/topics); omit or send [] for every topic.","items":{"type":"string"}},"url":{"type":"string","description":"https:// URL, no credentials in it.","example":"https://erp.example.com/hooks/navlo"}},"required":["name","url"]},"CreditBalances":{"type":"object","properties":{"aiCredits":{"type":"number","description":"Navlo AI credits. For an organization admin this is the organization's AI pool.","example":18.5},"trackingCredits":{"type":"number","description":"Tracking credits (shipments, vessel tracking). For an organization admin this is the organization's pool.","example":120}}},"Customer":{"type":"object","properties":{"address":{"type":["string","null"]},"archived":{"type":"boolean","description":"Archived customers are hidden from the app's directory and pickers but keep their shipments."},"city":{"type":["string","null"]},"contacts":{"type":"array","items":{"$ref":"#/components/schemas/CustomerContact"}},"countryCode":{"type":["string","null"],"description":"ISO 3166-1 alpha-2.","example":"TR"},"createdAt":{"type":"string","format":"date-time"},"id":{"type":"string","format":"uuid"},"name":{"type":"string","example":"Acme Trading Ltd."},"ref":{"type":["string","null"],"description":"Your own reference, when set. Unique per organization, case-insensitive.","example":"C-1042"},"shipmentCount":{"type":"integer","format":"int64","description":"Shipments currently assigned to this customer."},"taxId":{"type":["string","null"]},"updatedAt":{"type":"string","format":"date-time"}}},"CustomerContact":{"type":"object","properties":{"email":{"type":["string","null"]},"name":{"type":"string"},"phone":{"type":["string","null"]},"primary":{"type":"boolean","description":"The customer's main contact. At most one contact is primary."},"role":{"type":["string","null"],"description":"Their role at the customer.","example":"Operations"}}},"CustomerContactInput":{"type":"object","properties":{"email":{"type":["string","null"],"format":"email","maxLength":320,"minLength":0},"name":{"type":"string","maxLength":200,"minLength":0},"phone":{"type":["string","null"],"maxLength":50,"minLength":0},"primary":{"type":"boolean","description":"Only the first contact sent as primary stays primary."},"role":{"type":["string","null"],"example":"Operations","maxLength":100,"minLength":0}},"required":["name"]},"CustomerCreateRequest":{"type":"object","properties":{"address":{"type":["string","null"],"maxLength":1000,"minLength":0},"city":{"type":["string","null"],"maxLength":100,"minLength":0},"contacts":{"type":"array","items":{"$ref":"#/components/schemas/CustomerContactInput"},"maxItems":50,"minItems":0},"countryCode":{"type":["string","null"],"description":"ISO 3166-1 alpha-2.","example":"TR","pattern":"^\\s*[A-Za-z]{2}\\s*$"},"name":{"type":"string","example":"Acme Trading Ltd.","maxLength":200,"minLength":0},"ref":{"type":["string","null"],"description":"Your own code for the customer. A reference another customer already has is a 409.","example":"C-1042","maxLength":100,"minLength":0},"taxId":{"type":["string","null"],"maxLength":100,"minLength":0}},"required":["name"]},"CustomerInput":{"type":"object","description":"Assigns the request to one of your customers: send Navlo's `id`, or your own `ref` (+ `name`). An unknown `ref` creates the customer.","properties":{"id":{"type":["string","null"],"format":"uuid","description":"Navlo's customer id.","example":"0c7d2f6e-3a41-4b0e-9a55-1f2b3c4d5e6f"},"name":{"type":["string","null"],"description":"Company name, used only when `ref` is new and the customer is created.","example":"Acme Trading Ltd."},"ref":{"type":["string","null"],"description":"Your own code for the customer, e.g. from your accounting system. Unique per organization.","example":"C-1042"}}},"CustomerPage":{"type":"object","properties":{"customers":{"type":"array","items":{"$ref":"#/components/schemas/Customer"}},"page":{"type":"integer","format":"int32","description":"0-based page number."},"size":{"type":"integer","format":"int32"},"totalElements":{"type":"integer","format":"int64"},"totalPages":{"type":"integer","format":"int32"}}},"CustomerPatchRequest":{"type":"object","description":"Only the keys you send change. `null` (or \"\") clears an optional field; `name` cannot be cleared. `contacts` replaces the whole list (send [] to remove every contact).","properties":{"address":{"type":["string","null"]},"city":{"type":["string","null"]},"contacts":{"type":["array","null"],"items":{"$ref":"#/components/schemas/CustomerContactInput"}},"countryCode":{"type":["string","null"],"description":"ISO 3166-1 alpha-2.","example":"TR"},"name":{"type":["string","null"]},"ref":{"type":["string","null"]},"taxId":{"type":["string","null"]}}},"CustomerRef":{"type":"object","properties":{"countryCode":{"type":["string","null"],"description":"ISO 3166-1 alpha-2.","example":"TR"},"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"ref":{"type":["string","null"],"description":"Your own reference, when set.","example":"C-1042"}}},"DiscoveryFinishedDetails":{"type":"object","description":"details of shipment.discovery_finished.","properties":{"carrier":{"type":["string","null"],"description":"Carrier code, when known.","example":"MSC"},"outcome":{"type":"string","description":"RESOLVED: the carrier returned the shipment and Navlo tracks it. NOT_FOUND: no carrier data, and Navlo stopped searching on its own; a later find sends RESOLVED.","example":"RESOLVED"},"status":{"type":"string","description":"The shipment's public status after discovery.","example":"active"}}},"DndDetails":{"type":"object","description":"details of shipment.dnd.","properties":{"awbNumber":{"type":["string","null"],"example":"235-12345675"},"containerNumber":{"type":["string","null"],"example":"MSCU7382154"},"daysLeft":{"type":["integer","null"],"format":"int64","description":"Whole days of free time left; 0 once it is over.","example":2},"freeTimeEndsAt":{"type":["string","null"],"description":"When the free time ends or ended (for EMPTY_RETURN_DUE: the return deadline).","example":"2026-10-24T00:00:00Z"},"kind":{"type":"string","description":"FREE_TIME_WARNING, DEMURRAGE_STARTED, DETENTION_STARTED, EMPTY_RETURN_DUE, EMPTY_RETURNED or AIR_STORAGE_RISK.","example":"FREE_TIME_WARNING"}}},"DocumentDownload":{"type":"object","properties":{"expiresAt":{"type":"string","format":"date-time"},"url":{"type":"string","description":"Download link on api.navlo.io, valid for 15 minutes. A plain GET without an API key redirects to the file. Do not store it — ask again when it has expired.","example":"https://api.navlo.io/api/documents/d/AbC123.xYz789"}}},"EtaChangedDetails":{"type":"object","description":"details of shipment.eta_changed.","properties":{"awbNumber":{"type":["string","null"],"example":"235-12345675"},"containerNumber":{"type":["string","null"],"example":"MSCU7382154"},"deltaHours":{"type":["number","null"],"format":"double","description":"newEta minus previousEta in hours, one decimal: positive = later, negative = earlier.","example":54.0},"newEta":{"type":["string","null"],"description":"The new ETA.","example":"2026-11-04T14:00:00Z"},"previousEta":{"type":["string","null"],"description":"The ETA before this change.","example":"2026-11-02T08:00:00Z"}}},"LocationCoordinates":{"type":"object","properties":{"lat":{"type":"number","format":"double"},"lng":{"type":"number","format":"double"}}},"NextPlannedVesselResponse":{"type":"object","properties":{"plannedAt":{"type":["string","null"],"format":"date-time"},"portCode":{"type":["string","null"]},"portName":{"type":["string","null"]},"vesselName":{"type":"string"},"voyageNumber":{"type":["string","null"]}}},"PortCongestion":{"type":"object","properties":{"baselineDays":{"type":["integer","null"],"format":"int32","description":"Daily samples the level was judged against."},"calibrating":{"type":"boolean","description":"True while the port has fewer than 14 daily samples; treat its level as provisional."},"congestionLevel":{"type":"string","description":"Judged against the port's own last 30 daily samples, not an absolute scale.","enum":["LOW","MEDIUM","HIGH","CRITICAL"]},"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2: the first two letters of the UN/LOCODE.","example":"TR"},"latitude":{"type":["number","null"],"format":"double"},"locode":{"type":"string","description":"UN/LOCODE.","example":"TRAMR"},"longitude":{"type":["number","null"],"format":"double"},"medianTimeInPortHours":{"type":["number","null"],"format":"double","description":"Median time the vessels in port have been there, hours."},"medianWaitHours":{"type":["number","null"],"format":"double","description":"Median time those vessels have been waiting, hours; null when none is waiting or the anchorage isn't measured."},"name":{"type":["string","null"],"example":"Ambarli"},"sampledAt":{"type":["string","null"],"format":"date-time","description":"When the sample was taken (UTC)."},"vesselsAtAnchorage":{"type":["integer","null"],"format":"int32","description":"Commercial vessels waiting at anchor; null where Navlo doesn't measure the port's anchorage."},"vesselsInPort":{"type":["integer","null"],"format":"int32","description":"Commercial vessels in port."}}},"PortCongestionHistory":{"type":"object","properties":{"available":{"type":"boolean","description":"False when Navlo's port data could not be read just now; `history` is then empty. Retry later."},"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2.","example":"TR"},"days":{"type":"integer","format":"int32","description":"The window the history covers, days back from now.","example":30},"history":{"type":"array","description":"One sample a day, oldest first.","items":{"$ref":"#/components/schemas/PortCongestionSample"}},"latitude":{"type":["number","null"],"format":"double"},"locode":{"type":"string","description":"UN/LOCODE.","example":"TRAMR"},"longitude":{"type":["number","null"],"format":"double"},"name":{"type":["string","null"],"example":"Ambarli"}}},"PortCongestionList":{"type":"object","properties":{"available":{"type":"boolean","description":"False when Navlo's port data could not be read just now; `ports` is then empty. Retry later."},"ports":{"type":"array","description":"Most congested first.","items":{"$ref":"#/components/schemas/PortCongestion"}},"scope":{"type":"string","description":"Which ports are listed: `shipments` = the ports on your active ocean shipments (origin, destination, current port), `all` = every port Navlo samples.","enum":["shipments","all"]}}},"PortCongestionSample":{"type":"object","properties":{"baselineDays":{"type":["integer","null"],"format":"int32","description":"Daily samples the level was judged against."},"calibrating":{"type":"boolean","description":"True while the port had fewer than 14 daily samples behind it."},"congestionLevel":{"type":"string","enum":["LOW","MEDIUM","HIGH","CRITICAL"]},"medianTimeInPortHours":{"type":["number","null"],"format":"double","description":"Median time the vessels in port had been there, hours."},"medianWaitHours":{"type":["number","null"],"format":"double","description":"Median waiting time of those vessels, hours; null when the anchorage isn't measured."},"sampledAt":{"type":"string","format":"date-time","description":"When the sample was taken (UTC)."},"vesselsAtAnchorage":{"type":["integer","null"],"format":"int32","description":"Commercial vessels waiting at anchor; null where Navlo doesn't measure the port's anchorage."},"vesselsInPort":{"type":["integer","null"],"format":"int32","description":"Commercial vessels in port."}}},"PublicAirMilestone":{"type":"object","properties":{"actualTimestamp":{"type":["string","null"],"format":"date-time"},"airportCode":{"type":["string","null"]},"airportCoordinates":{"oneOf":[{"$ref":"#/components/schemas/LocationCoordinates"},{"type":"null"}]},"airportCountryCode":{"type":["string","null"]},"airportName":{"type":["string","null"]},"cargoEventType":{"type":"string"},"effectiveTimestamp":{"type":["string","null"],"format":"date-time"},"eventType":{"type":"string"},"flightNumber":{"type":["string","null"]},"flightSegmentId":{"type":["string","null"]},"id":{"type":"string"},"milestoneStatus":{"type":["string","null"]},"navloStatusCategory":{"type":["string","null"]},"navloStatusCode":{"type":["string","null"]},"navloStatusIcon":{"type":["string","null"]},"navloStatusName":{"type":["string","null"]},"piecesCount":{"type":["integer","null"],"format":"int32"},"piecesVolume":{"type":["number","null"]},"piecesWeight":{"type":["number","null"]},"piecesWeightUnit":{"type":["string","null"]},"plannedTimestamp":{"type":["string","null"],"format":"date-time"},"sortInstant":{"type":["string","null"],"format":"date-time"},"transportMode":{"type":["string","null"]}}},"PublicAirShipment":{"type":"object","properties":{"actualArrival":{"type":["string","null"],"format":"date-time"},"actualArrivalUtc":{"type":["string","null"],"format":"date-time"},"actualDeparture":{"type":["string","null"],"format":"date-time"},"actualDepartureUtc":{"type":["string","null"],"format":"date-time"},"actualTimeOfAvailability":{"type":["string","null"],"format":"date-time"},"awbNumber":{"type":["string","null"]},"chargeableWeight":{"type":["number","null"]},"co2Source":{"type":["string","null"]},"co2eKg":{"type":["number","null"]},"courierCode":{"type":"string"},"courierLogoUrl":{"type":["string","null"]},"courierName":{"type":"string"},"currentAirportCode":{"type":["string","null"]},"currentAirportCoordinates":{"oneOf":[{"$ref":"#/components/schemas/LocationCoordinates"},{"type":"null"}]},"deliveredPiecesCount":{"type":["integer","null"],"format":"int32"},"destinationAirportCode":{"type":["string","null"]},"destinationAirportCoordinates":{"oneOf":[{"$ref":"#/components/schemas/LocationCoordinates"},{"type":"null"}]},"destinationAirportName":{"type":["string","null"]},"destinationCountryCode":{"type":["string","null"]},"estimatedArrival":{"type":["string","null"],"format":"date-time"},"estimatedArrivalUtc":{"type":["string","null"],"format":"date-time"},"estimatedDeparture":{"type":["string","null"],"format":"date-time"},"estimatedDepartureUtc":{"type":["string","null"],"format":"date-time"},"flightSegments":{"type":"array","items":{"$ref":"#/components/schemas/PublicFlightSegment"}},"freeStorageUntil":{"type":["string","null"],"format":"date-time"},"id":{"type":"string"},"milestones":{"type":"array","items":{"$ref":"#/components/schemas/PublicAirMilestone"}},"navloStatusCategory":{"type":["string","null"]},"navloStatusCode":{"type":["string","null"]},"navloStatusName":{"type":["string","null"]},"originAirportCode":{"type":["string","null"]},"originAirportCoordinates":{"oneOf":[{"$ref":"#/components/schemas/LocationCoordinates"},{"type":"null"}]},"originAirportName":{"type":["string","null"]},"originCountryCode":{"type":["string","null"]},"piecesCount":{"type":["integer","null"],"format":"int32"},"piecesVolume":{"type":["number","null"]},"piecesVolumeUnit":{"type":["string","null"]},"piecesWeight":{"type":["number","null"]},"piecesWeightUnit":{"type":["string","null"]},"productName":{"type":["string","null"]},"scheduledTimeOfAvailability":{"type":["string","null"],"format":"date-time"},"shipmentParts":{"type":"array","items":{"$ref":"#/components/schemas/AirShipmentPartResponse"}},"statusListingCode":{"type":["string","null"]},"trackingNumber":{"type":["string","null"]}}},"PublicContainer":{"type":"object","properties":{"aboardVessel":{"type":"boolean"},"activities":{"type":"array","items":{"$ref":"#/components/schemas/PublicContainerEvent"}},"actualArrival":{"type":["string","null"],"format":"date-time"},"actualArrivalUtc":{"type":["string","null"],"format":"date-time"},"actualDelivery":{"type":["string","null"],"format":"date-time"},"actualDeparture":{"type":["string","null"],"format":"date-time"},"actualDepartureUtc":{"type":["string","null"],"format":"date-time"},"carrierFreeTimeBasis":{"type":["string","null"]},"carrierFreeTimeDays":{"type":["integer","null"],"format":"int32"},"co2Source":{"type":["string","null"]},"co2eKg":{"type":["number","null"]},"completedAt":{"type":["string","null"],"format":"date-time"},"containerIsoCode":{"type":["string","null"]},"containerNumber":{"type":"string"},"containerType":{"type":["string","null"]},"courierCode":{"type":"string"},"courierLogoUrl":{"type":["string","null"]},"courierName":{"type":"string"},"currentLocation":{"type":["string","null"]},"currentLocationCode":{"type":["string","null"]},"currentVesselImo":{"type":["string","null"]},"currentVesselName":{"type":["string","null"]},"currentVoyageNumber":{"type":["string","null"]},"demurrageFreeUntil":{"type":["string","null"],"format":"date-time"},"destinationCountryCode":{"type":["string","null"]},"destinationPortCode":{"type":["string","null"]},"destinationPortCoordinates":{"oneOf":[{"$ref":"#/components/schemas/LocationCoordinates"},{"type":"null"}]},"destinationPortName":{"type":["string","null"]},"destinationTerminal":{"type":["string","null"]},"estimatedArrival":{"type":["string","null"],"format":"date-time"},"estimatedArrivalUtc":{"type":["string","null"],"format":"date-time"},"estimatedDelivery":{"type":["string","null"],"format":"date-time"},"estimatedDeparture":{"type":["string","null"],"format":"date-time"},"estimatedDepartureUtc":{"type":["string","null"],"format":"date-time"},"id":{"type":"string"},"navloStatusCategory":{"type":["string","null"]},"navloStatusCode":{"type":["string","null"]},"navloStatusName":{"type":["string","null"]},"nextPlannedVessel":{"oneOf":[{"$ref":"#/components/schemas/NextPlannedVesselResponse"},{"type":"null"}]},"originCountryCode":{"type":["string","null"]},"originPortCode":{"type":["string","null"]},"originPortCoordinates":{"oneOf":[{"$ref":"#/components/schemas/LocationCoordinates"},{"type":"null"}]},"originPortName":{"type":["string","null"]},"originTerminal":{"type":["string","null"]},"statusListingCode":{"type":["string","null"]},"statusListingName":{"type":["string","null"]}}},"PublicContainerEvent":{"type":"object","properties":{"activityTimestamp":{"type":["string","null"],"format":"date-time"},"courierStatus":{"type":"string"},"detectionSource":{"type":["string","null"]},"eventType":{"type":["string","null"]},"id":{"type":"string"},"location":{"type":["string","null"]},"locationCode":{"type":["string","null"]},"locationCoordinates":{"oneOf":[{"$ref":"#/components/schemas/LocationCoordinates"},{"type":"null"}]},"locationCountryCode":{"type":["string","null"]},"navloStatusCategory":{"type":["string","null"]},"navloStatusCode":{"type":["string","null"]},"navloStatusDisplayOrder":{"type":["integer","null"],"format":"int32"},"navloStatusIcon":{"type":["string","null"]},"navloStatusName":{"type":["string","null"]},"terminalName":{"type":["string","null"]},"transportMode":{"type":["string","null"]},"vesselName":{"type":["string","null"]},"voyageNumber":{"type":["string","null"]}}},"PublicFlightSegment":{"type":"object","properties":{"actualArrivalTime":{"type":["string","null"],"format":"date-time"},"actualDepartureTime":{"type":["string","null"],"format":"date-time"},"aircraftType":{"type":["string","null"]},"arrivalUtcOffsetMinutes":{"type":["integer","null"],"format":"int32"},"carrierCode":{"type":["string","null"]},"departureUtcOffsetMinutes":{"type":["integer","null"],"format":"int32"},"destinationAirportCode":{"type":["string","null"]},"destinationAirportCoordinates":{"oneOf":[{"$ref":"#/components/schemas/LocationCoordinates"},{"type":"null"}]},"destinationAirportName":{"type":["string","null"]},"destinationCountryCode":{"type":["string","null"]},"estimatedArrivalTime":{"type":["string","null"],"format":"date-time"},"estimatedDepartureTime":{"type":["string","null"],"format":"date-time"},"flightDate":{"type":["string","null"],"format":"date"},"flightNumber":{"type":"string"},"id":{"type":"string"},"originAirportCode":{"type":["string","null"]},"originAirportCoordinates":{"oneOf":[{"$ref":"#/components/schemas/LocationCoordinates"},{"type":"null"}]},"originAirportName":{"type":["string","null"]},"originCountryCode":{"type":["string","null"]},"piecesCount":{"type":["integer","null"],"format":"int32"},"piecesVolume":{"type":["number","null"]},"piecesWeight":{"type":["number","null"]},"scheduledArrivalTime":{"type":["string","null"],"format":"date-time"},"scheduledDepartureTime":{"type":["string","null"],"format":"date-time"},"segmentOrder":{"type":"integer","format":"int32"},"transportMode":{"type":["string","null"]}}},"PublicShipmentResponse":{"type":"object","properties":{"airShipments":{"type":"array","items":{"$ref":"#/components/schemas/PublicAirShipment"}},"containers":{"type":"array","items":{"$ref":"#/components/schemas/PublicContainer"}},"status":{"type":"string"},"trackingIdentifier":{"type":"string"},"trackingMode":{"type":"string"},"vesselPosition":{"oneOf":[{"$ref":"#/components/schemas/PublicVesselPosition"},{"type":"null"}]}}},"PublicVesselPosition":{"type":"object","properties":{"ageHours":{"type":["integer","null"],"format":"int32"},"heading":{"type":["number","null"],"format":"double"},"latitude":{"type":"number","format":"double"},"longitude":{"type":"number","format":"double"},"reportedAt":{"type":["string","null"],"format":"date-time"},"source":{"type":"string"},"vesselName":{"type":"string"}}},"Report":{"type":"object","properties":{"expiresAt":{"type":"string","format":"date-time","description":"The link works for 7 days."},"fileName":{"type":"string","example":"shipment-status-report-20261022.xlsx"},"type":{"type":"string","example":"STATUS"},"url":{"type":"string","description":"Download link; anyone holding it can download the file until it expires."}}},"ReportFilters":{"type":"object","description":"STATUS and DND_RISK: mode, status, carrier, originPort, destinationPort, originCountry, destinationCountry, etaFrom, etaTo — or shipments on its own. COST: mode, carrier, destinationPort, originCountry, destinationCountry, etaFrom, etaTo, shipments, from, to. Dates are whole UTC days.","properties":{"carrier":{"type":["string","null"],"description":"Carrier code or name.","example":"MSC"},"customerId":{"type":["string","null"],"description":"STATUS and DND_RISK: one customer's shipments — a Navlo customer id, or `none` for shipments without a customer.","example":"0c7d2f6e-3a41-4b0e-9a55-1f2b3c4d5e6f"},"customerRef":{"type":["string","null"],"description":"STATUS and DND_RISK: one customer's shipments by your own reference. Unknown reference = 400.","example":"C-1042"},"destinationCountry":{"type":["string","null"],"description":"ISO 3166-1 alpha-2.","example":"NL"},"destinationPort":{"type":["string","null"],"description":"Port of discharge, UN/LOCODE (airport code for air). COST also takes a port name.","example":"NLRTM"},"etaFrom":{"type":["string","null"],"description":"ETA on or after this day (YYYY-MM-DD).","example":"2026-10-01"},"etaTo":{"type":["string","null"],"description":"ETA on or before this day (YYYY-MM-DD).","example":"2026-10-31"},"from":{"type":["string","null"],"description":"COST only: first day of the analysed period (default: 30 days before `to`).","example":"2026-09-01"},"mode":{"type":["string","null"],"description":"OCEAN or AIR. COST with AIR is the air storage-charge analysis.","example":"OCEAN"},"originCountry":{"type":["string","null"],"description":"ISO 3166-1 alpha-2.","example":"TR"},"originPort":{"type":["string","null"],"description":"Port of loading, UN/LOCODE (airport code for air).","example":"TRMER"},"shipments":{"type":["array","null"],"description":"Container, B/L, booking or AWB numbers (max 100). For STATUS and DND_RISK it cannot be combined with other filters.","example":["MSCU1234567"],"items":{"type":"string"}},"status":{"type":["array","null"],"description":"Public statuses: discovering, resolving, active, completed, stopped.","example":["active"],"items":{"type":"string"}},"tag":{"type":["array","null"],"description":"STATUS and DND_RISK: tag names, any of them. Unknown tag = 400.","example":["Priority"],"items":{"type":"string"}},"to":{"type":["string","null"],"description":"COST only: last day of the analysed period (default: today).","example":"2026-09-30"}}},"RiskRaisedDetails":{"type":"object","description":"details of shipment.risk_raised.","properties":{"awbNumber":{"type":["string","null"],"example":"235-12345675"},"containerNumber":{"type":["string","null"],"example":"MSCU7382154"},"kind":{"type":"string","description":"RISK_ALERT, ROLLOVER, TRANSSHIPMENT_DELAY, CARGO_NOT_LOADED or BOOKING_CANCELLED.","example":"RISK_ALERT"},"level":{"type":["string","null"],"description":"CRITICAL, HIGH, MEDIUM or LOW when the risk is graded (today: RISK_ALERT).","example":"HIGH"},"summary":{"type":["string","null"],"description":"One sentence on what was found, when there is one.","example":"MSCU7382154 has not moved for 6 days at Port Klang."}}},"RouteChangedDetails":{"type":"object","description":"details of shipment.route_changed.","properties":{"newDestination":{"description":"The port of discharge now.","oneOf":[{"$ref":"#/components/schemas/WebhookPlace"},{"type":"null"}]},"previousDestination":{"description":"The port of discharge before the change.","oneOf":[{"$ref":"#/components/schemas/WebhookPlace"},{"type":"null"}]}}},"ShareLink":{"type":"object","properties":{"token":{"type":"string","description":"The link's secret part. Revoking the link (DELETE) makes it stop working."},"url":{"type":"string","description":"Public, read-only shipment page anyone with the link can open (no Navlo account needed).","example":"https://app.navlo.io/shipment/shared/5t1QJ0wQe7bS2xk9vG3nDm4LhA8"}}},"ShipmentDocument":{"type":"object","properties":{"contentType":{"type":"string","example":"application/pdf"},"createdAt":{"type":"string","format":"date-time"},"documentType":{"type":"string","description":"BILL_OF_LADING, INVOICE, PACKING_LIST, CUSTOMS_DECLARATION or OTHER.","example":"INVOICE"},"fileName":{"type":"string"},"id":{"type":"string","format":"uuid"},"sizeBytes":{"type":"integer","format":"int64"},"uploadedBy":{"type":"string","description":"Name of the person who uploaded it.","example":"Ayşe Yılmaz"}}},"ShipmentMuteState":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"notificationsMuted":{"type":"boolean","description":"True while every Navlo notification about this shipment is off. Webhooks keep firing."}}},"ShipmentNote":{"type":"object","properties":{"authorName":{"type":"string","description":"Who wrote it. Notes added through the API are written by the API key's creator.","example":"Ayşe Yılmaz"},"content":{"type":"string","description":"The note text. Mentions keep the app's markup, e.g. `@[<userId>|Ayşe Yılmaz]`."},"createdAt":{"type":"string","format":"date-time"},"id":{"type":"string","format":"uuid"},"updatedAt":{"type":"string","format":"date-time","description":"When the text last changed; equals createdAt for a note never edited."}}},"ShipmentNotePage":{"type":"object","properties":{"notes":{"type":"array","description":"Newest first.","items":{"$ref":"#/components/schemas/ShipmentNote"}},"page":{"type":"integer","format":"int32"},"size":{"type":"integer","format":"int32"},"totalElements":{"type":"integer","format":"int64"},"totalPages":{"type":"integer","format":"int32"}}},"ShipmentNoteRequest":{"type":"object","properties":{"content":{"type":["string","null"],"description":"Note text, up to 10,000 characters.","example":"Customer asked for delivery before Friday."}},"required":["content"]},"ShipmentStatusResult":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","description":"Public status: discovering, resolving, active, completed or stopped.","example":"completed"}}},"ShipmentSubscriber":{"type":"object","properties":{"createdAt":{"type":"string","format":"date-time"},"email":{"type":"string"},"events":{"type":"array","description":"Milestone groups this address gets mail for (PRE_SHIPMENT, ORIGIN, TRANSIT, DESTINATION, COMPLETED). Empty = every status change.","items":{"type":"string"}},"id":{"type":"string","format":"uuid"}}},"StatusChangedDetails":{"type":"object","description":"details of shipment.status_changed.","properties":{"awbNumber":{"type":["string","null"],"description":"The air waybill the event is about (air).","example":"235-12345675"},"containerNumber":{"type":["string","null"],"description":"The container the event is about (ocean).","example":"MSCU7382154"},"eventAt":{"type":["string","null"],"description":"When it happened (carrier local time, Z suffix), when known.","example":"2026-10-20T14:30:00Z"},"location":{"description":"Where it happened, when known.","oneOf":[{"$ref":"#/components/schemas/WebhookPlace"},{"type":"null"}]},"milestone":{"description":"The status the event announces.","oneOf":[{"$ref":"#/components/schemas/WebhookMilestone"},{"type":"null"}]},"status":{"type":"string","description":"The shipment's public status after the event.","example":"active"}}},"Tag":{"type":"object","properties":{"color":{"type":["string","null"],"description":"Hex colour.","example":"#3b82f6"},"id":{"type":"string","format":"uuid"},"name":{"type":"string","example":"Urgent"}}},"UpdateWebhookRequest":{"type":"object","description":"Only the keys you send change.","properties":{"active":{"type":["boolean","null"],"description":"false pauses deliveries; true resumes them and clears the failure count."},"name":{"type":["string","null"]},"topics":{"type":["array","null"],"description":"Replaces the subscription; [] = every topic.","items":{"type":"string"}},"url":{"type":["string","null"]}}},"UsageGroup":{"type":"object","properties":{"aiCredits":{"type":"number"},"customer":{"oneOf":[{"$ref":"#/components/schemas/CustomerRef"},{"type":"null"}]},"day":{"type":["string","null"],"description":"UTC day, for groupBy=day.","example":"2026-10-14"},"netCredits":{"type":"number"},"refundedCredits":{"type":"number"},"shipment":{"oneOf":[{"$ref":"#/components/schemas/UsageShipment"},{"type":"null"}]},"shipmentsStarted":{"type":"integer","format":"int64"},"trackingCredits":{"type":"number"},"vesselCredits":{"type":"number"}}},"UsageReport":{"type":"object","properties":{"from":{"type":"string","description":"First day of the report, inclusive (UTC).","example":"2026-10-01"},"groupBy":{"type":"string","enum":["customer","shipment","day","none"],"example":"customer"},"groups":{"type":"array","description":"One entry per customer, shipment or day (empty for groupBy=none).","items":{"$ref":"#/components/schemas/UsageGroup"}},"to":{"type":"string","description":"Day after the last day of the report, exclusive (UTC).","example":"2026-11-01"},"totals":{"$ref":"#/components/schemas/UsageTotals"}}},"UsageShipment":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"identifier":{"type":"string","description":"Container, booking, bill of lading or air waybill number.","example":"MSCU1234567"}}},"UsageTotals":{"type":"object","properties":{"aiCredits":{"type":"number","description":"AI credits charged for Navlo AI answers.","example":1.35},"netCredits":{"type":"number","description":"trackingCredits − refundedCredits + vesselCredits + aiCredits.","example":45.35},"refundedCredits":{"type":"number","description":"Tracking credits given back to your balance, for example for a number that never produced data.","example":2},"shipmentsStarted":{"type":"integer","format":"int64","description":"Shipments started in the period, charged or free."},"trackingCredits":{"type":"number","description":"Tracking credits charged for shipments.","example":42},"vesselCredits":{"type":"number","description":"Tracking credits charged for vessel tracking (per voyage).","example":4}}},"VesselEtaPoint":{"type":"object","properties":{"destination":{"type":["string","null"],"description":"The AIS destination the ETA was for.","example":"TRIZT"},"eta":{"type":"string","format":"date-time"},"observedAt":{"type":"string","format":"date-time","description":"When Navlo saw this ETA (UTC)."}}},"VesselEvent":{"type":"object","properties":{"destination":{"type":["string","null"],"description":"The AIS destination at the time."},"id":{"type":"string","format":"uuid"},"newEta":{"type":["string","null"],"format":"date-time","description":"ETA_UPDATED: the ETA after the change."},"occurredAt":{"type":"string","format":"date-time"},"portName":{"type":["string","null"],"description":"The port of a departure or arrival."},"previousEta":{"type":["string","null"],"format":"date-time","description":"ETA_UPDATED: the ETA before the change."},"type":{"type":"string","enum":["DEPARTED","ARRIVED","IN_TRANSIT","IN_PORT","AT_ANCHOR","STOPPED","ETA_UPDATED","APPROACHING","SIGNAL_LOST","VOYAGE_COMPLETED","TRACKING_REMINDER","TRACKING_ENDED"]}}},"VesselFollow":{"type":"object","properties":{"completedAt":{"type":["string","null"],"format":"date-time","description":"When the voyage was completed (UTC); null while active."},"createdAt":{"type":"string","format":"date-time","description":"When the vessel was followed (UTC)."},"currentPort":{"description":"The port the vessel is in now; null at sea and on a completed follow.","oneOf":[{"$ref":"#/components/schemas/VesselPort"},{"type":"null"}]},"customer":{"description":"The customer this follow is for; null when none.","oneOf":[{"$ref":"#/components/schemas/CustomerRef"},{"type":"null"}]},"delayed":{"type":"boolean","description":"The ETA slipped more than a day past the first ETA."},"destination":{"type":["string","null"],"description":"AIS destination as the crew typed it. A completed follow keeps the one its voyage ended with.","example":"TRIZT"},"destinationPort":{"description":"The port the destination names, when Navlo can place it. On a completed follow: the port the voyage ended in.","oneOf":[{"$ref":"#/components/schemas/VesselPort"},{"type":"null"}]},"eta":{"type":["string","null"],"format":"date-time","description":"Current ETA at the destination; null when unknown or the follow is completed."},"etaChangeCount":{"type":"integer","format":"int32","description":"How many times the ETA changed in the current voyage."},"firstEta":{"type":["string","null"],"format":"date-time","description":"The first ETA Navlo recorded for this destination in the current voyage (the delay baseline)."},"followedBy":{"oneOf":[{"$ref":"#/components/schemas/VesselFollowedBy"},{"type":"null"}]},"id":{"type":"string","format":"uuid","description":"The follow's id: use it for the other /v1/vessels/follows calls."},"lastPort":{"description":"The last port the vessel left.","oneOf":[{"$ref":"#/components/schemas/VesselPort"},{"type":"null"}]},"overdue":{"type":"boolean","description":"The ETA passed more than a day ago and the vessel is not in port."},"position":{"description":"Latest known position; null until the first one arrives. Stays live after the follow completes.","oneOf":[{"$ref":"#/components/schemas/VesselPosition"},{"type":"null"}]},"state":{"type":"string","description":"What the vessel is doing, from its latest position. UNKNOWN: no recent signal, or the follow is completed.","enum":["IN_TRANSIT","IN_PORT","AT_ANCHOR","STOPPED","UNKNOWN"]},"status":{"type":"string","description":"ACTIVE: the voyage is tracked. COMPLETED: the voyage ended (arrival, you stopped it, or the 60-day limit); following the vessel again starts its next voyage.","enum":["ACTIVE","COMPLETED"]},"vessel":{"$ref":"#/components/schemas/VesselIdentity"}}},"VesselFollowDetail":{"type":"object","description":"Every VesselFollow property, plus the current voyage's ETA history, port calls and events.","properties":{"completedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"currentPort":{"oneOf":[{"$ref":"#/components/schemas/VesselPort"},{"type":"null"}]},"customer":{"oneOf":[{"$ref":"#/components/schemas/CustomerRef"},{"type":"null"}]},"delayed":{"type":"boolean"},"destination":{"type":["string","null"]},"destinationPort":{"oneOf":[{"$ref":"#/components/schemas/VesselPort"},{"type":"null"}]},"eta":{"type":["string","null"],"format":"date-time"},"etaChangeCount":{"type":"integer","format":"int32"},"etaHistory":{"type":"array","description":"ETAs observed in the current voyage, oldest first.","items":{"$ref":"#/components/schemas/VesselEtaPoint"}},"events":{"type":"array","description":"The vessel's activity, newest first (at most 100).","items":{"$ref":"#/components/schemas/VesselEvent"}},"firstEta":{"type":["string","null"],"format":"date-time"},"followedBy":{"oneOf":[{"$ref":"#/components/schemas/VesselFollowedBy"},{"type":"null"}]},"id":{"type":"string","format":"uuid"},"lastPort":{"oneOf":[{"$ref":"#/components/schemas/VesselPort"},{"type":"null"}]},"overdue":{"type":"boolean"},"portCalls":{"type":"array","description":"Port calls of the current voyage, newest first (at most 20).","items":{"$ref":"#/components/schemas/VesselPortCall"}},"position":{"oneOf":[{"$ref":"#/components/schemas/VesselPosition"},{"type":"null"}]},"state":{"type":"string","enum":["IN_TRANSIT","IN_PORT","AT_ANCHOR","STOPPED","UNKNOWN"]},"status":{"type":"string","enum":["ACTIVE","COMPLETED"]},"vessel":{"$ref":"#/components/schemas/VesselIdentity"}}},"VesselFollowPage":{"type":"object","properties":{"follows":{"type":"array","description":"Active follows first, then completed ones; newest first within each.","items":{"$ref":"#/components/schemas/VesselFollow"}},"page":{"type":"integer","format":"int32"},"size":{"type":"integer","format":"int32"},"totalElements":{"type":"integer","format":"int64"},"totalPages":{"type":"integer","format":"int32"}}},"VesselFollowRequest":{"type":"object","description":"The vessel to follow, as the vessel search returned it. An IMO or an MMSI is required: a name alone can match several ships.","properties":{"customer":{"description":"The customer this vessel is followed for (its credits show under that customer in usage reports). Following a vessel you already follow sets or replaces its customer. Absent or null: no change. Ignored by the quote.","oneOf":[{"$ref":"#/components/schemas/CustomerInput"},{"type":"null"}]},"flag":{"type":["string","null"],"description":"Flag state, ISO 3166-1 alpha-2.","example":"LR"},"imo":{"type":["string","null"],"description":"IMO number, 7 digits.","example":"9811000"},"mmsi":{"type":["string","null"],"description":"MMSI, 9 digits.","example":"636019825"},"name":{"type":["string","null"],"description":"Vessel name.","example":"MSC ANNA","maxLength":100,"minLength":0},"vesselType":{"type":["string","null"],"description":"Vessel type, as the search returned it.","example":"Container Ship"}},"required":["name"]},"VesselFollowedBy":{"type":"object","description":"The user the follow belongs to: the API key's creator for follows made through the API.","properties":{"email":{"type":"string"},"name":{"type":"string"}}},"VesselIdentity":{"type":"object","properties":{"callsign":{"type":["string","null"]},"flag":{"type":["string","null"],"description":"Flag state, ISO 3166-1 alpha-2.","example":"LR"},"grossTonnage":{"type":["integer","null"],"format":"int32"},"imo":{"type":["string","null"],"example":"9811000"},"lengthMeters":{"type":["number","null"],"format":"double"},"mmsi":{"type":["string","null"],"example":"636019825"},"name":{"type":"string","example":"MSC ANNA"},"vesselType":{"type":["string","null"],"example":"Container Ship"},"widthMeters":{"type":["number","null"],"format":"double"},"yearBuilt":{"type":["integer","null"],"format":"int32"}}},"VesselPort":{"type":"object","properties":{"arrivedAt":{"type":["string","null"],"format":"date-time","description":"Arrival there (UTC): set on the current port, and on a completed follow's destination port (its ATA)."},"countryCode":{"type":["string","null"],"description":"ISO 3166-1 alpha-2.","example":"TR"},"departedAt":{"type":["string","null"],"format":"date-time","description":"Departure from there (UTC): set on the last port."},"locode":{"type":["string","null"],"description":"UN/LOCODE, when known.","example":"TRIZT"},"name":{"type":"string","example":"Izmit"}}},"VesselPortCall":{"type":"object","properties":{"arrivedAt":{"type":["string","null"],"format":"date-time"},"countryCode":{"type":["string","null"],"description":"ISO 3166-1 alpha-2.","example":"TR"},"current":{"type":"boolean","description":"The vessel is in this port now."},"departedAt":{"type":["string","null"],"format":"date-time"},"locode":{"type":["string","null"],"description":"UN/LOCODE, when known.","example":"TRAMR"},"name":{"type":"string","example":"Ambarli"}}},"VesselPosition":{"type":"object","properties":{"courseDegrees":{"type":["number","null"],"format":"double","description":"Course over ground, degrees (0–359.9); null when the vessel does not report one."},"latitude":{"type":"number","format":"double"},"longitude":{"type":"number","format":"double"},"navStatus":{"type":["string","null"],"description":"AIS navigational status as reported.","example":"Under way using engine"},"reportedAt":{"type":["string","null"],"format":"date-time","description":"When the vessel's AIS transponder reported this position (UTC)."},"speedKnots":{"type":["number","null"],"format":"double"}}},"VesselSearch":{"type":"object","properties":{"available":{"type":"boolean","description":"False when the vessel search could not run just now (the list is then empty): retry shortly."},"results":{"type":"array","description":"Best match first, at most 40.","items":{"$ref":"#/components/schemas/VesselSearchResult"}}}},"VesselSearchResult":{"type":"object","properties":{"flag":{"type":["string","null"],"description":"Flag state, ISO 3166-1 alpha-2.","example":"LR"},"followId":{"type":["string","null"],"format":"uuid","description":"Your follow of this vessel, when you follow it already."},"followStatus":{"type":["string","null"],"description":"ACTIVE: you are tracking it. COMPLETED: its tracked voyage ended; following it again starts its next voyage.","enum":["ACTIVE","COMPLETED"]},"imo":{"type":["string","null"],"example":"9811000"},"mmsi":{"type":["string","null"],"example":"636019825"},"name":{"type":"string","example":"MSC ANNA"},"vesselType":{"type":["string","null"],"example":"Container Ship"}}},"VesselTrackingQuote":{"type":"object","properties":{"alreadyTracking":{"type":"boolean","description":"You already track this vessel: following it again starts nothing and costs nothing."},"covered":{"type":"boolean","description":"One of your active container shipments is on this vessel: the voyage is free."},"credits":{"type":"integer","format":"int32","description":"Credits the follow will take: 2 for a new voyage, 0 when one of your active container shipments is on this vessel or you already track it.","example":2},"enoughCredits":{"type":"boolean","description":"Your credit balance covers the charge (always true when nothing is charged)."}}},"Webhook":{"type":"object","description":"A webhook endpoint of your organization.","properties":{"active":{"type":"boolean","description":"False when you switched it off or Navlo did after 20 failed deliveries in a row."},"consecutiveFailures":{"type":"integer","format":"int32","description":"Failed deliveries since the last success.","example":0},"createdAt":{"type":"string","format":"date-time"},"disabledReason":{"type":["string","null"],"description":"Why Navlo switched the endpoint off; null while it is healthy."},"id":{"type":"string","format":"uuid"},"lastFailureAt":{"type":["string","null"],"format":"date-time"},"lastSuccessAt":{"type":["string","null"],"format":"date-time"},"name":{"type":"string","example":"ERP production"},"topics":{"type":"array","description":"Subscribed topics; empty = every topic, including ones added later.","items":{"type":"string"}},"url":{"type":"string","example":"https://erp.example.com/hooks/navlo"}}},"WebhookCreated":{"type":"object","description":"The new endpoint, with its signing secret. The secret is shown this once.","properties":{"active":{"type":"boolean"},"consecutiveFailures":{"type":"integer","format":"int32"},"createdAt":{"type":"string","format":"date-time"},"disabledReason":{"type":["string","null"]},"id":{"type":"string","format":"uuid"},"lastFailureAt":{"type":["string","null"],"format":"date-time"},"lastSuccessAt":{"type":["string","null"],"format":"date-time"},"name":{"type":"string"},"secret":{"type":"string","description":"HMAC-SHA256 signing secret. Store it now: it is never returned again.","example":"whsec_3f9a..."},"topics":{"type":"array","items":{"type":"string"}},"url":{"type":"string"}}},"WebhookDelivery":{"type":"object","description":"One event sent (or being sent) to an endpoint.","properties":{"attempts":{"type":"integer","format":"int32","description":"Attempts made so far (at most 5).","example":1},"createdAt":{"type":"string","format":"date-time"},"error":{"type":["string","null"],"description":"What went wrong on the last attempt (transport error, or the start of your response)."},"eventId":{"type":"string","format":"uuid","description":"The event id: payload `id` and the X-Navlo-Event-Id header, the same on every retry."},"id":{"type":"string","format":"uuid"},"lastAttemptAt":{"type":["string","null"],"format":"date-time","description":"When Navlo last tried it (or gave up on it); null before the first attempt."},"responseStatus":{"type":["integer","null"],"format":"int32","description":"HTTP status your endpoint answered the last attempt with; null when it could not be reached.","example":200},"shipmentId":{"type":["string","null"],"format":"uuid","description":"The shipment the event is about; null for a test event."},"status":{"type":"string","description":"pending (not tried yet), retrying (failed, will retry), delivered, failed (gave up).","example":"delivered"},"topic":{"type":"string","example":"shipment.status_changed"}}},"WebhookDeliveryPage":{"type":"object","properties":{"deliveries":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDelivery"}},"page":{"type":"integer","format":"int32"},"size":{"type":"integer","format":"int32"},"totalElements":{"type":"integer","format":"int64"},"totalPages":{"type":"integer","format":"int32"}}},"WebhookEventCompleted":{"type":"object","description":"Payload of shipment.completed.","properties":{"data":{"type":["object","null"],"additionalProperties":{},"deprecated":true,"description":"Deprecated: the old block of shipment facts (container, B/L, ports, vessel, dates), sent until 16 November 2026 and then removed. Read `shipment` and `details` instead."},"details":{"$ref":"#/components/schemas/CompletedDetails"},"id":{"type":"string","format":"uuid","description":"Event id. The same in the X-Navlo-Event-Id header and on every retry of this delivery: dedup on it."},"occurredAt":{"type":"string","format":"date-time","description":"When Navlo queued the event (UTC)."},"shipment":{"$ref":"#/components/schemas/WebhookShipment"},"test":{"type":["boolean","null"],"description":"Present, and true, only on test events (Send test event / POST /v1/webhooks/{id}/test)."},"topic":{"type":"string","example":"shipment.completed"}}},"WebhookEventDiscoveryFinished":{"type":"object","description":"Payload of shipment.discovery_finished.","properties":{"details":{"$ref":"#/components/schemas/DiscoveryFinishedDetails"},"id":{"type":"string","format":"uuid","description":"Event id. The same in the X-Navlo-Event-Id header and on every retry of this delivery: dedup on it."},"occurredAt":{"type":"string","format":"date-time","description":"When Navlo queued the event (UTC)."},"shipment":{"$ref":"#/components/schemas/WebhookShipment"},"test":{"type":["boolean","null"],"description":"Present, and true, only on test events (Send test event / POST /v1/webhooks/{id}/test)."},"topic":{"type":"string","example":"shipment.discovery_finished"}}},"WebhookEventDnd":{"type":"object","description":"Payload of shipment.dnd.","properties":{"data":{"type":["object","null"],"additionalProperties":{},"deprecated":true,"description":"Deprecated: the old block of shipment facts (container, B/L, ports, vessel, dates), sent until 16 November 2026 and then removed. Read `shipment` and `details` instead."},"details":{"$ref":"#/components/schemas/DndDetails"},"id":{"type":"string","format":"uuid","description":"Event id. The same in the X-Navlo-Event-Id header and on every retry of this delivery: dedup on it."},"occurredAt":{"type":"string","format":"date-time","description":"When Navlo queued the event (UTC)."},"shipment":{"$ref":"#/components/schemas/WebhookShipment"},"test":{"type":["boolean","null"],"description":"Present, and true, only on test events (Send test event / POST /v1/webhooks/{id}/test)."},"topic":{"type":"string","example":"shipment.dnd"}}},"WebhookEventEtaChanged":{"type":"object","description":"Payload of shipment.eta_changed.","properties":{"data":{"type":["object","null"],"additionalProperties":{},"deprecated":true,"description":"Deprecated: the old block of shipment facts (container, B/L, ports, vessel, dates), sent until 16 November 2026 and then removed. Read `shipment` and `details` instead."},"details":{"$ref":"#/components/schemas/EtaChangedDetails"},"id":{"type":"string","format":"uuid","description":"Event id. The same in the X-Navlo-Event-Id header and on every retry of this delivery: dedup on it."},"occurredAt":{"type":"string","format":"date-time","description":"When Navlo queued the event (UTC)."},"shipment":{"$ref":"#/components/schemas/WebhookShipment"},"test":{"type":["boolean","null"],"description":"Present, and true, only on test events (Send test event / POST /v1/webhooks/{id}/test)."},"topic":{"type":"string","example":"shipment.eta_changed"}}},"WebhookEventRiskRaised":{"type":"object","description":"Payload of shipment.risk_raised.","properties":{"data":{"type":["object","null"],"additionalProperties":{},"deprecated":true,"description":"Deprecated: the old block of shipment facts (container, B/L, ports, vessel, dates), sent until 16 November 2026 and then removed. Read `shipment` and `details` instead."},"details":{"$ref":"#/components/schemas/RiskRaisedDetails"},"id":{"type":"string","format":"uuid","description":"Event id. The same in the X-Navlo-Event-Id header and on every retry of this delivery: dedup on it."},"occurredAt":{"type":"string","format":"date-time","description":"When Navlo queued the event (UTC)."},"shipment":{"$ref":"#/components/schemas/WebhookShipment"},"test":{"type":["boolean","null"],"description":"Present, and true, only on test events (Send test event / POST /v1/webhooks/{id}/test)."},"topic":{"type":"string","example":"shipment.risk_raised"}}},"WebhookEventRouteChanged":{"type":"object","description":"Payload of shipment.route_changed.","properties":{"data":{"type":["object","null"],"additionalProperties":{},"deprecated":true,"description":"Deprecated: the old block of shipment facts (container, B/L, ports, vessel, dates), sent until 16 November 2026 and then removed. Read `shipment` and `details` instead."},"details":{"$ref":"#/components/schemas/RouteChangedDetails"},"id":{"type":"string","format":"uuid","description":"Event id. The same in the X-Navlo-Event-Id header and on every retry of this delivery: dedup on it."},"occurredAt":{"type":"string","format":"date-time","description":"When Navlo queued the event (UTC)."},"shipment":{"$ref":"#/components/schemas/WebhookShipment"},"test":{"type":["boolean","null"],"description":"Present, and true, only on test events (Send test event / POST /v1/webhooks/{id}/test)."},"topic":{"type":"string","example":"shipment.route_changed"}}},"WebhookEventStatusChanged":{"type":"object","description":"Payload of shipment.status_changed.","properties":{"data":{"type":["object","null"],"additionalProperties":{},"deprecated":true,"description":"Deprecated: the old block of shipment facts (container, B/L, ports, vessel, dates), sent until 16 November 2026 and then removed. Read `shipment` and `details` instead."},"details":{"$ref":"#/components/schemas/StatusChangedDetails"},"id":{"type":"string","format":"uuid","description":"Event id. The same in the X-Navlo-Event-Id header and on every retry of this delivery: dedup on it."},"occurredAt":{"type":"string","format":"date-time","description":"When Navlo queued the event (UTC)."},"shipment":{"$ref":"#/components/schemas/WebhookShipment"},"test":{"type":["boolean","null"],"description":"Present, and true, only on test events (Send test event / POST /v1/webhooks/{id}/test)."},"topic":{"type":"string","example":"shipment.status_changed"}}},"WebhookMilestone":{"type":"object","properties":{"code":{"type":["string","null"],"description":"Navlo status code, or APPROACHING_DESTINATION / DEPARTURE_DETECTED / ARRIVAL_DETECTED.","example":"DEPARTED"},"name":{"type":"string","description":"The status as the timeline names it.","example":"Departed"}}},"WebhookPlace":{"type":"object","properties":{"code":{"type":["string","null"],"description":"UN/LOCODE (ocean) or IATA code (air), when known.","example":"CNSHA"},"name":{"type":["string","null"],"description":"Display name, when known.","example":"Shanghai"}}},"WebhookSecret":{"type":"object","description":"A new signing secret, shown once. Every delivery from now on is signed with it.","properties":{"secret":{"type":"string","example":"whsec_3f9a..."}}},"WebhookShipment":{"type":"object","description":"The shipment the event is about, as it stands when the event is queued. With several containers, origin, destination, eta, vessel and voyage are those of the first container still on its way.","properties":{"carrier":{"type":["string","null"],"description":"Carrier code, as in GET /v1/shipments/{id}. Null while unknown.","example":"MSC"},"customer":{"description":"The customer the shipment is assigned to, or null.","oneOf":[{"$ref":"#/components/schemas/CustomerRef"},{"type":"null"}]},"destination":{"description":"Port of discharge (ocean) or destination airport (air), when known.","oneOf":[{"$ref":"#/components/schemas/WebhookPlace"},{"type":"null"}]},"eta":{"type":["string","null"],"description":"The carrier's ETA at the destination (carrier local time, Z suffix), when known.","example":"2026-11-21T06:00:00Z"},"id":{"type":"string","description":"Navlo's shipment id, as in GET /v1/shipments/{id}.","example":"5e1c3a9b-0d2f-4f8e-9a61-3b7c2d4e5f60"},"identifier":{"type":"string","description":"The identifier the shipment was tracked with.","example":"MSCU7382154"},"mode":{"type":"string","description":"OCEAN or AIR.","example":"OCEAN"},"origin":{"description":"Port of loading (ocean) or origin airport (air), when known.","oneOf":[{"$ref":"#/components/schemas/WebhookPlace"},{"type":"null"}]},"status":{"type":"string","description":"Public status: discovering, resolving, active, completed or stopped.","example":"active"},"vessel":{"type":["string","null"],"description":"The vessel the cargo is on (ocean), when known.","example":"MSC ANNA"},"voyage":{"type":["string","null"],"description":"That vessel's voyage number (ocean), when known.","example":"FA442W"}}},"WebhookTestEvent":{"type":"object","description":"The queued test event. It arrives within a minute, signed like any other.","properties":{"eventId":{"type":"string","format":"uuid","description":"The event id the delivery carries (payload `id`, X-Navlo-Event-Id)."},"topic":{"type":"string","example":"shipment.status_changed"}}},"WebhookTestRequest":{"type":"object","properties":{"topic":{"type":["string","null"],"description":"Topic to imitate; default shipment.status_changed.","example":"shipment.eta_changed"}}},"WebhookTopicInfo":{"type":"object","properties":{"description":{"type":"string"},"topic":{"type":"string","example":"shipment.status_changed"}}}},"securitySchemes":{"ApiKeyAuth":{"description":"A REST key (nvl_…) created under Settings → API & Embedding.","in":"header","name":"X-API-Key","type":"apiKey"},"EmbedKeyAuth":{"description":"An embed key (nvle_…). Only valid on /api/embed/resolve.","in":"header","name":"X-Embed-Key","type":"apiKey"}}},"webhooks":{"shipment.completed":{"post":{"description":"The shipment finished its journey. Signed: X-Navlo-Signature: sha256=<hex HMAC-SHA256 of \"<X-Navlo-Timestamp>.<raw body>\"> with the endpoint's secret.","operationId":"webhookShipmentCompleted","requestBody":{"content":{"*/*":{"schema":{"$ref":"#/components/schemas/WebhookEventCompleted"}}}},"responses":{"200":{"description":"Any 2xx within 10 seconds acknowledges the delivery; anything else is retried after 1, 5, 20 and 60 minutes."}},"summary":"shipment.completed","tags":["Webhooks"]}},"shipment.discovery_finished":{"post":{"description":"The search for a newly added shipment ended: RESOLVED or NOT_FOUND. Signed: X-Navlo-Signature: sha256=<hex HMAC-SHA256 of \"<X-Navlo-Timestamp>.<raw body>\"> with the endpoint's secret.","operationId":"webhookShipmentDiscoveryFinished","requestBody":{"content":{"*/*":{"schema":{"$ref":"#/components/schemas/WebhookEventDiscoveryFinished"}}}},"responses":{"200":{"description":"Any 2xx within 10 seconds acknowledges the delivery; anything else is retried after 1, 5, 20 and 60 minutes."}},"summary":"shipment.discovery_finished","tags":["Webhooks"]}},"shipment.dnd":{"post":{"description":"Demurrage, detention or storage: free time ending or over, empty return due or done. Signed: X-Navlo-Signature: sha256=<hex HMAC-SHA256 of \"<X-Navlo-Timestamp>.<raw body>\"> with the endpoint's secret.","operationId":"webhookShipmentDnd","requestBody":{"content":{"*/*":{"schema":{"$ref":"#/components/schemas/WebhookEventDnd"}}}},"responses":{"200":{"description":"Any 2xx within 10 seconds acknowledges the delivery; anything else is retried after 1, 5, 20 and 60 minutes."}},"summary":"shipment.dnd","tags":["Webhooks"]}},"shipment.eta_changed":{"post":{"description":"The carrier's ETA moved. Signed: X-Navlo-Signature: sha256=<hex HMAC-SHA256 of \"<X-Navlo-Timestamp>.<raw body>\"> with the endpoint's secret.","operationId":"webhookShipmentEtaChanged","requestBody":{"content":{"*/*":{"schema":{"$ref":"#/components/schemas/WebhookEventEtaChanged"}}}},"responses":{"200":{"description":"Any 2xx within 10 seconds acknowledges the delivery; anything else is retried after 1, 5, 20 and 60 minutes."}},"summary":"shipment.eta_changed","tags":["Webhooks"]}},"shipment.risk_raised":{"post":{"description":"A risk was raised on the shipment. Signed: X-Navlo-Signature: sha256=<hex HMAC-SHA256 of \"<X-Navlo-Timestamp>.<raw body>\"> with the endpoint's secret.","operationId":"webhookShipmentRiskRaised","requestBody":{"content":{"*/*":{"schema":{"$ref":"#/components/schemas/WebhookEventRiskRaised"}}}},"responses":{"200":{"description":"Any 2xx within 10 seconds acknowledges the delivery; anything else is retried after 1, 5, 20 and 60 minutes."}},"summary":"shipment.risk_raised","tags":["Webhooks"]}},"shipment.route_changed":{"post":{"description":"The carrier changed the port of discharge. Signed: X-Navlo-Signature: sha256=<hex HMAC-SHA256 of \"<X-Navlo-Timestamp>.<raw body>\"> with the endpoint's secret.","operationId":"webhookShipmentRouteChanged","requestBody":{"content":{"*/*":{"schema":{"$ref":"#/components/schemas/WebhookEventRouteChanged"}}}},"responses":{"200":{"description":"Any 2xx within 10 seconds acknowledges the delivery; anything else is retried after 1, 5, 20 and 60 minutes."}},"summary":"shipment.route_changed","tags":["Webhooks"]}},"shipment.status_changed":{"post":{"description":"A new status on the timeline, a departure or arrival seen on the vessel's live position, or the shipment approaching its destination. Signed: X-Navlo-Signature: sha256=<hex HMAC-SHA256 of \"<X-Navlo-Timestamp>.<raw body>\"> with the endpoint's secret.","operationId":"webhookShipmentStatusChanged","requestBody":{"content":{"*/*":{"schema":{"$ref":"#/components/schemas/WebhookEventStatusChanged"}}}},"responses":{"200":{"description":"Any 2xx within 10 seconds acknowledges the delivery; anything else is retried after 1, 5, 20 and 60 minutes."}},"summary":"shipment.status_changed","tags":["Webhooks"]}}}}