{
  "schemaVersion": 1,
  "title": "Navlo API",
  "apiVersion": "v1",
  "updatedAt": "2026-10-22",
  "baseUrl": "https://api.navlo.io",
  "openApiUrl": "https://api.navlo.io/v1/openapi.json",
  "postmanUrl": "https://app.navlo.io/developers/navlo-api.postman_collection.json",
  "labels": {
    "auth": {
      "apiKey": "X-API-Key",
      "embedKey": "X-Embed-Key (embed key)",
      "none": "None"
    },
    "rateLimit": {
      "general": "60 / min per key",
      "ai": "10 / min per key",
      "none": "None per key"
    },
    "httpStatus": {
      "200": "OK",
      "201": "Created",
      "202": "Accepted",
      "204": "No Content",
      "302": "Found",
      "400": "Bad Request",
      "401": "Unauthorized",
      "402": "Payment Required",
      "403": "Forbidden",
      "404": "Not Found",
      "409": "Conflict",
      "410": "Gone",
      "413": "Payload Too Large",
      "422": "Unprocessable Entity",
      "429": "Too Many Requests",
      "500": "Internal Server Error",
      "503": "Service Unavailable",
      "504": "Gateway Timeout"
    }
  },
  "sections": [
    {
      "id": "get-started",
      "title": "Get started",
      "pages": [
        {
          "id": "quick-start",
          "title": "Quick start",
          "summary": "From a new API key to a tracked shipment and your first webhook in about five minutes.",
          "blocks": [
            {
              "kind": "prose",
              "text": "The Navlo API lets your systems do what your team does in the app: start tracking ocean and air shipments, read every milestone, ETA and risk signal Navlo has, put shipments on your own customers, ask Navlo AI, and get each change pushed to you. Most examples in these docs use the same demo shipment — container `MEDU1234562`, shipped for the customer Acme Trading Ltd. (`C-1042`) — so you can follow one shipment from the first request to the usage report; webhook payloads are exactly what your endpoint receives."
            },
            {
              "kind": "definitions",
              "items": [
                {
                  "term": "Base URL",
                  "description": "`https://api.navlo.io`"
                },
                {
                  "term": "Format",
                  "description": "JSON over HTTPS, UTF-8, camelCase field names"
                },
                {
                  "term": "Authentication",
                  "description": "`X-API-Key: nvl_…` header on every request"
                },
                {
                  "term": "Version",
                  "description": "`/v1` — changes are additive only ([Compatibility promise](/developers/compatibility))"
                },
                {
                  "term": "Machine-readable",
                  "description": "[OpenAPI 3 document](/developers/openapi-and-postman) and a Postman collection"
                }
              ]
            },
            {
              "kind": "heading",
              "id": "quick-start-key",
              "title": "1. Create an API key"
            },
            {
              "kind": "list",
              "ordered": true,
              "items": [
                "In the Navlo app, open **Settings → API & Embedding** and choose **New key**.",
                "Name it after the system that will use it (for example \"ERP integration\") and pick the **REST API** scope.",
                "Copy the key. It starts with `nvl_` and is shown only once — store it in your secret manager."
              ]
            },
            {
              "kind": "callout",
              "tone": "info",
              "text": "Only organization admins can create keys. A request acts as the admin who created the key: shipments appear in the app under their name and use your organization’s credits. Details in [Authentication](/developers/authentication)."
            },
            {
              "kind": "code",
              "samples": [
                {
                  "lang": "curl",
                  "label": "Shell",
                  "code": "export NAVLO_API_KEY=\"nvl_…\"   # the key you just copied"
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "// Keep the key in .env (NAVLO_API_KEY=nvl_…) and start with: node --env-file=.env app.mjs  (Node 20.6+)\nconst apiKey = process.env.NAVLO_API_KEY"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "# shell: export NAVLO_API_KEY=\"nvl_…\"\nimport os\napi_key = os.environ[\"NAVLO_API_KEY\"]"
                }
              ]
            },
            {
              "kind": "heading",
              "id": "quick-start-first-call",
              "title": "2. Check the key works"
            },
            {
              "kind": "prose",
              "text": "`GET /v1/credits` is a safe first call: it changes nothing and returns the balances your requests draw from."
            },
            {
              "kind": "code",
              "title": "Request",
              "samples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl \"https://api.navlo.io/v1/credits\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\""
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const res = await fetch('https://api.navlo.io/v1/credits', {\n  headers: { 'X-API-Key': process.env.NAVLO_API_KEY },\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\nconst credits = await res.json()"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.get(\n    \"https://api.navlo.io/v1/credits\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\ncredits = r.json()"
                }
              ]
            },
            {
              "kind": "code",
              "title": "Response",
              "samples": [
                {
                  "lang": "json",
                  "label": "200 OK",
                  "code": "{\n  \"trackingCredits\": 248,\n  \"aiCredits\": 14.3725\n}"
                }
              ]
            },
            {
              "kind": "heading",
              "id": "quick-start-track",
              "title": "3. Start tracking a shipment"
            },
            {
              "kind": "prose",
              "text": "Send the container, Master B/L, booking or Master AWB number with its mode. Add `customer` to put the shipment on one of your own customers — the first time Navlo sees a reference it creates that customer for you, so your billing codes work from day one."
            },
            {
              "kind": "code",
              "title": "Request",
              "samples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl -X POST \"https://api.navlo.io/v1/shipments\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"identifier\": \"MEDU1234562\",\n    \"mode\": \"OCEAN\",\n    \"carrier\": \"MSC\",\n    \"customer\": {\n      \"ref\": \"C-1042\",\n      \"name\": \"Acme Trading Ltd.\"\n    }\n  }'"
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const res = await fetch('https://api.navlo.io/v1/shipments', {\n  method: 'POST',\n  headers: {\n    'X-API-Key': process.env.NAVLO_API_KEY,\n    'Content-Type': 'application/json',\n  },\n  body: JSON.stringify({\n    identifier: 'MEDU1234562',\n    mode: 'OCEAN',\n    carrier: 'MSC',\n    customer: { ref: 'C-1042', name: 'Acme Trading Ltd.' },\n  }),\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\nconst shipment = await res.json()"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.post(\n    \"https://api.navlo.io/v1/shipments\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    json={\n        \"identifier\": \"MEDU1234562\",\n        \"mode\": \"OCEAN\",\n        \"carrier\": \"MSC\",\n        \"customer\": {\"ref\": \"C-1042\", \"name\": \"Acme Trading Ltd.\"},\n    },\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\nshipment = r.json()"
                }
              ]
            },
            {
              "kind": "code",
              "title": "Response",
              "samples": [
                {
                  "lang": "json",
                  "label": "201 Created",
                  "code": "{\n  \"id\": \"8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07\",\n  \"identifier\": \"MEDU1234562\",\n  \"mode\": \"OCEAN\",\n  \"status\": \"discovering\",\n  \"carrier\": \"MSC\",\n  \"createdAt\": \"2026-09-24T07:41:18Z\"\n}"
                }
              ]
            },
            {
              "kind": "callout",
              "tone": "tip",
              "text": "Posting an identifier your organization already tracks returns the existing shipment — no duplicate and no second charge — so retrying a create after a timeout is always safe."
            },
            {
              "kind": "heading",
              "id": "quick-start-read",
              "title": "4. Read the shipment"
            },
            {
              "kind": "prose",
              "text": "The status starts as `discovering` (`tracking` for air) while Navlo finds the carrier and pulls the first data — usually within minutes — and becomes `active` once carrier data arrives. Ask for Navlo’s own intelligence with `include`:"
            },
            {
              "kind": "code",
              "title": "Request",
              "samples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl \"https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07?include=risk,navloEta,customer\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\""
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const params = new URLSearchParams({ include: 'risk,navloEta,customer' })\n\nconst res = await fetch(`https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07?${params}`, {\n  headers: { 'X-API-Key': process.env.NAVLO_API_KEY },\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\nconst shipment = await res.json()"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.get(\n    \"https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    params={\"include\": \"risk,navloEta,customer\"},\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\nshipment = r.json()"
                }
              ]
            },
            {
              "kind": "code",
              "title": "Response",
              "samples": [
                {
                  "lang": "json",
                  "label": "200 OK",
                  "code": "{\n  \"id\": \"8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07\",\n  \"identifier\": \"MEDU1234562\",\n  \"mode\": \"OCEAN\",\n  \"status\": \"active\",\n  \"carrier\": \"MSC\",\n  \"containers\": [\n    {\n      \"containerNumber\": \"MEDU1234562\",\n      \"containerType\": \"40HC\",\n      \"status\": \"DEPARTED\",\n      \"etd\": \"2026-09-26T22:00:00Z\",\n      \"atd\": \"2026-09-27T03:40:00Z\",\n      \"eta\": \"2026-10-30T06:00:00Z\",\n      \"ata\": null,\n      \"origin\": {\n        \"code\": \"CNSHA\",\n        \"name\": \"Shanghai\"\n      },\n      \"destination\": {\n        \"code\": \"TRAMR\",\n        \"name\": \"Ambarli\"\n      },\n      \"currentVessel\": \"MSC MARTINA\"\n    }\n  ],\n  \"airShipments\": [],\n  \"events\": [\n    {\n      \"timestamp\": \"2026-09-24T14:12:00Z\",\n      \"type\": \"ACTUAL\",\n      \"status\": \"GATE_IN\",\n      \"location\": \"Shanghai\",\n      \"locationCode\": \"CNSHA\",\n      \"vessel\": null,\n      \"voyage\": null,\n      \"flight\": null,\n      \"pieces\": null,\n      \"weight\": null\n    },\n    {\n      \"timestamp\": \"2026-09-26T21:30:00Z\",\n      \"type\": \"ACTUAL\",\n      \"status\": \"LOADED\",\n      \"location\": \"Shanghai\",\n      \"locationCode\": \"CNSHA\",\n      \"vessel\": \"MSC MARTINA\",\n      \"voyage\": \"438W\",\n      \"flight\": null,\n      \"pieces\": null,\n      \"weight\": null\n    },\n    {\n      \"timestamp\": \"2026-09-27T03:40:00Z\",\n      \"type\": \"ACTUAL\",\n      \"status\": \"DEPARTED\",\n      \"location\": \"Shanghai\",\n      \"locationCode\": \"CNSHA\",\n      \"vessel\": \"MSC MARTINA\",\n      \"voyage\": \"438W\",\n      \"flight\": null,\n      \"pieces\": null,\n      \"weight\": null\n    },\n    {\n      \"timestamp\": \"2026-10-23T08:00:00Z\",\n      \"type\": \"EXPECTED\",\n      \"status\": \"TRANSSHIPMENT\",\n      \"location\": \"Piraeus\",\n      \"locationCode\": \"GRPIR\",\n      \"vessel\": \"MSC MARTINA\",\n      \"voyage\": \"438W\",\n      \"flight\": null,\n      \"pieces\": null,\n      \"weight\": null\n    },\n    {\n      \"timestamp\": \"2026-10-27T18:00:00Z\",\n      \"type\": \"EXPECTED\",\n      \"status\": \"DEPARTED\",\n      \"location\": \"Piraeus\",\n      \"locationCode\": \"GRPIR\",\n      \"vessel\": \"MSC ARIANE\",\n      \"voyage\": \"IP243A\",\n      \"flight\": null,\n      \"pieces\": null,\n      \"weight\": null\n    },\n    {\n      \"timestamp\": \"2026-10-30T06:00:00Z\",\n      \"type\": \"EXPECTED\",\n      \"status\": \"ARRIVED\",\n      \"location\": \"Ambarli\",\n      \"locationCode\": \"TRAMR\",\n      \"vessel\": \"MSC ARIANE\",\n      \"voyage\": \"IP243A\",\n      \"flight\": null,\n      \"pieces\": null,\n      \"weight\": null\n    }\n  ],\n  \"etaHistory\": [\n    {\n      \"field\": \"ETA\",\n      \"previousValue\": \"2026-10-27T06:00:00Z\",\n      \"newValue\": \"2026-10-30T06:00:00Z\",\n      \"deltaHours\": 72,\n      \"recordedAt\": \"2026-10-14T09:22:14Z\",\n      \"containerNumber\": \"MEDU1234562\",\n      \"awbNumber\": null\n    },\n    {\n      \"field\": \"ETA\",\n      \"previousValue\": \"2026-10-25T06:00:00Z\",\n      \"newValue\": \"2026-10-27T06:00:00Z\",\n      \"deltaHours\": 48,\n      \"recordedAt\": \"2026-10-03T11:05:39Z\",\n      \"containerNumber\": \"MEDU1234562\",\n      \"awbNumber\": null\n    }\n  ],\n  \"vessel\": {\n    \"vesselName\": \"MSC MARTINA\",\n    \"latitude\": 34.9123,\n    \"longitude\": 25.6342,\n    \"heading\": 318,\n    \"source\": \"LIVE\",\n    \"reportedAt\": \"2026-10-22T05:41:00Z\"\n  },\n  \"risk\": {\n    \"level\": \"MEDIUM\",\n    \"score\": 52,\n    \"summary\": \"ETA slipped 5 days since departure; the Piraeus transshipment is congested.\",\n    \"computedAt\": \"2026-10-22T07:15:00Z\",\n    \"stale\": false\n  },\n  \"navloEta\": [\n    {\n      \"containerNumber\": \"MEDU1234562\",\n      \"predictedEta\": \"2026-10-31T02:00:00Z\",\n      \"confidence\": \"MEDIUM\",\n      \"computedAt\": \"2026-10-22T05:42:19Z\",\n      \"carrierEta\": \"2026-10-30T06:00:00Z\"\n    }\n  ],\n  \"customer\": {\n    \"id\": \"c7d2a9e4-3f1b-4e8a-9b6c-1d5e7f3a2b90\",\n    \"ref\": \"C-1042\",\n    \"name\": \"Acme Trading Ltd.\",\n    \"countryCode\": \"TR\"\n  }\n}"
                }
              ]
            },
            {
              "kind": "heading",
              "id": "quick-start-webhook",
              "title": "5. Get changes pushed to you"
            },
            {
              "kind": "prose",
              "text": "Instead of polling, register an HTTPS endpoint. Navlo POSTs a signed JSON event for every status change, ETA move, risk, D&D warning and route change on your shipments. Leaving `topics` out subscribes the endpoint to every topic, including ones added later."
            },
            {
              "kind": "code",
              "title": "Request",
              "samples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl -X POST \"https://api.navlo.io/v1/webhooks\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"name\": \"ERP shipment updates\",\n    \"url\": \"https://erp.example.com/webhooks/navlo\"\n  }'"
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const res = await fetch('https://api.navlo.io/v1/webhooks', {\n  method: 'POST',\n  headers: {\n    'X-API-Key': process.env.NAVLO_API_KEY,\n    'Content-Type': 'application/json',\n  },\n  body: JSON.stringify({\n    name: 'ERP shipment updates',\n    url: 'https://erp.example.com/webhooks/navlo',\n  }),\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\nconst webhook = await res.json()"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.post(\n    \"https://api.navlo.io/v1/webhooks\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    json={\n        \"name\": \"ERP shipment updates\",\n        \"url\": \"https://erp.example.com/webhooks/navlo\",\n    },\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\nwebhook = r.json()"
                }
              ]
            },
            {
              "kind": "code",
              "title": "Response",
              "samples": [
                {
                  "lang": "json",
                  "label": "201 Created",
                  "code": "{\n  \"id\": \"2b7e9c41-6d3a-4f8e-a5c1-9e0d7b3f2a68\",\n  \"name\": \"ERP shipment updates\",\n  \"url\": \"https://erp.example.com/webhooks/navlo\",\n  \"topics\": [],\n  \"active\": true,\n  \"disabledReason\": null,\n  \"consecutiveFailures\": 0,\n  \"lastSuccessAt\": null,\n  \"lastFailureAt\": null,\n  \"createdAt\": \"2026-10-22T08:15:00Z\",\n  \"secret\": \"whsec_7d1f9a3c5e8b2d4f6a0c1e3b5d7f9a2c4e6b8d0f1a3c5e7b9d2f4a6c8e0b1d3f\"\n}"
                }
              ]
            },
            {
              "kind": "prose",
              "text": "Store `secret` — it is shown only here and when you rotate it — and check every delivery’s signature with it before trusting the body: [Verifying signatures](/developers/webhooks#webhooks-signatures). To see a real payload right away, [send a test event](/developers/webhooks#webhooks-test)."
            },
            {
              "kind": "heading",
              "id": "quick-start-next",
              "title": "Next steps"
            },
            {
              "kind": "list",
              "ordered": false,
              "items": [
                "[Shipments](/developers/shipments) — filters, `updatedSince` sync, batch create, customer assignment.",
                "[Shipment intelligence](/developers/shipment-intelligence) — risk, Navlo ETA, D&D, carbon, recommendations, route alerts.",
                "[Usage & credits](/developers/usage-and-credits) — re-bill your own customers from Navlo’s usage report.",
                "[Navlo AI](/developers/navlo-ai) — ask questions about your shipments over the API, streamed.",
                "[Embed](/developers/embed) — put live tracking on your own website.",
                "[Errors](/developers/errors) and [Rate limits](/developers/rate-limits) — build a client that behaves under failure."
              ]
            }
          ]
        },
        {
          "id": "authentication",
          "title": "Authentication",
          "summary": "Every request carries a REST API key in the `X-API-Key` header — no OAuth, no tokens to refresh.",
          "blocks": [
            {
              "kind": "prose",
              "text": "Send your key in the `X-API-Key` header on every request to `https://api.navlo.io/v1/…`. The key is the credential: there is no login call and nothing expires on its own."
            },
            {
              "kind": "code",
              "title": "Request",
              "samples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl \"https://api.navlo.io/v1/shipments?size=1\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\""
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const params = new URLSearchParams({ size: '1' })\n\nconst res = await fetch(`https://api.navlo.io/v1/shipments?${params}`, {\n  headers: { 'X-API-Key': process.env.NAVLO_API_KEY },\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\nconst page = await res.json()"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.get(\n    \"https://api.navlo.io/v1/shipments\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    params={\"size\": \"1\"},\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\npage = r.json()"
                }
              ]
            },
            {
              "kind": "heading",
              "id": "auth-key-types",
              "title": "Key types"
            },
            {
              "kind": "table",
              "columns": [
                "Key",
                "Starts with",
                "Works on",
                "Keep it"
              ],
              "rows": [
                [
                  "REST API",
                  "`nvl_`",
                  "All `/v1` endpoints",
                  "Servers only"
                ],
                [
                  "Embed",
                  "`nvle_`",
                  "Widget, `/api/embed/resolve`",
                  "Web pages"
                ]
              ]
            },
            {
              "kind": "prose",
              "text": "Both are created under **Settings → API & Embedding** by an organization admin, and both are shown in full only once, at creation. An embed key sent to a `/v1` endpoint is rejected with `401`."
            },
            {
              "kind": "heading",
              "id": "auth-acting-user",
              "title": "Who a request acts as"
            },
            {
              "kind": "list",
              "ordered": false,
              "items": [
                "A key belongs to your organization and acts as the person who created it. Shipments, notes and Navlo AI conversations created through the API show that person as the author in the app, and Navlo AI conversations appear in their Navlo AI list.",
                "Credits come from the balance that person uses in the app. Keys are created by organization admins, whose balance is the organization’s pool.",
                "Everything is scoped to your organization. An id that belongs to another organization behaves exactly like one that doesn’t exist: `404`.",
                "Admin-only operations — managing webhooks, deleting tags — work while the key’s creator is an organization admin, and answer `403` otherwise."
              ]
            },
            {
              "kind": "heading",
              "id": "auth-rotation",
              "title": "Rotating and revoking keys"
            },
            {
              "kind": "list",
              "ordered": false,
              "items": [
                "To rotate, create the new key, deploy it, then revoke the old one under **Settings → API & Embedding**. A revoked key fails on its very next request.",
                "A key works only while the person who created it is an active member of your organization: if they leave or their account is deactivated, it answers `401 Invalid or revoked API key` (and works again if they are reactivated). Create the replacement as another admin.",
                "The key list shows each key’s prefix, who created it and when it was last used, so unused keys are easy to find and revoke.",
                "An organization can have at most 10 live keys, REST and embed together."
              ]
            },
            {
              "kind": "callout",
              "tone": "warning",
              "title": "Treat the key like a password",
              "text": "Keep REST keys on your servers. Anyone holding one can start shipments on your credits and read every shipment in your organization. Never ship an `nvl_` key in browser JavaScript or a mobile app — the [embed key](/developers/embed) exists for that."
            },
            {
              "kind": "heading",
              "id": "auth-errors",
              "title": "Authentication errors"
            },
            {
              "kind": "definitions",
              "items": [
                {
                  "term": "`401` `Invalid or revoked API key`",
                  "description": "The header is missing, the key is mistyped or revoked, its creator is no longer an active member, or an embed key was sent to `/v1`."
                },
                {
                  "term": "`401` `API key owner no longer exists`",
                  "description": "The person who created the key was removed from your organization."
                },
                {
                  "term": "`403` (message per operation)",
                  "description": "The key works, but its creator may not do this — for example, they are not an admin."
                }
              ]
            },
            {
              "kind": "prose",
              "text": "Only `GET /v1/openapi.json`, the machine-readable reference, answers without a key."
            }
          ]
        },
        {
          "id": "errors",
          "title": "Errors",
          "summary": "Standard HTTP status codes, and a JSON body whose `message` always explains what went wrong.",
          "blocks": [
            {
              "kind": "prose",
              "text": "Navlo answers every failed request with an HTTP status code and a JSON body carrying a human-readable `message`. Read `message` — in every shape the API can return — and you will never lose an explanation."
            },
            {
              "kind": "heading",
              "id": "errors-shape",
              "title": "Error body"
            },
            {
              "kind": "code",
              "samples": [
                {
                  "lang": "json",
                  "label": "404 Not Found",
                  "code": "{\n  \"error\": \"Shipment not found\",\n  \"message\": \"Shipment not found\"\n}"
                }
              ]
            },
            {
              "kind": "prose",
              "text": "`error` and `message` carry the same text. `error` stays because integrations built before 2026-10-22 read it; new code should read `message`."
            },
            {
              "kind": "prose",
              "text": "A few errors — an unexpected server error, a malformed path parameter, or insufficient credits on the original shipment endpoints — use a second shape. It has `message` too:"
            },
            {
              "kind": "code",
              "samples": [
                {
                  "lang": "json",
                  "label": "402 Payment Required",
                  "code": "{\n  \"timestamp\": \"2026-10-22T09:14:03.512\",\n  \"status\": 402,\n  \"error\": \"Payment Required\",\n  \"message\": \"Insufficient credits. Required: 1.00, Available: 0.00\",\n  \"path\": null\n}"
                }
              ]
            },
            {
              "kind": "callout",
              "tone": "warning",
              "text": "In this second shape `error` is the HTTP reason phrase (\"Payment Required\"), not the explanation. Always show or log `message`."
            },
            {
              "kind": "prose",
              "text": "The embed endpoint, `GET /api/embed/resolve`, answers errors with an empty body: branch on the status code there."
            },
            {
              "kind": "heading",
              "id": "errors-status-codes",
              "title": "Status codes"
            },
            {
              "kind": "definitions",
              "items": [
                {
                  "term": "`200` `201` `202` `204`",
                  "description": "Success."
                },
                {
                  "term": "`400` Bad Request",
                  "description": "The request is invalid. Fix it — `message` names the field. Don’t retry it unchanged."
                },
                {
                  "term": "`401` Unauthorized",
                  "description": "Missing, invalid or revoked key. Check the key; don’t retry."
                },
                {
                  "term": "`402` Payment Required",
                  "description": "Not enough credits. Top up or transfer credits, then retry."
                },
                {
                  "term": "`403` Forbidden",
                  "description": "The key’s creator lacks the permission for this operation."
                },
                {
                  "term": "`404` Not Found",
                  "description": "No such resource in your organization (another organization’s ids read the same). Check the id."
                },
                {
                  "term": "`409` Conflict",
                  "description": "The request conflicts with the current state — e.g. the carrier was already changed once. Read `message`."
                },
                {
                  "term": "`410` Gone",
                  "description": "The resource expired; create it again."
                },
                {
                  "term": "`429` Too Many Requests",
                  "description": "Rate limit reached. Wait `Retry-After` seconds, then retry."
                },
                {
                  "term": "`500` Internal Server Error",
                  "description": "Unexpected error on Navlo’s side. Retry with backoff; contact support if it persists."
                },
                {
                  "term": "`503` Service Unavailable",
                  "description": "Temporarily unavailable (e.g. Navlo AI busy). Retry with backoff."
                }
              ]
            },
            {
              "kind": "heading",
              "id": "errors-retries",
              "title": "Retrying safely"
            },
            {
              "kind": "list",
              "ordered": false,
              "items": [
                "Retry `429`, `500`, `502`, `503`, `504` and network errors with exponential backoff, honouring `Retry-After` when present. Never retry any other 4xx unchanged.",
                "`POST /v1/shipments` and every batch item are idempotent per identifier: retrying a create that timed out never creates a duplicate or charges twice.",
                "Stop, resume, mute, complete, share link, archive and restore are idempotent too. Creating a note, uploading a document or adding a subscriber is not — check before retrying those."
              ]
            },
            {
              "kind": "code",
              "title": "A small client with retries",
              "samples": [
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const BASE = 'https://api.navlo.io'\n\n// Retries 429 / 5xx with Retry-After or exponential backoff; throws with Navlo's message otherwise.\nexport async function navlo(path, { method = 'GET', body, retries = 3 } = {}) {\n  for (let attempt = 0; ; attempt++) {\n    const res = await fetch(`${BASE}${path}`, {\n      method,\n      headers: {\n        'X-API-Key': process.env.NAVLO_API_KEY,\n        ...(body ? { 'Content-Type': 'application/json' } : {}),\n      },\n      body: body ? JSON.stringify(body) : undefined,\n    })\n    if ((res.status === 429 || res.status >= 500) && attempt < retries) {\n      const waitSeconds = Number(res.headers.get('Retry-After')) || 2 ** attempt\n      await new Promise((resolve) => setTimeout(resolve, waitSeconds * 1000))\n      continue\n    }\n    if (res.status === 204) return null\n    const data = await res.json()\n    if (!res.ok) throw new Error(`Navlo ${res.status}: ${data.message}`)\n    return data\n  }\n}\n\nconst shipment = await navlo('/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07')"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport time\nimport requests\n\nBASE = \"https://api.navlo.io\"\nsession = requests.Session()\nsession.headers[\"X-API-Key\"] = os.environ[\"NAVLO_API_KEY\"]\n\n\ndef navlo(method, path, retries=3, **kwargs):\n    \"\"\"Retries 429 / 5xx with Retry-After or exponential backoff; raises with Navlo's message otherwise.\"\"\"\n    for attempt in range(retries + 1):\n        r = session.request(method, BASE + path, timeout=30, **kwargs)\n        if (r.status_code == 429 or r.status_code >= 500) and attempt < retries:\n            time.sleep(float(r.headers.get(\"Retry-After\") or 2 ** attempt))\n            continue\n        if r.status_code == 204:\n            return None\n        data = r.json()\n        if not r.ok:\n            raise RuntimeError(f\"Navlo {r.status_code}: {data['message']}\")\n        return data\n\n\nshipment = navlo(\"GET\", \"/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07\")"
                }
              ]
            }
          ]
        },
        {
          "id": "rate-limits",
          "title": "Rate limits",
          "summary": "60 requests a minute per key, 10 a minute for Navlo AI, plus a few caps per organization — with headers that tell you where you stand.",
          "blocks": [
            {
              "kind": "prose",
              "text": "Limits apply per API key, per minute. Every response tells you how much of the current window is left and when it resets. Request bodies are capped at 1 MB (uploads: 10 MB); a larger one answers `413`."
            },
            {
              "kind": "definitions",
              "items": [
                {
                  "term": "General — 60 / minute",
                  "description": "Every `/v1` endpoint except Navlo AI."
                },
                {
                  "term": "Navlo AI — 10 / minute",
                  "description": "Paths under `/v1/ai/`."
                },
                {
                  "term": "Tracking widget — 60 / minute",
                  "description": "Lookups per [embed key](/developers/embed)."
                }
              ]
            },
            {
              "kind": "prose",
              "text": "The buckets are independent: a burst of Navlo AI questions never slows your tracking sync, and a backfill never blocks Navlo AI."
            },
            {
              "kind": "heading",
              "id": "rate-limits-organization",
              "title": "Caps per organization"
            },
            {
              "kind": "definitions",
              "items": [
                {
                  "term": "API keys — 10 live",
                  "description": "REST and embed keys together. Revoke one you no longer use before creating another."
                },
                {
                  "term": "Navlo AI — 2 answers at once",
                  "description": "A question sent while two are still being answered gets `429` and nothing is stored; send it when one finishes."
                },
                {
                  "term": "Share emails — 500 recipients / 24 hours",
                  "description": "App and API together ([subscribers](/developers/shipment-actions#actions-subscribers)). A request that would go over answers `429` and emails nobody."
                }
              ]
            },
            {
              "kind": "heading",
              "id": "rate-limits-headers",
              "title": "Headers on every response"
            },
            {
              "kind": "table",
              "columns": [
                "Header",
                "Meaning"
              ],
              "rows": [
                [
                  "`X-RateLimit-Limit`",
                  "The bucket’s limit per minute (60 or 10)"
                ],
                [
                  "`X-RateLimit-Remaining`",
                  "Requests left in the current window"
                ],
                [
                  "`X-RateLimit-Reset`",
                  "Unix time, in seconds, when the window resets"
                ],
                [
                  "`Retry-After`",
                  "Only on `429`: seconds to wait before retrying"
                ]
              ]
            },
            {
              "kind": "heading",
              "id": "rate-limits-429",
              "title": "When you hit the limit"
            },
            {
              "kind": "code",
              "samples": [
                {
                  "lang": "http",
                  "label": "Response",
                  "code": "HTTP/1.1 429 Too Many Requests\nContent-Type: application/json\nX-RateLimit-Limit: 60\nX-RateLimit-Remaining: 0\nX-RateLimit-Reset: 1792656960\nRetry-After: 23\n\n{\"error\":\"Rate limit exceeded (60 requests/minute)\",\"message\":\"Rate limit exceeded (60 requests/minute)\"}"
                }
              ]
            },
            {
              "kind": "prose",
              "text": "Wait the `Retry-After` seconds and send the request again. The [client on the Errors page](/developers/errors#errors-retries) does this for you."
            },
            {
              "kind": "heading",
              "id": "rate-limits-tips",
              "title": "Staying well under the limit"
            },
            {
              "kind": "list",
              "ordered": false,
              "items": [
                "Use [webhooks](/developers/webhooks) instead of polling every shipment: each change reaches you once, when it happens.",
                "If you poll, poll the list with `updatedSince` — one request returns every shipment that changed since your last sync ([how](/developers/shipments#shipments-sync)).",
                "Start many shipments with `POST /v1/shipments/batch`: up to 50 per request, counted as one request.",
                "A streamed Navlo AI answer counts once, however long it streams.",
                "Webhook deliveries and the embed widget never count against your key.",
                "Need a higher limit for a backfill? Write to support@navlo.io with the volume and the window."
              ]
            }
          ]
        },
        {
          "id": "compatibility",
          "title": "Compatibility promise",
          "summary": "What stays stable on `/v1`, and the three habits that keep your integration working as the API grows.",
          "blocks": [
            {
              "kind": "prose",
              "text": "An integration built on `/v1` keeps working. This is what Navlo commits to — and what your code should do so a new field or value never breaks it."
            },
            {
              "kind": "heading",
              "id": "compatibility-promise",
              "title": "What Navlo promises"
            },
            {
              "kind": "list",
              "ordered": false,
              "items": [
                "**`/v1` stays.** Documented paths, parameters and response fields are not removed or renamed, and their types don’t change.",
                "**Changes are additive.** New endpoints, optional parameters, response fields, webhook topics and enum values can appear at any time without notice.",
                "**New data is opt-in.** Richer shipment data arrives through `include=`; a request without it returns exactly what it returned before.",
                "**Breaking changes get a new version.** Anything that must change incompatibly ships as `/v2`, announced in the [Changelog](/developers/changelog) with time to migrate. `/v1` keeps running alongside it."
              ]
            },
            {
              "kind": "heading",
              "id": "compatibility-your-side",
              "title": "What your code should do"
            },
            {
              "kind": "list",
              "ordered": false,
              "items": [
                "Ignore JSON fields you don’t recognise; never fail on them. Configure strict deserialisers to allow unknown properties.",
                "Handle enum values you don’t recognise — statuses, milestone codes, recommendation kinds, alert types — with a generic fallback.",
                "Acknowledge webhook topics you didn’t expect with `2xx`: an endpoint without `topics` also receives topics added later.",
                "Don’t depend on the order of object keys, or of list items unless a field documents its order.",
                "Read error explanations from `message`."
              ]
            },
            {
              "kind": "heading",
              "id": "compatibility-legacy",
              "title": "Kept for compatibility"
            },
            {
              "kind": "list",
              "ordered": false,
              "items": [
                "`error` in error bodies — the same text as `message`.",
                "The original shipment endpoints answer exactly as before when you send no new parameters: same fields, same order, same status codes."
              ]
            }
          ]
        }
      ]
    },
    {
      "id": "shipments-group",
      "title": "Shipments",
      "pages": [
        {
          "id": "shipments",
          "title": "Shipments",
          "summary": "Start tracking ocean containers, B/Ls, bookings and air waybills, then list, read, update, pause and delete them.",
          "blocks": [
            {
              "kind": "prose",
              "text": "A shipment is one identifier you asked Navlo to track. Navlo finds the carrier, pulls the data and keeps it current on its own polling schedule; you read the result here or get it pushed through [webhooks](/developers/webhooks)."
            },
            {
              "kind": "heading",
              "id": "shipments-identifiers",
              "title": "What you can track"
            },
            {
              "kind": "table",
              "columns": [
                "Identifier",
                "Mode",
                "Example"
              ],
              "rows": [
                [
                  "Container number (ISO 6346)",
                  "`OCEAN`",
                  "`MEDU1234562`"
                ],
                [
                  "Master bill of lading",
                  "`OCEAN`",
                  "`MEDUSH448021`"
                ],
                [
                  "Booking number",
                  "`OCEAN`",
                  "`177SHA2611987`"
                ],
                [
                  "Master air waybill (MAWB)",
                  "`AIR`",
                  "`871-12345675` (dash optional)"
                ]
              ]
            },
            {
              "kind": "prose",
              "text": "A B/L or booking with several containers becomes one shipment with several `containers`. House B/Ls and house AWBs are not supported — send the master document."
            },
            {
              "kind": "heading",
              "id": "shipments-customer-input",
              "title": "Putting a shipment on a customer"
            },
            {
              "kind": "prose",
              "text": "Shipments, batch items, Navlo AI questions and vessel follows accept a `customer` object, so every credit you spend is attributed to one of your customers in the [usage report](/developers/usage-and-credits). Send either Navlo’s id or your own reference:"
            },
            {
              "kind": "code",
              "samples": [
                {
                  "lang": "json",
                  "label": "By your reference",
                  "code": "{\n  \"customer\": {\n    \"ref\": \"C-1042\",\n    \"name\": \"Acme Trading Ltd.\"\n  }\n}"
                },
                {
                  "lang": "json",
                  "label": "By Navlo id",
                  "code": "{\n  \"customer\": {\n    \"id\": \"c7d2a9e4-3f1b-4e8a-9b6c-1d5e7f3a2b90\"\n  }\n}"
                }
              ]
            },
            {
              "kind": "list",
              "ordered": false,
              "items": [
                "`id` — one of your customers. Unknown → `400 Unknown customer id`, unless you also sent a `ref`.",
                "`ref` — your own code (max 100 characters; matched case-insensitively and trimmed). The customer with that ref is used. An unknown ref creates a new customer named `name` (or the ref, without a name) — or, when a customer of that name already exists without a reference, gives it this ref. A same-named customer that already has another reference is refused: `400 A customer named \"Acme Trading Ltd.\" already exists with the reference \"C-9\"`. Existing customers are never renamed this way.",
                "Both `id` and `ref`: `id` wins when it exists; an unknown `id` falls back to the `ref`.",
                "An empty object is rejected (`400 customer needs an id or a ref`), and an archived customer can’t take shipments (`400 \"Acme Trading Ltd.\" is archived. Restore it before assigning shipments.`). All of this is checked before anything is created or charged."
              ]
            },
            {
              "kind": "prose",
              "text": "Customers are the companies on the app’s **Companies** page; manage them with the [Customers API](/developers/customers)."
            },
            {
              "kind": "endpoint",
              "id": "shipments-create",
              "method": "POST",
              "path": "/v1/shipments",
              "summary": "Start tracking a shipment",
              "description": [
                "Starts tracking one identifier and returns the shipment straight away, usually in `discovering` (`tracking` for air). Carrier data follows within minutes — read it with [`GET /v1/shipments/{id}`](#shipments-get), or subscribe to `shipment.discovery_finished` and `shipment.status_changed`."
              ],
              "auth": "apiKey",
              "rateLimit": "general",
              "pathParams": [],
              "queryParams": [],
              "headers": [],
              "body": {
                "contentType": "application/json",
                "fields": [
                  {
                    "name": "identifier",
                    "type": "string",
                    "required": true,
                    "description": "Container, Master B/L, booking or Master AWB number. Surrounding whitespace is trimmed."
                  },
                  {
                    "name": "mode",
                    "type": "enum",
                    "required": true,
                    "description": "An unambiguous identifier wins over what you send: an ISO 6346 container number is always tracked as `OCEAN`, an AWB with a known airline prefix and a valid check digit as `AIR`. The response’s `mode` says which.",
                    "values": [
                      "OCEAN",
                      "AIR"
                    ]
                  },
                  {
                    "name": "carrier",
                    "type": "string",
                    "required": false,
                    "description": "A carrier code (`MSC`, `MAERSK`) or your own wording (\"Hapag Lloyd\", \"MAERSK LINE A/S\"). A name Navlo can’t match is still accepted and the carrier is detected from the identifier — never rejected. Informational for air: the AWB prefix decides."
                  },
                  {
                    "name": "customer",
                    "type": "object",
                    "required": false,
                    "description": "The shipment’s customer — [how it resolves](#shipments-customer-input). On an identifier you already track, it sets or replaces the customer."
                  },
                  {
                    "name": "customer.id",
                    "type": "uuid",
                    "required": false,
                    "description": "A Navlo customer id from [`GET /v1/customers`](/developers/customers#customers-list). Wins when both `id` and `ref` are sent."
                  },
                  {
                    "name": "customer.ref",
                    "type": "string",
                    "required": false,
                    "description": "Your own code for the customer (max 100 characters, case-insensitive, trimmed). An unknown ref creates the customer."
                  },
                  {
                    "name": "customer.name",
                    "type": "string",
                    "required": false,
                    "description": "Name used only when the ref creates a new customer. Defaults to the ref. Never renames an existing customer."
                  }
                ]
              },
              "response": {
                "status": 201,
                "contentType": "application/json",
                "fields": [
                  {
                    "name": "id",
                    "type": "uuid",
                    "description": "The shipment’s id — the `{id}` of every `/v1/shipments/{id}` call."
                  },
                  {
                    "name": "identifier",
                    "type": "string",
                    "description": "The number you tracked, trimmed (AWBs in the dashed IATA form, e.g. `871-12345675`)."
                  },
                  {
                    "name": "mode",
                    "type": "enum",
                    "description": "Transport mode.",
                    "values": [
                      "OCEAN",
                      "AIR"
                    ]
                  },
                  {
                    "name": "status",
                    "type": "enum",
                    "description": "Lifecycle status — see [Statuses](/developers/statuses-and-time-zones#statuses-shipment). `tracking` — air only: the waybill was accepted and Navlo is fetching the airline's first data. It becomes `active` when that data arrives (or `discovering` if no airline has it yet). A new air shipment's create response usually says `tracking`. List, export and report filters treat it as `active`.",
                    "values": [
                      "discovering",
                      "resolving",
                      "active",
                      "tracking",
                      "completed",
                      "stopped"
                    ]
                  },
                  {
                    "name": "carrier",
                    "type": "string",
                    "nullable": true,
                    "description": "The carrier Navlo tracks this shipment with, e.g. `MSC` or `SUPARANA_AIRLINES`. Null until the carrier is known. Display it as-is."
                  },
                  {
                    "name": "createdAt",
                    "type": "timestamp",
                    "description": "When the shipment was started in Navlo (UTC)."
                  }
                ]
              },
              "requestExamples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl -X POST \"https://api.navlo.io/v1/shipments\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"identifier\": \"MEDU1234562\",\n    \"mode\": \"OCEAN\",\n    \"carrier\": \"MSC\",\n    \"customer\": {\n      \"ref\": \"C-1042\",\n      \"name\": \"Acme Trading Ltd.\"\n    }\n  }'"
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const res = await fetch('https://api.navlo.io/v1/shipments', {\n  method: 'POST',\n  headers: {\n    'X-API-Key': process.env.NAVLO_API_KEY,\n    'Content-Type': 'application/json',\n  },\n  body: JSON.stringify({\n    identifier: 'MEDU1234562',\n    mode: 'OCEAN',\n    carrier: 'MSC',\n    customer: { ref: 'C-1042', name: 'Acme Trading Ltd.' },\n  }),\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\nconst shipment = await res.json()"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.post(\n    \"https://api.navlo.io/v1/shipments\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    json={\n        \"identifier\": \"MEDU1234562\",\n        \"mode\": \"OCEAN\",\n        \"carrier\": \"MSC\",\n        \"customer\": {\"ref\": \"C-1042\", \"name\": \"Acme Trading Ltd.\"},\n    },\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\nshipment = r.json()"
                }
              ],
              "responseExamples": [
                {
                  "status": 201,
                  "contentType": "application/json",
                  "body": "{\n  \"id\": \"8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07\",\n  \"identifier\": \"MEDU1234562\",\n  \"mode\": \"OCEAN\",\n  \"status\": \"discovering\",\n  \"carrier\": \"MSC\",\n  \"createdAt\": \"2026-09-24T07:41:18Z\"\n}"
                }
              ],
              "errors": [
                {
                  "status": 400,
                  "message": "identifier must not be blank",
                  "when": "`identifier` missing or blank."
                },
                {
                  "status": 400,
                  "message": "mode is required: OCEAN or AIR",
                  "when": "`mode` missing or not `OCEAN` / `AIR`."
                },
                {
                  "status": 400,
                  "message": "Unknown customer id",
                  "when": "`customer.id` is not one of your customers."
                },
                {
                  "status": 400,
                  "message": "customer needs an id or a ref",
                  "when": "`customer` was sent without `id` or `ref`."
                },
                {
                  "status": 400,
                  "message": "Malformed or unreadable request body",
                  "when": "The body is not valid JSON (general error shape)."
                },
                {
                  "status": 402,
                  "message": "Insufficient credits. Required: 1.00, Available: 0.00",
                  "when": "A new identifier and no tracking credits left (general error shape)."
                },
                {
                  "status": 401,
                  "message": "Invalid or revoked API key",
                  "when": "The X-API-Key header is missing, wrong or revoked."
                },
                {
                  "status": 429,
                  "message": "Rate limit exceeded (60 requests/minute)",
                  "when": "Over the per-key budget; wait Retry-After seconds."
                }
              ],
              "notes": [
                "**Idempotent.** Posting an identifier your organization already tracks returns that shipment, still with `201` — no duplicate, no charge.",
                "**Cost:** 1 tracking credit for an identifier new to your organization. Free when your organization already tracks it, and when Navlo can’t track that carrier (the shipment is then `stopped` at once). If discovery finds no data at all, Navlo keeps retrying and refunds the credit when it gives up.",
                "A bad `customer` is rejected before anything is created or charged."
              ]
            },
            {
              "kind": "endpoint",
              "id": "shipments-batch",
              "method": "POST",
              "path": "/v1/shipments/batch",
              "summary": "Start tracking up to 50 shipments",
              "description": [
                "Bulk-starts tracking in one call — built for integration platforms and backfills. The call counts as one request against the rate limit, and items succeed or fail on their own: there is no all-or-nothing rejection."
              ],
              "auth": "apiKey",
              "rateLimit": "general",
              "pathParams": [],
              "queryParams": [],
              "headers": [],
              "body": {
                "contentType": "application/json",
                "fields": [
                  {
                    "name": "shipments",
                    "type": "array<object>",
                    "required": true,
                    "description": "1–50 items."
                  },
                  {
                    "name": "shipments[].identifier",
                    "type": "string",
                    "required": true,
                    "description": "As on the single endpoint. A blank item fails alone."
                  },
                  {
                    "name": "shipments[].mode",
                    "type": "enum",
                    "required": true,
                    "description": "As on the single endpoint. An item without it fails alone.",
                    "values": [
                      "OCEAN",
                      "AIR"
                    ]
                  },
                  {
                    "name": "shipments[].carrier",
                    "type": "string",
                    "required": false,
                    "description": "Code or your own wording — same resolution as the single endpoint."
                  },
                  {
                    "name": "shipments[].customer",
                    "type": "object",
                    "required": false,
                    "description": "`{ \"id\" }` or `{ \"ref\", \"name\" }`. A bad customer fails that item only."
                  }
                ]
              },
              "response": {
                "status": 200,
                "contentType": "application/json",
                "fields": [
                  {
                    "name": "submitted",
                    "type": "integer",
                    "description": "Items received."
                  },
                  {
                    "name": "created",
                    "type": "integer",
                    "description": "New shipments started — one credit each."
                  },
                  {
                    "name": "existing",
                    "type": "integer",
                    "description": "Identifiers you already tracked — returned, not charged."
                  },
                  {
                    "name": "errors",
                    "type": "integer",
                    "description": "Items that failed."
                  },
                  {
                    "name": "results",
                    "type": "array<object>",
                    "description": "One per item, in request order."
                  },
                  {
                    "name": "results[].identifier",
                    "type": "string",
                    "description": "The item’s identifier as sent (trimmed)."
                  },
                  {
                    "name": "results[].status",
                    "type": "enum",
                    "description": "What happened to the item.",
                    "values": [
                      "created",
                      "existing",
                      "error"
                    ]
                  },
                  {
                    "name": "results[].id",
                    "type": "uuid",
                    "nullable": true,
                    "description": "The shipment id; null on error."
                  },
                  {
                    "name": "results[].error",
                    "type": "string",
                    "nullable": true,
                    "description": "Why the item failed, e.g. `Insufficient credits`, `Unknown customer id`; null otherwise."
                  }
                ]
              },
              "requestExamples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl -X POST \"https://api.navlo.io/v1/shipments/batch\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"shipments\": [\n      {\n        \"identifier\": \"MEDU1234562\",\n        \"mode\": \"OCEAN\",\n        \"customer\": {\n          \"ref\": \"C-1042\"\n        }\n      },\n      {\n        \"identifier\": \"TGHU8126501\",\n        \"mode\": \"OCEAN\",\n        \"carrier\": \"Hapag Lloyd\",\n        \"customer\": {\n          \"ref\": \"C-1042\"\n        }\n      },\n      {\n        \"identifier\": \"176-12345675\",\n        \"mode\": \"AIR\",\n        \"customer\": {\n          \"ref\": \"C-2107\",\n          \"name\": \"Sample Foods Ltd.\"\n        }\n      },\n      {\n        \"identifier\": \"MSCU7362815\",\n        \"mode\": \"OCEAN\",\n        \"customer\": {\n          \"id\": \"00000000-0000-0000-0000-000000000000\"\n        }\n      }\n    ]\n  }'"
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const res = await fetch('https://api.navlo.io/v1/shipments/batch', {\n  method: 'POST',\n  headers: {\n    'X-API-Key': process.env.NAVLO_API_KEY,\n    'Content-Type': 'application/json',\n  },\n  body: JSON.stringify({\n    shipments: [\n      {\n        identifier: 'MEDU1234562',\n        mode: 'OCEAN',\n        customer: { ref: 'C-1042' },\n      },\n      {\n        identifier: 'TGHU8126501',\n        mode: 'OCEAN',\n        carrier: 'Hapag Lloyd',\n        customer: { ref: 'C-1042' },\n      },\n      {\n        identifier: '176-12345675',\n        mode: 'AIR',\n        customer: { ref: 'C-2107', name: 'Sample Foods Ltd.' },\n      },\n      {\n        identifier: 'MSCU7362815',\n        mode: 'OCEAN',\n        customer: { id: '00000000-0000-0000-0000-000000000000' },\n      },\n    ],\n  }),\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\nconst batch = await res.json()"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.post(\n    \"https://api.navlo.io/v1/shipments/batch\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    json={\n        \"shipments\": [\n            {\n                \"identifier\": \"MEDU1234562\",\n                \"mode\": \"OCEAN\",\n                \"customer\": {\"ref\": \"C-1042\"},\n            },\n            {\n                \"identifier\": \"TGHU8126501\",\n                \"mode\": \"OCEAN\",\n                \"carrier\": \"Hapag Lloyd\",\n                \"customer\": {\"ref\": \"C-1042\"},\n            },\n            {\n                \"identifier\": \"176-12345675\",\n                \"mode\": \"AIR\",\n                \"customer\": {\"ref\": \"C-2107\", \"name\": \"Sample Foods Ltd.\"},\n            },\n            {\n                \"identifier\": \"MSCU7362815\",\n                \"mode\": \"OCEAN\",\n                \"customer\": {\"id\": \"00000000-0000-0000-0000-000000000000\"},\n            },\n        ],\n    },\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\nbatch = r.json()"
                }
              ],
              "responseExamples": [
                {
                  "status": 200,
                  "contentType": "application/json",
                  "body": "{\n  \"submitted\": 4,\n  \"created\": 2,\n  \"existing\": 1,\n  \"errors\": 1,\n  \"results\": [\n    {\n      \"identifier\": \"MEDU1234562\",\n      \"status\": \"existing\",\n      \"id\": \"8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07\",\n      \"error\": null\n    },\n    {\n      \"identifier\": \"TGHU8126501\",\n      \"status\": \"created\",\n      \"id\": \"6b1f0c9a-4d2e-4f7b-9a3c-8e5d21f0a4b7\",\n      \"error\": null\n    },\n    {\n      \"identifier\": \"176-12345675\",\n      \"status\": \"created\",\n      \"id\": \"b5d13c88-9e2f-4a7b-8c41-6f0a3e9d72c5\",\n      \"error\": null\n    },\n    {\n      \"identifier\": \"MSCU7362815\",\n      \"status\": \"error\",\n      \"id\": null,\n      \"error\": \"Unknown customer id\"\n    }\n  ]\n}"
                }
              ],
              "errors": [
                {
                  "status": 400,
                  "message": "shipments must not be empty",
                  "when": "`shipments` is empty."
                },
                {
                  "status": 400,
                  "message": "Maximum 50 shipments per batch",
                  "when": "More than 50 items."
                },
                {
                  "status": 400,
                  "message": "Malformed or unreadable request body",
                  "when": "The body is not valid JSON (general error shape)."
                },
                {
                  "status": 401,
                  "message": "Invalid or revoked API key",
                  "when": "The X-API-Key header is missing, wrong or revoked."
                },
                {
                  "status": 429,
                  "message": "Rate limit exceeded (60 requests/minute)",
                  "when": "Over the per-key budget; wait Retry-After seconds."
                }
              ],
              "notes": [
                "Running out of credits mid-batch fails the remaining new identifiers with `Insufficient credits`; items you already track still come back as `existing`."
              ]
            },
            {
              "kind": "endpoint",
              "id": "shipments-list",
              "method": "GET",
              "path": "/v1/shipments",
              "summary": "List shipments",
              "description": [
                "Pages through your organization’s shipments, newest data first when you sort by `-updatedAt`. Every filter is optional and they combine with AND; a carrier, customer or tag that matches nothing gives an empty page, not an error. With no parameters the response is exactly what this endpoint has always returned."
              ],
              "auth": "apiKey",
              "rateLimit": "general",
              "pathParams": [],
              "queryParams": [
                {
                  "name": "page",
                  "type": "integer",
                  "required": false,
                  "description": "Zero-based page index.",
                  "defaultValue": "0"
                },
                {
                  "name": "size",
                  "type": "integer",
                  "required": false,
                  "description": "Page size, 1–100. Larger values are capped at 100.",
                  "defaultValue": "20"
                },
                {
                  "name": "status",
                  "type": "csv",
                  "required": false,
                  "description": "Only these statuses, e.g. `active,completed`. `active` also matches `tracking`.",
                  "values": [
                    "discovering",
                    "resolving",
                    "active",
                    "tracking",
                    "completed",
                    "stopped"
                  ]
                },
                {
                  "name": "mode",
                  "type": "csv",
                  "required": false,
                  "description": "Only ocean or only air shipments (`OCEAN,AIR` means both).",
                  "values": [
                    "OCEAN",
                    "AIR"
                  ]
                },
                {
                  "name": "carrier",
                  "type": "string",
                  "required": false,
                  "description": "Carrier code, e.g. `MSC`, `MAERSK` — exact, case-insensitive."
                },
                {
                  "name": "customerId",
                  "type": "uuid",
                  "required": false,
                  "description": "Only shipments of this customer."
                },
                {
                  "name": "customerRef",
                  "type": "string",
                  "required": false,
                  "description": "Only shipments of the customer with this reference (case-insensitive). With `customerId` too, both must match."
                },
                {
                  "name": "tag",
                  "type": "csv",
                  "required": false,
                  "description": "Tag names (case-insensitive); shipments carrying any of them, e.g. `Priority,Q4 launch`."
                },
                {
                  "name": "risk",
                  "type": "csv",
                  "required": false,
                  "description": "Only these risk levels. Only fresh risk counts — shipments whose risk is stale or unknown never match.",
                  "values": [
                    "LOW",
                    "MEDIUM",
                    "HIGH"
                  ]
                },
                {
                  "name": "etaFrom",
                  "type": "timestamp | date",
                  "required": false,
                  "description": "ETA on or after this time (any container or waybill). ETAs are carrier-local times, compared as written. Every date filter takes an ISO instant, an offset date-time or a plain date."
                },
                {
                  "name": "etaTo",
                  "type": "timestamp | date",
                  "required": false,
                  "description": "ETA on or before this time; a date means the end of that day."
                },
                {
                  "name": "createdFrom",
                  "type": "timestamp | date",
                  "required": false,
                  "description": "Started in Navlo on or after this time (UTC)."
                },
                {
                  "name": "createdTo",
                  "type": "timestamp | date",
                  "required": false,
                  "description": "Started in Navlo on or before this time (UTC); a date means the end of that day."
                },
                {
                  "name": "updatedSince",
                  "type": "timestamp",
                  "required": false,
                  "description": "Only shipments whose data changed at or after this time — compared with `lastChangedAt`. The basis of [incremental sync](#shipments-sync); air shipments can match without a visible change (see there)."
                },
                {
                  "name": "sort",
                  "type": "enum",
                  "required": false,
                  "description": "`updatedAt` sorts by `lastChangedAt`, `eta` by the soonest ETA (shipments without one last); prefix `-` for descending. Without `sort`, filtered lists come newest-created first, while a request with no filters (only `include`, or nothing) keeps the order it always had — pass `sort` whenever order matters.",
                  "values": [
                    "createdAt",
                    "-createdAt",
                    "updatedAt",
                    "-updatedAt",
                    "eta",
                    "-eta"
                  ]
                },
                {
                  "name": "include",
                  "type": "csv",
                  "required": false,
                  "description": "Extra keys on each item — see the response fields below.",
                  "values": [
                    "customer",
                    "tags",
                    "risk",
                    "lastChangedAt"
                  ]
                }
              ],
              "headers": [],
              "response": {
                "status": 200,
                "contentType": "application/json",
                "fields": [
                  {
                    "name": "page",
                    "type": "integer",
                    "description": "The page you asked for."
                  },
                  {
                    "name": "size",
                    "type": "integer",
                    "description": "The page size used."
                  },
                  {
                    "name": "totalElements",
                    "type": "integer",
                    "description": "Shipments matching the filters."
                  },
                  {
                    "name": "totalPages",
                    "type": "integer",
                    "description": "Pages at this size."
                  },
                  {
                    "name": "shipments",
                    "type": "array<object>",
                    "description": "The page’s shipments, each with the fields below."
                  },
                  {
                    "name": "shipments[].id",
                    "type": "uuid",
                    "description": "The shipment’s id — the `{id}` of every `/v1/shipments/{id}` call."
                  },
                  {
                    "name": "shipments[].identifier",
                    "type": "string",
                    "description": "The number you tracked, trimmed (AWBs in the dashed IATA form, e.g. `871-12345675`)."
                  },
                  {
                    "name": "shipments[].mode",
                    "type": "enum",
                    "description": "Transport mode.",
                    "values": [
                      "OCEAN",
                      "AIR"
                    ]
                  },
                  {
                    "name": "shipments[].status",
                    "type": "enum",
                    "description": "Lifecycle status — see [Statuses](/developers/statuses-and-time-zones#statuses-shipment). `tracking` — air only: the waybill was accepted and Navlo is fetching the airline's first data. It becomes `active` when that data arrives (or `discovering` if no airline has it yet). A new air shipment's create response usually says `tracking`. List, export and report filters treat it as `active`.",
                    "values": [
                      "discovering",
                      "resolving",
                      "active",
                      "tracking",
                      "completed",
                      "stopped"
                    ]
                  },
                  {
                    "name": "shipments[].carrier",
                    "type": "string",
                    "nullable": true,
                    "description": "The carrier Navlo tracks this shipment with, e.g. `MSC` or `SUPARANA_AIRLINES`. Null until the carrier is known. Display it as-is."
                  },
                  {
                    "name": "shipments[].createdAt",
                    "type": "timestamp",
                    "description": "When the shipment was started in Navlo (UTC)."
                  },
                  {
                    "name": "shipments[].customer",
                    "type": "object",
                    "nullable": true,
                    "description": "With `include=customer`: the shipment’s customer (`id`, `ref`, `name`, `countryCode`), or null."
                  },
                  {
                    "name": "shipments[].tags",
                    "type": "array<object>",
                    "description": "With `include=tags`: the shipment’s tags, `[{ id, name, color }]`."
                  },
                  {
                    "name": "shipments[].risk",
                    "type": "object",
                    "description": "With `include=risk`: `{ level, computedAt, stale }` — the same freshness rule as the detail’s [risk](/developers/shipment-intelligence#intelligence-risk)."
                  },
                  {
                    "name": "shipments[].lastChangedAt",
                    "type": "timestamp",
                    "nullable": true,
                    "description": "With `include=lastChangedAt`: when the shipment’s data last changed — the value `updatedSince` and `sort=updatedAt` use. If no change is recorded yet, it falls back to the shipment’s last update time."
                  }
                ]
              },
              "requestExamples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl \"https://api.navlo.io/v1/shipments?status=active&customerRef=C-1042&include=customer,tags,risk,lastChangedAt&sort=-updatedAt\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\""
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const params = new URLSearchParams({\n  status: 'active',\n  customerRef: 'C-1042',\n  include: 'customer,tags,risk,lastChangedAt',\n  sort: '-updatedAt',\n})\n\nconst res = await fetch(`https://api.navlo.io/v1/shipments?${params}`, {\n  headers: { 'X-API-Key': process.env.NAVLO_API_KEY },\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\nconst page = await res.json()"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.get(\n    \"https://api.navlo.io/v1/shipments\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    params={\n        \"status\": \"active\",\n        \"customerRef\": \"C-1042\",\n        \"include\": \"customer,tags,risk,lastChangedAt\",\n        \"sort\": \"-updatedAt\",\n    },\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\npage = r.json()"
                }
              ],
              "responseExamples": [
                {
                  "status": 200,
                  "label": "With filters and include",
                  "contentType": "application/json",
                  "body": "{\n  \"page\": 0,\n  \"size\": 20,\n  \"totalElements\": 2,\n  \"totalPages\": 1,\n  \"shipments\": [\n    {\n      \"id\": \"8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07\",\n      \"identifier\": \"MEDU1234562\",\n      \"mode\": \"OCEAN\",\n      \"status\": \"active\",\n      \"carrier\": \"MSC\",\n      \"createdAt\": \"2026-09-24T07:41:18Z\",\n      \"customer\": {\n        \"id\": \"c7d2a9e4-3f1b-4e8a-9b6c-1d5e7f3a2b90\",\n        \"ref\": \"C-1042\",\n        \"name\": \"Acme Trading Ltd.\",\n        \"countryCode\": \"TR\"\n      },\n      \"tags\": [\n        {\n          \"id\": \"a3f9c2d1-7b4e-4c8a-9e16-2d5f8b0c7e41\",\n          \"name\": \"Priority\",\n          \"color\": \"#ef4444\"\n        },\n        {\n          \"id\": \"b81e4d7a-2c9f-4a63-8d05-6e3b1f9c2a77\",\n          \"name\": \"Q4 launch\",\n          \"color\": \"#3b82f6\"\n        }\n      ],\n      \"risk\": {\n        \"level\": \"MEDIUM\",\n        \"computedAt\": \"2026-10-22T07:15:00Z\",\n        \"stale\": false\n      },\n      \"lastChangedAt\": \"2026-10-22T06:00:41Z\"\n    },\n    {\n      \"id\": \"6b1f0c9a-4d2e-4f7b-9a3c-8e5d21f0a4b7\",\n      \"identifier\": \"TGHU8126501\",\n      \"mode\": \"OCEAN\",\n      \"status\": \"active\",\n      \"carrier\": \"HAPAG\",\n      \"createdAt\": \"2026-10-02T13:20:07Z\",\n      \"customer\": {\n        \"id\": \"c7d2a9e4-3f1b-4e8a-9b6c-1d5e7f3a2b90\",\n        \"ref\": \"C-1042\",\n        \"name\": \"Acme Trading Ltd.\",\n        \"countryCode\": \"TR\"\n      },\n      \"tags\": [],\n      \"risk\": {\n        \"level\": null,\n        \"computedAt\": \"2026-10-21T19:02:00Z\",\n        \"stale\": true\n      },\n      \"lastChangedAt\": \"2026-10-21T22:47:13Z\"\n    }\n  ]\n}"
                },
                {
                  "status": 200,
                  "label": "No parameters",
                  "contentType": "application/json",
                  "body": "{\n  \"page\": 0,\n  \"size\": 20,\n  \"totalElements\": 143,\n  \"totalPages\": 8,\n  \"shipments\": [\n    {\n      \"id\": \"8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07\",\n      \"identifier\": \"MEDU1234562\",\n      \"mode\": \"OCEAN\",\n      \"status\": \"active\",\n      \"carrier\": \"MSC\",\n      \"createdAt\": \"2026-09-24T07:41:18Z\"\n    },\n    {\n      \"id\": \"5c2e8a1f-9b3d-4e72-a6c0-3d8f1b7e4a59\",\n      \"identifier\": \"871-12345675\",\n      \"mode\": \"AIR\",\n      \"status\": \"completed\",\n      \"carrier\": \"SUPARANA_AIRLINES\",\n      \"createdAt\": \"2026-10-18T11:02:51Z\"\n    }\n  ]\n}"
                }
              ],
              "errors": [
                {
                  "status": 400,
                  "message": "Unknown status 'shipped'. Allowed values: discovering, resolving, active, tracking, completed, stopped",
                  "when": "A filter, `sort` or `include` value outside its allowed list — the message names the parameter."
                },
                {
                  "status": 400,
                  "message": "etaFrom must be an ISO-8601 timestamp or date, e.g. 2026-10-01T00:00:00Z or 2026-10-01",
                  "when": "A date parameter that doesn’t parse."
                },
                {
                  "status": 400,
                  "message": "customerId must be a UUID",
                  "when": "A malformed `customerId`."
                },
                {
                  "status": 401,
                  "message": "Invalid or revoked API key",
                  "when": "The X-API-Key header is missing, wrong or revoked."
                },
                {
                  "status": 429,
                  "message": "Rate limit exceeded (60 requests/minute)",
                  "when": "Over the per-key budget; wait Retry-After seconds."
                }
              ],
              "notes": []
            },
            {
              "kind": "endpoint",
              "id": "shipments-get",
              "method": "GET",
              "path": "/v1/shipments/{id}",
              "summary": "Retrieve a shipment",
              "description": [
                "The full shipment: containers or air waybills with their dates and ports, the merged event timeline, the ETA change history and the vessel’s last known position. Add `include` for Navlo’s intelligence — each value is documented on [Shipment intelligence](/developers/shipment-intelligence)."
              ],
              "auth": "apiKey",
              "rateLimit": "general",
              "pathParams": [
                {
                  "name": "id",
                  "type": "uuid",
                  "required": true,
                  "description": "The shipment id from the create or list response."
                }
              ],
              "queryParams": [
                {
                  "name": "include",
                  "type": "csv",
                  "required": false,
                  "description": "Extra blocks to add. A requested key is always present — `null` or `[]` when there is nothing. `all` adds every block.",
                  "values": [
                    "risk",
                    "recommendations",
                    "navloEta",
                    "dnd",
                    "carbon",
                    "alerts",
                    "customer",
                    "tags",
                    "details",
                    "all"
                  ]
                }
              ],
              "headers": [],
              "response": {
                "status": 200,
                "contentType": "application/json",
                "fields": [
                  {
                    "name": "id",
                    "type": "uuid",
                    "description": "The shipment’s id."
                  },
                  {
                    "name": "identifier",
                    "type": "string",
                    "description": "The number you tracked."
                  },
                  {
                    "name": "mode",
                    "type": "enum",
                    "description": "Branch on this: ocean shipments fill `containers`, air shipments fill `airShipments`.",
                    "values": [
                      "OCEAN",
                      "AIR"
                    ]
                  },
                  {
                    "name": "status",
                    "type": "enum",
                    "description": "Lifecycle status. `tracking` — air only: the waybill was accepted and Navlo is fetching the airline's first data. It becomes `active` when that data arrives (or `discovering` if no airline has it yet). A new air shipment's create response usually says `tracking`. List, export and report filters treat it as `active`.",
                    "values": [
                      "discovering",
                      "resolving",
                      "active",
                      "tracking",
                      "completed",
                      "stopped"
                    ]
                  },
                  {
                    "name": "carrier",
                    "type": "string",
                    "nullable": true,
                    "description": "The carrier, as on the list."
                  },
                  {
                    "name": "containers",
                    "type": "array<object>",
                    "description": "OCEAN: one entry per container. Always `[]` for air."
                  },
                  {
                    "name": "containers[].containerNumber",
                    "type": "string",
                    "description": "ISO 6346 container number."
                  },
                  {
                    "name": "containers[].containerType",
                    "type": "string",
                    "nullable": true,
                    "description": "Size/type as the carrier reports it, e.g. `40HC`, `20DV`."
                  },
                  {
                    "name": "containers[].status",
                    "type": "string",
                    "nullable": true,
                    "description": "The container’s current milestone code, e.g. `DEPARTED`, `DISCHARGED` ([milestone codes](/developers/statuses-and-time-zones#statuses-milestones))."
                  },
                  {
                    "name": "containers[].etd",
                    "type": "timestamp",
                    "nullable": true,
                    "description": "Estimated departure from the port of loading — carrier local time ([time zones](/developers/statuses-and-time-zones#statuses-time-zones))."
                  },
                  {
                    "name": "containers[].atd",
                    "type": "timestamp",
                    "nullable": true,
                    "description": "Actual departure from the port of loading."
                  },
                  {
                    "name": "containers[].eta",
                    "type": "timestamp",
                    "nullable": true,
                    "description": "Estimated arrival at the port of discharge — the carrier’s ETA."
                  },
                  {
                    "name": "containers[].ata",
                    "type": "timestamp",
                    "nullable": true,
                    "description": "Actual arrival at the port of discharge."
                  },
                  {
                    "name": "containers[].origin.code",
                    "type": "string",
                    "nullable": true,
                    "description": "Port of loading code — UN/LOCODE for ocean (`CNSHA`), IATA for air (`AMS`)."
                  },
                  {
                    "name": "containers[].origin.name",
                    "type": "string",
                    "nullable": true,
                    "description": "Port of loading name."
                  },
                  {
                    "name": "containers[].destination.code",
                    "type": "string",
                    "nullable": true,
                    "description": "Port of discharge code — UN/LOCODE for ocean (`CNSHA`), IATA for air (`AMS`)."
                  },
                  {
                    "name": "containers[].destination.name",
                    "type": "string",
                    "nullable": true,
                    "description": "Port of discharge name."
                  },
                  {
                    "name": "containers[].currentVessel",
                    "type": "string",
                    "nullable": true,
                    "description": "The vessel the container is on or booked on."
                  },
                  {
                    "name": "airShipments",
                    "type": "array<object>",
                    "description": "AIR: one entry per air waybill. Always `[]` for ocean."
                  },
                  {
                    "name": "airShipments[].awbNumber",
                    "type": "string",
                    "nullable": true,
                    "description": "Dashed IATA form, e.g. `871-12345675`."
                  },
                  {
                    "name": "airShipments[].status",
                    "type": "string",
                    "nullable": true,
                    "description": "Current milestone code, e.g. `BOOKED`, `DEPARTED`, `ARRIVED`, `DELIVERED`."
                  },
                  {
                    "name": "airShipments[].origin.code",
                    "type": "string",
                    "nullable": true,
                    "description": "Origin airport code — UN/LOCODE for ocean (`CNSHA`), IATA for air (`AMS`)."
                  },
                  {
                    "name": "airShipments[].origin.name",
                    "type": "string",
                    "nullable": true,
                    "description": "Origin airport name."
                  },
                  {
                    "name": "airShipments[].destination.code",
                    "type": "string",
                    "nullable": true,
                    "description": "Destination airport code — UN/LOCODE for ocean (`CNSHA`), IATA for air (`AMS`)."
                  },
                  {
                    "name": "airShipments[].destination.name",
                    "type": "string",
                    "nullable": true,
                    "description": "Destination airport name."
                  },
                  {
                    "name": "airShipments[].currentAirport",
                    "type": "object",
                    "nullable": true,
                    "description": "Where the cargo was last reported (`code`, `name`), when the airline says."
                  },
                  {
                    "name": "airShipments[].etd",
                    "type": "timestamp",
                    "nullable": true,
                    "description": "Estimated departure — airport local time."
                  },
                  {
                    "name": "airShipments[].atd",
                    "type": "timestamp",
                    "nullable": true,
                    "description": "Actual departure."
                  },
                  {
                    "name": "airShipments[].eta",
                    "type": "timestamp",
                    "nullable": true,
                    "description": "Estimated arrival."
                  },
                  {
                    "name": "airShipments[].ata",
                    "type": "timestamp",
                    "nullable": true,
                    "description": "Actual arrival."
                  },
                  {
                    "name": "airShipments[].pieces",
                    "type": "integer",
                    "nullable": true,
                    "description": "Pieces on the waybill."
                  },
                  {
                    "name": "airShipments[].weight",
                    "type": "number",
                    "nullable": true,
                    "description": "Gross weight, in `weightUnit`."
                  },
                  {
                    "name": "airShipments[].weightUnit",
                    "type": "enum",
                    "nullable": true,
                    "description": "Null reads as kilograms.",
                    "values": [
                      "KILOGRAM",
                      "POUND"
                    ]
                  },
                  {
                    "name": "airShipments[].chargeableWeight",
                    "type": "number",
                    "nullable": true,
                    "description": "IATA chargeable (volumetric) weight, same unit."
                  },
                  {
                    "name": "airShipments[].volume",
                    "type": "number",
                    "nullable": true,
                    "description": "Volume, in `volumeUnit` (usually cubic metres)."
                  },
                  {
                    "name": "airShipments[].volumeUnit",
                    "type": "string",
                    "nullable": true,
                    "description": "Volume unit when the airline reports one."
                  },
                  {
                    "name": "airShipments[].flights",
                    "type": "array<object>",
                    "description": "Booked and flown legs in order — empty until the airline publishes the routing."
                  },
                  {
                    "name": "airShipments[].flights[].flightNumber",
                    "type": "string",
                    "description": "e.g. `Y87001`."
                  },
                  {
                    "name": "airShipments[].flights[].from",
                    "type": "object",
                    "description": "Departure airport (`code`, `name`)."
                  },
                  {
                    "name": "airShipments[].flights[].to",
                    "type": "object",
                    "description": "Arrival airport (`code`, `name`)."
                  },
                  {
                    "name": "airShipments[].flights[].etd",
                    "type": "timestamp",
                    "nullable": true,
                    "description": "Scheduled/estimated departure of the leg (`atd`, `eta`, `ata` likewise)."
                  },
                  {
                    "name": "airShipments[].flights[].status",
                    "type": "string",
                    "nullable": true,
                    "description": "The airline’s booking status for the leg, e.g. `BOOKED`, `PLANNED`."
                  },
                  {
                    "name": "events",
                    "type": "array<object>",
                    "description": "The merged timeline across containers or waybills, oldest first (up to 200 events per container)."
                  },
                  {
                    "name": "events[].timestamp",
                    "type": "timestamp",
                    "nullable": true,
                    "description": "When it happened (or is expected) — carrier local time."
                  },
                  {
                    "name": "events[].type",
                    "type": "enum",
                    "nullable": true,
                    "description": "`ACTUAL` — it happened. `EXPECTED` — a carrier projection that can still change. Null when the carrier doesn’t say.",
                    "values": [
                      "ACTUAL",
                      "EXPECTED"
                    ]
                  },
                  {
                    "name": "events[].status",
                    "type": "string",
                    "nullable": true,
                    "description": "Navlo’s milestone code when the carrier event is mapped (`DEPARTED`), otherwise the carrier’s own text."
                  },
                  {
                    "name": "events[].location",
                    "type": "string",
                    "nullable": true,
                    "description": "Place name."
                  },
                  {
                    "name": "events[].locationCode",
                    "type": "string",
                    "nullable": true,
                    "description": "UN/LOCODE (ocean) or IATA code (air)."
                  },
                  {
                    "name": "events[].vessel",
                    "type": "string",
                    "nullable": true,
                    "description": "OCEAN: vessel name. Null on air events."
                  },
                  {
                    "name": "events[].voyage",
                    "type": "string",
                    "nullable": true,
                    "description": "OCEAN: voyage number."
                  },
                  {
                    "name": "events[].flight",
                    "type": "string",
                    "nullable": true,
                    "description": "AIR: the flight the event refers to. Null on ocean events."
                  },
                  {
                    "name": "events[].pieces",
                    "type": "integer",
                    "nullable": true,
                    "description": "AIR: pieces this event covers — split consignments report a partial count per leg."
                  },
                  {
                    "name": "events[].weight",
                    "type": "number",
                    "nullable": true,
                    "description": "AIR: weight this event covers, in the waybill’s unit."
                  },
                  {
                    "name": "etaHistory",
                    "type": "array<object>",
                    "description": "Every recorded ETA/ETD/ATA/ATD change, newest first, up to 100."
                  },
                  {
                    "name": "etaHistory[].field",
                    "type": "enum",
                    "description": "Which time moved.",
                    "values": [
                      "ETA",
                      "ETD",
                      "ATA",
                      "ATD"
                    ]
                  },
                  {
                    "name": "etaHistory[].previousValue",
                    "type": "timestamp",
                    "description": "The value before the change."
                  },
                  {
                    "name": "etaHistory[].newValue",
                    "type": "timestamp",
                    "description": "The value after it."
                  },
                  {
                    "name": "etaHistory[].deltaHours",
                    "type": "integer",
                    "description": "Signed hours — positive means later (a delay)."
                  },
                  {
                    "name": "etaHistory[].recordedAt",
                    "type": "timestamp",
                    "description": "When Navlo observed the change (UTC) — not when the carrier decided it."
                  },
                  {
                    "name": "etaHistory[].containerNumber",
                    "type": "string",
                    "nullable": true,
                    "description": "OCEAN: the container the change belongs to."
                  },
                  {
                    "name": "etaHistory[].awbNumber",
                    "type": "string",
                    "nullable": true,
                    "description": "AIR: the waybill the change belongs to."
                  },
                  {
                    "name": "vessel",
                    "type": "object",
                    "nullable": true,
                    "description": "Last known position of the vessel the shipment is on. Always null for air."
                  },
                  {
                    "name": "vessel.vesselName",
                    "type": "string",
                    "nullable": true,
                    "description": "Vessel name."
                  },
                  {
                    "name": "vessel.latitude",
                    "type": "number",
                    "description": "Latitude in degrees."
                  },
                  {
                    "name": "vessel.longitude",
                    "type": "number",
                    "description": "Longitude in degrees."
                  },
                  {
                    "name": "vessel.heading",
                    "type": "number",
                    "nullable": true,
                    "description": "Course over ground in degrees, when the fix has one."
                  },
                  {
                    "name": "vessel.source",
                    "type": "enum",
                    "description": "**Branch on this before drawing a ship.** `LIVE` — a fresh AIS fix for the vessel the container is verifiably on. `STALE` — that vessel’s real position, just old (see `reportedAt`). `LAST_KNOWN` — no trusted fix: the coordinates are the last port the shipment passed, NOT a ship position.",
                    "values": [
                      "LIVE",
                      "STALE",
                      "LAST_KNOWN"
                    ]
                  },
                  {
                    "name": "vessel.reportedAt",
                    "type": "timestamp",
                    "nullable": true,
                    "description": "AIS fix time (UTC) for `LIVE`/`STALE`; null for `LAST_KNOWN`."
                  }
                ]
              },
              "requestExamples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl \"https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\""
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const res = await fetch('https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07', {\n  headers: { 'X-API-Key': process.env.NAVLO_API_KEY },\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\nconst shipment = await res.json()"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.get(\n    \"https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\nshipment = r.json()"
                }
              ],
              "responseExamples": [
                {
                  "status": 200,
                  "label": "Ocean",
                  "contentType": "application/json",
                  "body": "{\n  \"id\": \"8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07\",\n  \"identifier\": \"MEDU1234562\",\n  \"mode\": \"OCEAN\",\n  \"status\": \"active\",\n  \"carrier\": \"MSC\",\n  \"containers\": [\n    {\n      \"containerNumber\": \"MEDU1234562\",\n      \"containerType\": \"40HC\",\n      \"status\": \"DEPARTED\",\n      \"etd\": \"2026-09-26T22:00:00Z\",\n      \"atd\": \"2026-09-27T03:40:00Z\",\n      \"eta\": \"2026-10-30T06:00:00Z\",\n      \"ata\": null,\n      \"origin\": {\n        \"code\": \"CNSHA\",\n        \"name\": \"Shanghai\"\n      },\n      \"destination\": {\n        \"code\": \"TRAMR\",\n        \"name\": \"Ambarli\"\n      },\n      \"currentVessel\": \"MSC MARTINA\"\n    }\n  ],\n  \"airShipments\": [],\n  \"events\": [\n    {\n      \"timestamp\": \"2026-09-24T14:12:00Z\",\n      \"type\": \"ACTUAL\",\n      \"status\": \"GATE_IN\",\n      \"location\": \"Shanghai\",\n      \"locationCode\": \"CNSHA\",\n      \"vessel\": null,\n      \"voyage\": null,\n      \"flight\": null,\n      \"pieces\": null,\n      \"weight\": null\n    },\n    {\n      \"timestamp\": \"2026-09-26T21:30:00Z\",\n      \"type\": \"ACTUAL\",\n      \"status\": \"LOADED\",\n      \"location\": \"Shanghai\",\n      \"locationCode\": \"CNSHA\",\n      \"vessel\": \"MSC MARTINA\",\n      \"voyage\": \"438W\",\n      \"flight\": null,\n      \"pieces\": null,\n      \"weight\": null\n    },\n    {\n      \"timestamp\": \"2026-09-27T03:40:00Z\",\n      \"type\": \"ACTUAL\",\n      \"status\": \"DEPARTED\",\n      \"location\": \"Shanghai\",\n      \"locationCode\": \"CNSHA\",\n      \"vessel\": \"MSC MARTINA\",\n      \"voyage\": \"438W\",\n      \"flight\": null,\n      \"pieces\": null,\n      \"weight\": null\n    },\n    {\n      \"timestamp\": \"2026-10-23T08:00:00Z\",\n      \"type\": \"EXPECTED\",\n      \"status\": \"TRANSSHIPMENT\",\n      \"location\": \"Piraeus\",\n      \"locationCode\": \"GRPIR\",\n      \"vessel\": \"MSC MARTINA\",\n      \"voyage\": \"438W\",\n      \"flight\": null,\n      \"pieces\": null,\n      \"weight\": null\n    },\n    {\n      \"timestamp\": \"2026-10-27T18:00:00Z\",\n      \"type\": \"EXPECTED\",\n      \"status\": \"DEPARTED\",\n      \"location\": \"Piraeus\",\n      \"locationCode\": \"GRPIR\",\n      \"vessel\": \"MSC ARIANE\",\n      \"voyage\": \"IP243A\",\n      \"flight\": null,\n      \"pieces\": null,\n      \"weight\": null\n    },\n    {\n      \"timestamp\": \"2026-10-30T06:00:00Z\",\n      \"type\": \"EXPECTED\",\n      \"status\": \"ARRIVED\",\n      \"location\": \"Ambarli\",\n      \"locationCode\": \"TRAMR\",\n      \"vessel\": \"MSC ARIANE\",\n      \"voyage\": \"IP243A\",\n      \"flight\": null,\n      \"pieces\": null,\n      \"weight\": null\n    }\n  ],\n  \"etaHistory\": [\n    {\n      \"field\": \"ETA\",\n      \"previousValue\": \"2026-10-27T06:00:00Z\",\n      \"newValue\": \"2026-10-30T06:00:00Z\",\n      \"deltaHours\": 72,\n      \"recordedAt\": \"2026-10-14T09:22:14Z\",\n      \"containerNumber\": \"MEDU1234562\",\n      \"awbNumber\": null\n    },\n    {\n      \"field\": \"ETA\",\n      \"previousValue\": \"2026-10-25T06:00:00Z\",\n      \"newValue\": \"2026-10-27T06:00:00Z\",\n      \"deltaHours\": 48,\n      \"recordedAt\": \"2026-10-03T11:05:39Z\",\n      \"containerNumber\": \"MEDU1234562\",\n      \"awbNumber\": null\n    }\n  ],\n  \"vessel\": {\n    \"vesselName\": \"MSC MARTINA\",\n    \"latitude\": 34.9123,\n    \"longitude\": 25.6342,\n    \"heading\": 318,\n    \"source\": \"LIVE\",\n    \"reportedAt\": \"2026-10-22T05:41:00Z\"\n  }\n}"
                },
                {
                  "status": 200,
                  "label": "Air",
                  "contentType": "application/json",
                  "body": "{\n  \"id\": \"5c2e8a1f-9b3d-4e72-a6c0-3d8f1b7e4a59\",\n  \"identifier\": \"871-12345675\",\n  \"mode\": \"AIR\",\n  \"status\": \"completed\",\n  \"carrier\": \"SUPARANA_AIRLINES\",\n  \"containers\": [],\n  \"airShipments\": [\n    {\n      \"awbNumber\": \"871-12345675\",\n      \"status\": \"DELIVERED\",\n      \"origin\": {\n        \"code\": \"CKG\",\n        \"name\": \"Chongqing Jiangbei International Airport\"\n      },\n      \"destination\": {\n        \"code\": \"AMS\",\n        \"name\": \"Amsterdam Airport Schiphol\"\n      },\n      \"currentAirport\": {\n        \"code\": \"AMS\",\n        \"name\": \"Amsterdam Airport Schiphol\"\n      },\n      \"etd\": \"2026-10-19T13:30:00Z\",\n      \"atd\": \"2026-10-19T13:44:00Z\",\n      \"eta\": \"2026-10-19T18:30:00Z\",\n      \"ata\": \"2026-10-19T18:52:00Z\",\n      \"pieces\": 120,\n      \"weight\": 1850,\n      \"weightUnit\": \"KILOGRAM\",\n      \"chargeableWeight\": 2210,\n      \"volume\": 13.25,\n      \"volumeUnit\": null,\n      \"flights\": [\n        {\n          \"flightNumber\": \"Y87001\",\n          \"from\": {\n            \"code\": \"CKG\",\n            \"name\": \"Chongqing Jiangbei International Airport\"\n          },\n          \"to\": {\n            \"code\": \"AMS\",\n            \"name\": \"Amsterdam Airport Schiphol\"\n          },\n          \"etd\": \"2026-10-19T13:30:00Z\",\n          \"atd\": \"2026-10-19T13:44:00Z\",\n          \"eta\": \"2026-10-19T18:30:00Z\",\n          \"ata\": \"2026-10-19T18:52:00Z\",\n          \"status\": \"BOOKED\"\n        }\n      ]\n    }\n  ],\n  \"events\": [\n    {\n      \"timestamp\": \"2026-10-18T22:10:00Z\",\n      \"type\": \"ACTUAL\",\n      \"status\": \"Received from Shipper\",\n      \"location\": \"Chongqing Jiangbei International Airport\",\n      \"locationCode\": \"CKG\",\n      \"vessel\": null,\n      \"voyage\": null,\n      \"flight\": null,\n      \"pieces\": 120,\n      \"weight\": 1850\n    },\n    {\n      \"timestamp\": \"2026-10-19T13:44:00Z\",\n      \"type\": \"ACTUAL\",\n      \"status\": \"Departed\",\n      \"location\": \"Chongqing Jiangbei International Airport\",\n      \"locationCode\": \"CKG\",\n      \"vessel\": null,\n      \"voyage\": null,\n      \"flight\": \"Y87001\",\n      \"pieces\": 120,\n      \"weight\": 1850\n    },\n    {\n      \"timestamp\": \"2026-10-19T18:52:00Z\",\n      \"type\": \"ACTUAL\",\n      \"status\": \"Arrived\",\n      \"location\": \"Amsterdam Airport Schiphol\",\n      \"locationCode\": \"AMS\",\n      \"vessel\": null,\n      \"voyage\": null,\n      \"flight\": \"Y87001\",\n      \"pieces\": 120,\n      \"weight\": 1850\n    },\n    {\n      \"timestamp\": \"2026-10-20T10:15:00Z\",\n      \"type\": \"ACTUAL\",\n      \"status\": \"Delivered\",\n      \"location\": \"Amsterdam Airport Schiphol\",\n      \"locationCode\": \"AMS\",\n      \"vessel\": null,\n      \"voyage\": null,\n      \"flight\": null,\n      \"pieces\": 120,\n      \"weight\": 1850\n    }\n  ],\n  \"etaHistory\": [],\n  \"vessel\": null\n}"
                },
                {
                  "status": 200,
                  "label": "include=customer,tags",
                  "contentType": "application/json",
                  "body": "{\n  \"id\": \"8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07\",\n  \"identifier\": \"MEDU1234562\",\n  \"mode\": \"OCEAN\",\n  \"status\": \"active\",\n  \"carrier\": \"MSC\",\n  \"containers\": [\n    {\n      \"containerNumber\": \"MEDU1234562\",\n      \"containerType\": \"40HC\",\n      \"status\": \"DEPARTED\",\n      \"etd\": \"2026-09-26T22:00:00Z\",\n      \"atd\": \"2026-09-27T03:40:00Z\",\n      \"eta\": \"2026-10-30T06:00:00Z\",\n      \"ata\": null,\n      \"origin\": {\n        \"code\": \"CNSHA\",\n        \"name\": \"Shanghai\"\n      },\n      \"destination\": {\n        \"code\": \"TRAMR\",\n        \"name\": \"Ambarli\"\n      },\n      \"currentVessel\": \"MSC MARTINA\"\n    }\n  ],\n  \"airShipments\": [],\n  \"events\": [\n    {\n      \"timestamp\": \"2026-09-24T14:12:00Z\",\n      \"type\": \"ACTUAL\",\n      \"status\": \"GATE_IN\",\n      \"location\": \"Shanghai\",\n      \"locationCode\": \"CNSHA\",\n      \"vessel\": null,\n      \"voyage\": null,\n      \"flight\": null,\n      \"pieces\": null,\n      \"weight\": null\n    },\n    {\n      \"timestamp\": \"2026-09-26T21:30:00Z\",\n      \"type\": \"ACTUAL\",\n      \"status\": \"LOADED\",\n      \"location\": \"Shanghai\",\n      \"locationCode\": \"CNSHA\",\n      \"vessel\": \"MSC MARTINA\",\n      \"voyage\": \"438W\",\n      \"flight\": null,\n      \"pieces\": null,\n      \"weight\": null\n    },\n    {\n      \"timestamp\": \"2026-09-27T03:40:00Z\",\n      \"type\": \"ACTUAL\",\n      \"status\": \"DEPARTED\",\n      \"location\": \"Shanghai\",\n      \"locationCode\": \"CNSHA\",\n      \"vessel\": \"MSC MARTINA\",\n      \"voyage\": \"438W\",\n      \"flight\": null,\n      \"pieces\": null,\n      \"weight\": null\n    },\n    {\n      \"timestamp\": \"2026-10-23T08:00:00Z\",\n      \"type\": \"EXPECTED\",\n      \"status\": \"TRANSSHIPMENT\",\n      \"location\": \"Piraeus\",\n      \"locationCode\": \"GRPIR\",\n      \"vessel\": \"MSC MARTINA\",\n      \"voyage\": \"438W\",\n      \"flight\": null,\n      \"pieces\": null,\n      \"weight\": null\n    },\n    {\n      \"timestamp\": \"2026-10-27T18:00:00Z\",\n      \"type\": \"EXPECTED\",\n      \"status\": \"DEPARTED\",\n      \"location\": \"Piraeus\",\n      \"locationCode\": \"GRPIR\",\n      \"vessel\": \"MSC ARIANE\",\n      \"voyage\": \"IP243A\",\n      \"flight\": null,\n      \"pieces\": null,\n      \"weight\": null\n    },\n    {\n      \"timestamp\": \"2026-10-30T06:00:00Z\",\n      \"type\": \"EXPECTED\",\n      \"status\": \"ARRIVED\",\n      \"location\": \"Ambarli\",\n      \"locationCode\": \"TRAMR\",\n      \"vessel\": \"MSC ARIANE\",\n      \"voyage\": \"IP243A\",\n      \"flight\": null,\n      \"pieces\": null,\n      \"weight\": null\n    }\n  ],\n  \"etaHistory\": [\n    {\n      \"field\": \"ETA\",\n      \"previousValue\": \"2026-10-27T06:00:00Z\",\n      \"newValue\": \"2026-10-30T06:00:00Z\",\n      \"deltaHours\": 72,\n      \"recordedAt\": \"2026-10-14T09:22:14Z\",\n      \"containerNumber\": \"MEDU1234562\",\n      \"awbNumber\": null\n    },\n    {\n      \"field\": \"ETA\",\n      \"previousValue\": \"2026-10-25T06:00:00Z\",\n      \"newValue\": \"2026-10-27T06:00:00Z\",\n      \"deltaHours\": 48,\n      \"recordedAt\": \"2026-10-03T11:05:39Z\",\n      \"containerNumber\": \"MEDU1234562\",\n      \"awbNumber\": null\n    }\n  ],\n  \"vessel\": {\n    \"vesselName\": \"MSC MARTINA\",\n    \"latitude\": 34.9123,\n    \"longitude\": 25.6342,\n    \"heading\": 318,\n    \"source\": \"LIVE\",\n    \"reportedAt\": \"2026-10-22T05:41:00Z\"\n  },\n  \"customer\": {\n    \"id\": \"c7d2a9e4-3f1b-4e8a-9b6c-1d5e7f3a2b90\",\n    \"ref\": \"C-1042\",\n    \"name\": \"Acme Trading Ltd.\",\n    \"countryCode\": \"TR\"\n  },\n  \"tags\": [\n    {\n      \"id\": \"a3f9c2d1-7b4e-4c8a-9e16-2d5f8b0c7e41\",\n      \"name\": \"Priority\",\n      \"color\": \"#ef4444\"\n    },\n    {\n      \"id\": \"b81e4d7a-2c9f-4a63-8d05-6e3b1f9c2a77\",\n      \"name\": \"Q4 launch\",\n      \"color\": \"#3b82f6\"\n    }\n  ]\n}"
                }
              ],
              "errors": [
                {
                  "status": 404,
                  "message": "Shipment not found",
                  "when": "Unknown id, deleted, or another organization’s shipment."
                },
                {
                  "status": 400,
                  "message": "Unknown include 'eta'. Allowed values: risk, recommendations, navloEta, dnd, carbon, alerts, customer, tags, details, all",
                  "when": "An `include` value outside the list — checked first, so even for an id that doesn’t exist."
                },
                {
                  "status": 401,
                  "message": "Invalid or revoked API key",
                  "when": "The X-API-Key header is missing, wrong or revoked."
                },
                {
                  "status": 429,
                  "message": "Rate limit exceeded (60 requests/minute)",
                  "when": "Over the per-key budget; wait Retry-After seconds."
                }
              ],
              "notes": []
            },
            {
              "kind": "endpoint",
              "id": "shipments-update",
              "method": "PATCH",
              "path": "/v1/shipments/{id}",
              "summary": "Update a shipment",
              "description": [
                "Changes the shipment’s customer. A key you leave out is not changed; `\"customer\": null` removes the customer. Usage already recorded follows the change: the usage report attributes a shipment’s credits to its customer at the time you run the report."
              ],
              "auth": "apiKey",
              "rateLimit": "general",
              "since": "2026-10-22",
              "pathParams": [
                {
                  "name": "id",
                  "type": "uuid",
                  "required": true,
                  "description": "The shipment id."
                }
              ],
              "queryParams": [],
              "headers": [],
              "body": {
                "contentType": "application/json",
                "fields": [
                  {
                    "name": "customer",
                    "type": "object | null",
                    "required": false,
                    "description": "The new customer (`{ \"id\" }` or `{ \"ref\", \"name\" }`), or `null` to clear it."
                  },
                  {
                    "name": "customer.id",
                    "type": "uuid",
                    "required": false,
                    "description": "A Navlo customer id from [`GET /v1/customers`](/developers/customers#customers-list). Wins when both `id` and `ref` are sent."
                  },
                  {
                    "name": "customer.ref",
                    "type": "string",
                    "required": false,
                    "description": "Your own code for the customer (max 100 characters, case-insensitive, trimmed). An unknown ref creates the customer."
                  },
                  {
                    "name": "customer.name",
                    "type": "string",
                    "required": false,
                    "description": "Name used only when the ref creates a new customer. Defaults to the ref. Never renames an existing customer."
                  }
                ]
              },
              "response": {
                "status": 200,
                "contentType": "application/json",
                "fields": [
                  {
                    "name": "id",
                    "type": "uuid",
                    "description": "The shipment id."
                  },
                  {
                    "name": "customer",
                    "type": "object",
                    "nullable": true,
                    "description": "The shipment’s customer after the change."
                  },
                  {
                    "name": "customer.id",
                    "type": "uuid",
                    "description": "Navlo’s customer id."
                  },
                  {
                    "name": "customer.ref",
                    "type": "string",
                    "nullable": true,
                    "description": "Your reference for the customer, when it has one."
                  },
                  {
                    "name": "customer.name",
                    "type": "string",
                    "description": "The customer’s name, as shown on the Companies page."
                  },
                  {
                    "name": "customer.countryCode",
                    "type": "string",
                    "nullable": true,
                    "description": "ISO 3166-1 alpha-2 country code, e.g. `TR`."
                  }
                ]
              },
              "requestExamples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl -X PATCH \"https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"customer\": {\n      \"ref\": \"C-1042\",\n      \"name\": \"Acme Trading Ltd.\"\n    }\n  }'"
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const res = await fetch('https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07', {\n  method: 'PATCH',\n  headers: {\n    'X-API-Key': process.env.NAVLO_API_KEY,\n    'Content-Type': 'application/json',\n  },\n  body: JSON.stringify({ customer: { ref: 'C-1042', name: 'Acme Trading Ltd.' } }),\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\nconst shipment = await res.json()"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.patch(\n    \"https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    json={\"customer\": {\"ref\": \"C-1042\", \"name\": \"Acme Trading Ltd.\"}},\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\nshipment = r.json()"
                }
              ],
              "responseExamples": [
                {
                  "status": 200,
                  "contentType": "application/json",
                  "body": "{\n  \"id\": \"8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07\",\n  \"customer\": {\n    \"id\": \"c7d2a9e4-3f1b-4e8a-9b6c-1d5e7f3a2b90\",\n    \"ref\": \"C-1042\",\n    \"name\": \"Acme Trading Ltd.\",\n    \"countryCode\": \"TR\"\n  }\n}"
                },
                {
                  "status": 200,
                  "label": "customer: null",
                  "contentType": "application/json",
                  "body": "{\n  \"id\": \"8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07\",\n  \"customer\": null\n}"
                }
              ],
              "errors": [
                {
                  "status": 404,
                  "message": "Shipment not found",
                  "when": "Unknown id, deleted, or another organization’s shipment."
                },
                {
                  "status": 400,
                  "message": "Unknown customer id",
                  "when": "`customer.id` is not one of your customers."
                },
                {
                  "status": 400,
                  "message": "customer needs an id or a ref",
                  "when": "`customer` was sent without `id` or `ref`."
                },
                {
                  "status": 400,
                  "message": "Request body is missing or is not valid JSON",
                  "when": "The body could not be parsed."
                },
                {
                  "status": 401,
                  "message": "Invalid or revoked API key",
                  "when": "The X-API-Key header is missing, wrong or revoked."
                },
                {
                  "status": 429,
                  "message": "Rate limit exceeded (60 requests/minute)",
                  "when": "Over the per-key budget; wait Retry-After seconds."
                }
              ],
              "notes": []
            },
            {
              "kind": "endpoint",
              "id": "shipments-route",
              "method": "GET",
              "path": "/v1/shipments/{id}/route",
              "summary": "Route geometry (GeoJSON)",
              "description": [
                "The line Navlo draws on the shipment map: sea legs follow real shipping lanes, inland rail and truck legs are straight, and the two never merge into one line. Air shipments get one straight `AIR` feature per flight leg between the airports (draw the arc yourself) and a null vessel. It has its own endpoint because the geometry is computed, not stored, and runs to hundreds of coordinate pairs — polling the detail never pays for it."
              ],
              "auth": "apiKey",
              "rateLimit": "general",
              "pathParams": [
                {
                  "name": "id",
                  "type": "uuid",
                  "required": true,
                  "description": "The shipment id."
                }
              ],
              "queryParams": [],
              "headers": [],
              "response": {
                "status": 200,
                "contentType": "application/json",
                "fields": [
                  {
                    "name": "shipmentId",
                    "type": "uuid",
                    "description": "The shipment id."
                  },
                  {
                    "name": "ports",
                    "type": "array<object>",
                    "description": "Ports called at, in order: loading, transshipments, discharge. Air: the airports of the legs."
                  },
                  {
                    "name": "ports[].code",
                    "type": "string",
                    "nullable": true,
                    "description": "UN/LOCODE or IATA code."
                  },
                  {
                    "name": "ports[].name",
                    "type": "string",
                    "nullable": true,
                    "description": "Port or airport name."
                  },
                  {
                    "name": "ports[].latitude",
                    "type": "number",
                    "description": "Latitude."
                  },
                  {
                    "name": "ports[].longitude",
                    "type": "number",
                    "description": "Longitude."
                  },
                  {
                    "name": "geojson",
                    "type": "object",
                    "description": "A GeoJSON FeatureCollection with one LineString Feature per leg. Coordinates are `[longitude, latitude]` — GeoJSON order, the reverse of every other field in this API."
                  },
                  {
                    "name": "geojson.features[].properties.kind",
                    "type": "enum",
                    "description": "The leg’s transport.",
                    "values": [
                      "SEA",
                      "LAND",
                      "AIR"
                    ]
                  },
                  {
                    "name": "vessel",
                    "type": "object",
                    "nullable": true,
                    "description": "Same shape and rules as `vessel` on the detail."
                  }
                ]
              },
              "requestExamples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl \"https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/route\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\""
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const res = await fetch('https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/route', {\n  headers: { 'X-API-Key': process.env.NAVLO_API_KEY },\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\nconst route = await res.json()"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.get(\n    \"https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/route\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\nroute = r.json()"
                }
              ],
              "responseExamples": [
                {
                  "status": 200,
                  "contentType": "application/json",
                  "body": "{\n  \"shipmentId\": \"8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07\",\n  \"ports\": [\n    {\n      \"code\": \"CNSHA\",\n      \"name\": \"Shanghai\",\n      \"latitude\": 31.2304,\n      \"longitude\": 121.4737\n    },\n    {\n      \"code\": \"GRPIR\",\n      \"name\": \"Piraeus\",\n      \"latitude\": 37.9421,\n      \"longitude\": 23.6465\n    },\n    {\n      \"code\": \"TRAMR\",\n      \"name\": \"Ambarli\",\n      \"latitude\": 40.9667,\n      \"longitude\": 28.6833\n    }\n  ],\n  \"geojson\": {\n    \"type\": \"FeatureCollection\",\n    \"features\": [\n      {\n        \"type\": \"Feature\",\n        \"properties\": {\n          \"kind\": \"SEA\"\n        },\n        \"geometry\": {\n          \"type\": \"LineString\",\n          \"coordinates\": [\n            [\n              121.4737,\n              31.2304\n            ],\n            [\n              122.6,\n              29.1\n            ],\n            [\n              114.3,\n              21.4\n            ],\n            [\n              103.9,\n              1.2\n            ],\n            [\n              80.1,\n              5.6\n            ],\n            [\n              51.2,\n              12.4\n            ],\n            [\n              43.4,\n              12.6\n            ],\n            [\n              32.5,\n              29.9\n            ],\n            [\n              32.3,\n              31.3\n            ],\n            [\n              23.6465,\n              37.9421\n            ]\n          ]\n        }\n      },\n      {\n        \"type\": \"Feature\",\n        \"properties\": {\n          \"kind\": \"SEA\"\n        },\n        \"geometry\": {\n          \"type\": \"LineString\",\n          \"coordinates\": [\n            [\n              23.6465,\n              37.9421\n            ],\n            [\n              25.4,\n              39.4\n            ],\n            [\n              26.4,\n              40.1\n            ],\n            [\n              28.6833,\n              40.9667\n            ]\n          ]\n        }\n      }\n    ]\n  },\n  \"vessel\": {\n    \"vesselName\": \"MSC MARTINA\",\n    \"latitude\": 34.9123,\n    \"longitude\": 25.6342,\n    \"heading\": 318,\n    \"source\": \"LIVE\",\n    \"reportedAt\": \"2026-10-22T05:41:00Z\"\n  }\n}"
                }
              ],
              "errors": [
                {
                  "status": 404,
                  "message": "Shipment not found",
                  "when": "Unknown id, deleted, or another organization’s shipment."
                },
                {
                  "status": 404,
                  "message": "No route available for this shipment yet",
                  "when": "Nothing on the shipment is geocoded yet (e.g. still discovering)."
                },
                {
                  "status": 401,
                  "message": "Invalid or revoked API key",
                  "when": "The X-API-Key header is missing, wrong or revoked."
                },
                {
                  "status": 429,
                  "message": "Rate limit exceeded (60 requests/minute)",
                  "when": "Over the per-key budget; wait Retry-After seconds."
                }
              ],
              "notes": []
            },
            {
              "kind": "endpoint",
              "id": "shipments-stop",
              "method": "POST",
              "path": "/v1/shipments/{id}/stop",
              "summary": "Pause tracking",
              "description": [
                "Stops polling the carrier. The shipment, its history and its status stay as they are, and you can resume at any time. Idempotent: stopping a stopped shipment is a `200`."
              ],
              "auth": "apiKey",
              "rateLimit": "general",
              "pathParams": [
                {
                  "name": "id",
                  "type": "uuid",
                  "required": true,
                  "description": "The shipment id."
                }
              ],
              "queryParams": [],
              "headers": [],
              "response": {
                "status": 200,
                "contentType": "application/json",
                "fields": [
                  {
                    "name": "id",
                    "type": "uuid",
                    "description": "The shipment id."
                  },
                  {
                    "name": "polling",
                    "type": "enum",
                    "description": "Always `stopped`.",
                    "values": [
                      "stopped"
                    ]
                  }
                ]
              },
              "requestExamples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl -X POST \"https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/stop\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\""
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const res = await fetch('https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/stop', {\n  method: 'POST',\n  headers: { 'X-API-Key': process.env.NAVLO_API_KEY },\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\nconst result = await res.json()"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.post(\n    \"https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/stop\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\nresult = r.json()"
                }
              ],
              "responseExamples": [
                {
                  "status": 200,
                  "contentType": "application/json",
                  "body": "{\n  \"id\": \"8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07\",\n  \"polling\": \"stopped\"\n}"
                }
              ],
              "errors": [
                {
                  "status": 404,
                  "message": "Shipment not found",
                  "when": "Unknown id, deleted, or another organization’s shipment."
                },
                {
                  "status": 401,
                  "message": "Invalid or revoked API key",
                  "when": "The X-API-Key header is missing, wrong or revoked."
                },
                {
                  "status": 429,
                  "message": "Rate limit exceeded (60 requests/minute)",
                  "when": "Over the per-key budget; wait Retry-After seconds."
                }
              ],
              "notes": [
                "Pausing does not change `status` (`stopped` means Navlo can’t track the identifier). `details.pollingStoppedAt` ([include](/developers/shipment-intelligence#intelligence-details)) shows a pause."
              ]
            },
            {
              "kind": "endpoint",
              "id": "shipments-resume",
              "method": "POST",
              "path": "/v1/shipments/{id}/resume",
              "summary": "Resume tracking",
              "description": [
                "Re-arms polling and asks the carrier for fresh data straight away. Idempotent."
              ],
              "auth": "apiKey",
              "rateLimit": "general",
              "pathParams": [
                {
                  "name": "id",
                  "type": "uuid",
                  "required": true,
                  "description": "The shipment id."
                }
              ],
              "queryParams": [],
              "headers": [],
              "response": {
                "status": 200,
                "contentType": "application/json",
                "fields": [
                  {
                    "name": "id",
                    "type": "uuid",
                    "description": "The shipment id."
                  },
                  {
                    "name": "polling",
                    "type": "enum",
                    "description": "Always `active`.",
                    "values": [
                      "active"
                    ]
                  }
                ]
              },
              "requestExamples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl -X POST \"https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/resume\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\""
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const res = await fetch('https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/resume', {\n  method: 'POST',\n  headers: { 'X-API-Key': process.env.NAVLO_API_KEY },\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\nconst result = await res.json()"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.post(\n    \"https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/resume\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\nresult = r.json()"
                }
              ],
              "responseExamples": [
                {
                  "status": 200,
                  "contentType": "application/json",
                  "body": "{\n  \"id\": \"8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07\",\n  \"polling\": \"active\"\n}"
                }
              ],
              "errors": [
                {
                  "status": 404,
                  "message": "Shipment not found",
                  "when": "Unknown id, deleted, or another organization’s shipment."
                },
                {
                  "status": 401,
                  "message": "Invalid or revoked API key",
                  "when": "The X-API-Key header is missing, wrong or revoked."
                },
                {
                  "status": 429,
                  "message": "Rate limit exceeded (60 requests/minute)",
                  "when": "Over the per-key budget; wait Retry-After seconds."
                }
              ],
              "notes": []
            },
            {
              "kind": "endpoint",
              "id": "shipments-delete",
              "method": "DELETE",
              "path": "/v1/shipments/{id}",
              "summary": "Delete a shipment",
              "description": [
                "Removes the shipment and everything under it — containers, events, notes, documents, tags. Credits already spent are not refunded. To stop updates but keep the record, [pause](#shipments-stop) instead; it can be undone."
              ],
              "auth": "apiKey",
              "rateLimit": "general",
              "pathParams": [
                {
                  "name": "id",
                  "type": "uuid",
                  "required": true,
                  "description": "The shipment id."
                }
              ],
              "queryParams": [],
              "headers": [],
              "response": {
                "status": 204,
                "contentType": "",
                "description": "No body.",
                "fields": []
              },
              "requestExamples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl -X DELETE \"https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\""
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const res = await fetch('https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07', {\n  method: 'DELETE',\n  headers: { 'X-API-Key': process.env.NAVLO_API_KEY },\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\n// 204 No Content: nothing to parse"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.delete(\n    \"https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\n# 204 No Content: nothing to parse"
                }
              ],
              "responseExamples": [
                {
                  "status": 204,
                  "contentType": "",
                  "body": ""
                }
              ],
              "errors": [
                {
                  "status": 404,
                  "message": "Shipment not found",
                  "when": "Unknown id, deleted, or another organization’s shipment."
                },
                {
                  "status": 401,
                  "message": "Invalid or revoked API key",
                  "when": "The X-API-Key header is missing, wrong or revoked."
                },
                {
                  "status": 429,
                  "message": "Rate limit exceeded (60 requests/minute)",
                  "when": "Over the per-key budget; wait Retry-After seconds."
                }
              ],
              "notes": []
            },
            {
              "kind": "heading",
              "id": "shipments-sync",
              "title": "Keeping your system in sync"
            },
            {
              "kind": "prose",
              "text": "Two patterns keep a copy of your shipments current. Most integrations use both: webhooks for speed, a periodic sync as the safety net."
            },
            {
              "kind": "list",
              "ordered": false,
              "items": [
                "**Push** — subscribe to [webhooks](/developers/webhooks). Each event carries the shipment snapshot and what changed; fetch the detail when you need the full picture.",
                "**Pull** — every few minutes, list with `updatedSince=<start of your previous run>&sort=updatedAt` and refresh the shipments it returns. `lastChangedAt` (`include=lastChangedAt`) tells you the exact change time per shipment."
              ]
            },
            {
              "kind": "callout",
              "tone": "info",
              "title": "What counts as a change",
              "text": "Ocean shipments count as changed only when their status, ETA or discovery outcome changes. Air shipments can also appear in `updatedSince` results with no visible change — compare what you stored and skip those. A shipment with no recorded change falls back to its last update time."
            },
            {
              "kind": "code",
              "title": "Incremental sync",
              "samples": [
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "import { readFile, writeFile } from 'node:fs/promises'\n\n// Incremental sync: everything that changed since the last run, oldest change first.\nconst since = await readFile('last-sync.txt', 'utf8').catch(() => '2026-10-01T00:00:00Z')\nconst startedAt = new Date().toISOString()\n\nfor (let page = 0; ; page++) {\n  const params = new URLSearchParams({ updatedSince: since, sort: 'updatedAt', size: '100', page: String(page) })\n  const res = await fetch(`https://api.navlo.io/v1/shipments?${params}`, {\n    headers: { 'X-API-Key': process.env.NAVLO_API_KEY },\n  })\n  if (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\n  const { shipments, totalPages } = await res.json()\n  for (const s of shipments) await upsertShipment(s.id) // e.g. fetch GET /v1/shipments/{id} and store it\n  if (page + 1 >= totalPages) break\n}\n\nawait writeFile('last-sync.txt', startedAt) // the NEXT run starts from when this one started"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport pathlib\nfrom datetime import datetime, timezone\nimport requests\n\nstate = pathlib.Path(\"last-sync.txt\")\nsince = state.read_text() if state.exists() else \"2026-10-01T00:00:00Z\"\nstarted_at = datetime.now(timezone.utc).isoformat().replace(\"+00:00\", \"Z\")\n\npage = 0\nwhile True:\n    r = requests.get(\n        \"https://api.navlo.io/v1/shipments\",\n        headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n        params={\"updatedSince\": since, \"sort\": \"updatedAt\", \"size\": 100, \"page\": page},\n        timeout=30,\n    )\n    if not r.ok:\n        raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\n    body = r.json()\n    for s in body[\"shipments\"]:\n        upsert_shipment(s[\"id\"])  # e.g. GET /v1/shipments/{id} and store it\n    page += 1\n    if page >= body[\"totalPages\"]:\n        break\n\nstate.write_text(started_at)  # the NEXT run starts from when this one started"
                }
              ]
            },
            {
              "kind": "callout",
              "tone": "tip",
              "text": "Store the time a run **started** as the next `updatedSince`, not the time it finished — changes that land while you page are then picked up next time instead of being skipped."
            }
          ]
        },
        {
          "id": "shipment-intelligence",
          "title": "Shipment intelligence",
          "summary": "Risk, Navlo’s own ETA, D&D, carbon, recommendations and route alerts — the signals the app shows, opt-in per request.",
          "blocks": [
            {
              "kind": "prose",
              "text": "Navlo adds its own analysis on top of carrier data. Ask for it with `include` on [`GET /v1/shipments/{id}`](/developers/shipments#shipments-get): a requested key is always present in the response (`null` or `[]` when there is nothing), and a request without `include` is unchanged. These are the same signals the app shows on the shipment page."
            },
            {
              "kind": "definitions",
              "items": [
                {
                  "term": "`risk`",
                  "description": "Risk level, score and the reason. Nothing known: `level: null, stale: true`."
                },
                {
                  "term": "`recommendations`",
                  "description": "The action cards the app shows. None: `[]`."
                },
                {
                  "term": "`navloEta`",
                  "description": "Navlo’s predicted arrival per container. None (and always for air): `[]`."
                },
                {
                  "term": "`dnd`",
                  "description": "Free time, demurrage and storage. No data: `available: false`."
                },
                {
                  "term": "`carbon`",
                  "description": "CO₂e for the shipment and each unit. No figure: `co2eKg: null`."
                },
                {
                  "term": "`alerts`",
                  "description": "Storms, quakes and security incidents near the route. None: `[]`."
                },
                {
                  "term": "`customer`",
                  "description": "The shipment’s customer, or `null`."
                },
                {
                  "term": "`tags`",
                  "description": "The shipment’s tags, or `[]`."
                },
                {
                  "term": "`details`",
                  "description": "Terminals, vessel IMO, the next connection, polling times."
                },
                {
                  "term": "`all`",
                  "description": "Every block above."
                }
              ]
            },
            {
              "kind": "code",
              "title": "Request",
              "samples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl \"https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07?include=all\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\""
                }
              ]
            },
            {
              "kind": "code",
              "title": "Response",
              "samples": [
                {
                  "lang": "json",
                  "label": "200 OK · include=all",
                  "code": "{\n  \"id\": \"8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07\",\n  \"identifier\": \"MEDU1234562\",\n  \"mode\": \"OCEAN\",\n  \"status\": \"active\",\n  \"carrier\": \"MSC\",\n  \"containers\": [\n    {\n      \"containerNumber\": \"MEDU1234562\",\n      \"containerType\": \"40HC\",\n      \"status\": \"DEPARTED\",\n      \"etd\": \"2026-09-26T22:00:00Z\",\n      \"atd\": \"2026-09-27T03:40:00Z\",\n      \"eta\": \"2026-10-30T06:00:00Z\",\n      \"ata\": null,\n      \"origin\": {\n        \"code\": \"CNSHA\",\n        \"name\": \"Shanghai\"\n      },\n      \"destination\": {\n        \"code\": \"TRAMR\",\n        \"name\": \"Ambarli\"\n      },\n      \"currentVessel\": \"MSC MARTINA\"\n    }\n  ],\n  \"airShipments\": [],\n  \"events\": [\n    {\n      \"timestamp\": \"2026-09-24T14:12:00Z\",\n      \"type\": \"ACTUAL\",\n      \"status\": \"GATE_IN\",\n      \"location\": \"Shanghai\",\n      \"locationCode\": \"CNSHA\",\n      \"vessel\": null,\n      \"voyage\": null,\n      \"flight\": null,\n      \"pieces\": null,\n      \"weight\": null\n    },\n    {\n      \"timestamp\": \"2026-09-26T21:30:00Z\",\n      \"type\": \"ACTUAL\",\n      \"status\": \"LOADED\",\n      \"location\": \"Shanghai\",\n      \"locationCode\": \"CNSHA\",\n      \"vessel\": \"MSC MARTINA\",\n      \"voyage\": \"438W\",\n      \"flight\": null,\n      \"pieces\": null,\n      \"weight\": null\n    },\n    {\n      \"timestamp\": \"2026-09-27T03:40:00Z\",\n      \"type\": \"ACTUAL\",\n      \"status\": \"DEPARTED\",\n      \"location\": \"Shanghai\",\n      \"locationCode\": \"CNSHA\",\n      \"vessel\": \"MSC MARTINA\",\n      \"voyage\": \"438W\",\n      \"flight\": null,\n      \"pieces\": null,\n      \"weight\": null\n    },\n    {\n      \"timestamp\": \"2026-10-23T08:00:00Z\",\n      \"type\": \"EXPECTED\",\n      \"status\": \"TRANSSHIPMENT\",\n      \"location\": \"Piraeus\",\n      \"locationCode\": \"GRPIR\",\n      \"vessel\": \"MSC MARTINA\",\n      \"voyage\": \"438W\",\n      \"flight\": null,\n      \"pieces\": null,\n      \"weight\": null\n    },\n    {\n      \"timestamp\": \"2026-10-27T18:00:00Z\",\n      \"type\": \"EXPECTED\",\n      \"status\": \"DEPARTED\",\n      \"location\": \"Piraeus\",\n      \"locationCode\": \"GRPIR\",\n      \"vessel\": \"MSC ARIANE\",\n      \"voyage\": \"IP243A\",\n      \"flight\": null,\n      \"pieces\": null,\n      \"weight\": null\n    },\n    {\n      \"timestamp\": \"2026-10-30T06:00:00Z\",\n      \"type\": \"EXPECTED\",\n      \"status\": \"ARRIVED\",\n      \"location\": \"Ambarli\",\n      \"locationCode\": \"TRAMR\",\n      \"vessel\": \"MSC ARIANE\",\n      \"voyage\": \"IP243A\",\n      \"flight\": null,\n      \"pieces\": null,\n      \"weight\": null\n    }\n  ],\n  \"etaHistory\": [\n    {\n      \"field\": \"ETA\",\n      \"previousValue\": \"2026-10-27T06:00:00Z\",\n      \"newValue\": \"2026-10-30T06:00:00Z\",\n      \"deltaHours\": 72,\n      \"recordedAt\": \"2026-10-14T09:22:14Z\",\n      \"containerNumber\": \"MEDU1234562\",\n      \"awbNumber\": null\n    },\n    {\n      \"field\": \"ETA\",\n      \"previousValue\": \"2026-10-25T06:00:00Z\",\n      \"newValue\": \"2026-10-27T06:00:00Z\",\n      \"deltaHours\": 48,\n      \"recordedAt\": \"2026-10-03T11:05:39Z\",\n      \"containerNumber\": \"MEDU1234562\",\n      \"awbNumber\": null\n    }\n  ],\n  \"vessel\": {\n    \"vesselName\": \"MSC MARTINA\",\n    \"latitude\": 34.9123,\n    \"longitude\": 25.6342,\n    \"heading\": 318,\n    \"source\": \"LIVE\",\n    \"reportedAt\": \"2026-10-22T05:41:00Z\"\n  },\n  \"risk\": {\n    \"level\": \"MEDIUM\",\n    \"score\": 52,\n    \"summary\": \"ETA slipped 5 days since departure; the Piraeus transshipment is congested.\",\n    \"computedAt\": \"2026-10-22T07:15:00Z\",\n    \"stale\": false\n  },\n  \"recommendations\": [\n    {\n      \"id\": \"eta:8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07\",\n      \"severity\": \"HIGH\",\n      \"title\": \"ETA at Ambarli slipped 3 days\",\n      \"impact\": \"Arrival moves from 27 Oct to 30 Oct, and free time at Ambarli now starts on 30 Oct.\",\n      \"recommendation\": \"Tell Acme Trading Ltd. the new arrival date and move the delivery truck to 31 Oct.\",\n      \"kind\": \"eta\",\n      \"confidence\": \"HIGH\",\n      \"computedAt\": \"2026-10-14T09:30:02Z\"\n    },\n    {\n      \"id\": \"congestion:GRPIR\",\n      \"severity\": \"MEDIUM\",\n      \"title\": \"Congestion at Piraeus, your transshipment port\",\n      \"impact\": \"Vessels are waiting about 1.8 days at anchorage, against a 0.6-day baseline.\",\n      \"recommendation\": \"Expect the MSC ARIANE connection on 27 Oct to slip; check the next feeder sailing.\",\n      \"kind\": \"congestion\",\n      \"confidence\": \"MEDIUM\",\n      \"computedAt\": \"2026-10-22T07:18:41Z\"\n    }\n  ],\n  \"navloEta\": [\n    {\n      \"containerNumber\": \"MEDU1234562\",\n      \"predictedEta\": \"2026-10-31T02:00:00Z\",\n      \"confidence\": \"MEDIUM\",\n      \"computedAt\": \"2026-10-22T05:42:19Z\",\n      \"carrierEta\": \"2026-10-30T06:00:00Z\"\n    }\n  ],\n  \"dnd\": {\n    \"available\": true,\n    \"source\": \"CARRIER\",\n    \"freeTimeStartAt\": \"2026-10-30T06:00:00Z\",\n    \"freeTimeEndsAt\": \"2026-11-06T00:00:00Z\",\n    \"freeTimeStarted\": false,\n    \"freeTimeDaysLeft\": null,\n    \"demurrageDaysSoFar\": null,\n    \"demurrageStoppedAt\": null,\n    \"carrierFreeTimeDays\": 7,\n    \"carrierFreeTimeBasis\": \"Calendar Days\"\n  },\n  \"carbon\": {\n    \"co2eKg\": 1856.4,\n    \"source\": \"GLEC\",\n    \"units\": [\n      {\n        \"containerNumber\": \"MEDU1234562\",\n        \"awbNumber\": null,\n        \"co2eKg\": 1856.4,\n        \"source\": \"GLEC\"\n      }\n    ]\n  },\n  \"alerts\": [\n    {\n      \"type\": \"EARTHQUAKE\",\n      \"severity\": \"MEDIUM\",\n      \"title\": \"Earthquake near the route\",\n      \"description\": \"Medium-severity earthquake reported near this shipment's route on 21 Oct 2026.\",\n      \"location\": {\n        \"name\": null,\n        \"code\": null,\n        \"latitude\": 34.71,\n        \"longitude\": 24.93\n      },\n      \"startsAt\": \"2026-10-21T19:42:00Z\",\n      \"endsAt\": null\n    }\n  ],\n  \"customer\": {\n    \"id\": \"c7d2a9e4-3f1b-4e8a-9b6c-1d5e7f3a2b90\",\n    \"ref\": \"C-1042\",\n    \"name\": \"Acme Trading Ltd.\",\n    \"countryCode\": \"TR\"\n  },\n  \"tags\": [\n    {\n      \"id\": \"a3f9c2d1-7b4e-4c8a-9e16-2d5f8b0c7e41\",\n      \"name\": \"Priority\",\n      \"color\": \"#ef4444\"\n    },\n    {\n      \"id\": \"b81e4d7a-2c9f-4a63-8d05-6e3b1f9c2a77\",\n      \"name\": \"Q4 launch\",\n      \"color\": \"#3b82f6\"\n    }\n  ],\n  \"details\": {\n    \"lastCarrierEventAt\": \"2026-09-27T03:40:00Z\",\n    \"pollingStoppedAt\": null,\n    \"notificationsMuted\": false,\n    \"relatedIdentifiers\": [\n      \"MEDUSH448021\",\n      \"177SHA2611987\"\n    ],\n    \"containers\": [\n      {\n        \"containerNumber\": \"MEDU1234562\",\n        \"originTerminal\": \"Yangshan Deep Water Port Phase IV\",\n        \"destinationTerminal\": \"Marport Ambarli\",\n        \"originCountryCode\": \"CN\",\n        \"destinationCountryCode\": \"TR\",\n        \"currentLocation\": \"Shanghai\",\n        \"currentLocationCode\": \"CNSHA\",\n        \"vesselImo\": \"9461805\",\n        \"voyage\": \"438W\",\n        \"aboardVessel\": true,\n        \"nextPlannedVessel\": {\n          \"vesselName\": \"MSC ARIANE\",\n          \"voyageNumber\": \"IP243A\",\n          \"plannedAt\": \"2026-10-27T18:00:00Z\",\n          \"portName\": \"Piraeus\",\n          \"portCode\": \"GRPIR\"\n        },\n        \"transshipmentPorts\": [\n          {\n            \"code\": \"GRPIR\",\n            \"name\": \"Piraeus\"\n          }\n        ]\n      }\n    ],\n    \"airShipments\": []\n  }\n}"
                }
              ]
            },
            {
              "kind": "heading",
              "id": "intelligence-risk",
              "title": "risk"
            },
            {
              "kind": "prose",
              "text": "Navlo’s risk assessment for the shipment. It is shown only while it is current, on a shipment that is not completed. Anything else reads `level: null` and `stale: true` — Navlo never reports `LOW` for a risk it doesn’t know."
            },
            {
              "kind": "code",
              "samples": [
                {
                  "lang": "json",
                  "label": "risk",
                  "code": "{\n  \"risk\": {\n    \"level\": \"MEDIUM\",\n    \"score\": 52,\n    \"summary\": \"ETA slipped 5 days since departure; the Piraeus transshipment is congested.\",\n    \"computedAt\": \"2026-10-22T07:15:00Z\",\n    \"stale\": false\n  }\n}"
                }
              ]
            },
            {
              "kind": "fields",
              "fields": [
                {
                  "name": "risk.level",
                  "type": "enum",
                  "nullable": true,
                  "description": "The shipment’s risk while it is fresh; null when stale, never computed, or still discovering.",
                  "values": [
                    "LOW",
                    "MEDIUM",
                    "HIGH"
                  ]
                },
                {
                  "name": "risk.score",
                  "type": "integer",
                  "nullable": true,
                  "description": "0–100. LOW is 0–29, MEDIUM 30–69, HIGH 70–100. Null when `level` is null."
                },
                {
                  "name": "risk.summary",
                  "type": "string",
                  "nullable": true,
                  "description": "One sentence on what drives the risk, as the app shows it. Null when `level` is null."
                },
                {
                  "name": "risk.computedAt",
                  "type": "timestamp",
                  "nullable": true,
                  "description": "When Navlo last assessed the risk (UTC)."
                },
                {
                  "name": "risk.stale",
                  "type": "boolean",
                  "description": "`true` when there is no current assessment — `level` is then null."
                }
              ]
            },
            {
              "kind": "heading",
              "id": "intelligence-recommendations",
              "title": "recommendations"
            },
            {
              "kind": "prose",
              "text": "The cards from the app’s recommendation feed for this shipment, most severe first. Completed shipments only keep D&D and idle-container cards."
            },
            {
              "kind": "code",
              "samples": [
                {
                  "lang": "json",
                  "label": "recommendations",
                  "code": "{\n  \"recommendations\": [\n    {\n      \"id\": \"eta:8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07\",\n      \"severity\": \"HIGH\",\n      \"title\": \"ETA at Ambarli slipped 3 days\",\n      \"impact\": \"Arrival moves from 27 Oct to 30 Oct, and free time at Ambarli now starts on 30 Oct.\",\n      \"recommendation\": \"Tell Acme Trading Ltd. the new arrival date and move the delivery truck to 31 Oct.\",\n      \"kind\": \"eta\",\n      \"confidence\": \"HIGH\",\n      \"computedAt\": \"2026-10-14T09:30:02Z\"\n    },\n    {\n      \"id\": \"congestion:GRPIR\",\n      \"severity\": \"MEDIUM\",\n      \"title\": \"Congestion at Piraeus, your transshipment port\",\n      \"impact\": \"Vessels are waiting about 1.8 days at anchorage, against a 0.6-day baseline.\",\n      \"recommendation\": \"Expect the MSC ARIANE connection on 27 Oct to slip; check the next feeder sailing.\",\n      \"kind\": \"congestion\",\n      \"confidence\": \"MEDIUM\",\n      \"computedAt\": \"2026-10-22T07:18:41Z\"\n    }\n  ]\n}"
                }
              ]
            },
            {
              "kind": "fields",
              "fields": [
                {
                  "name": "recommendations[].id",
                  "type": "string",
                  "description": "Stable id of the card — the same card keeps its id across refreshes."
                },
                {
                  "name": "recommendations[].severity",
                  "type": "enum",
                  "description": "How urgent. `INFO` marks purely informational cards.",
                  "values": [
                    "CRITICAL",
                    "HIGH",
                    "MEDIUM",
                    "LOW",
                    "INFO"
                  ]
                },
                {
                  "name": "recommendations[].title",
                  "type": "string",
                  "description": "Headline."
                },
                {
                  "name": "recommendations[].impact",
                  "type": "string",
                  "description": "What it means for this shipment."
                },
                {
                  "name": "recommendations[].recommendation",
                  "type": "string",
                  "description": "What to do about it."
                },
                {
                  "name": "recommendations[].kind",
                  "type": "string",
                  "description": "Category of the signal. Treat unknown values generically.",
                  "values": [
                    "eta",
                    "congestion",
                    "dnd",
                    "idle",
                    "risk",
                    "storm",
                    "quake",
                    "volcano",
                    "incident",
                    "live_tracking",
                    "ais_detected"
                  ]
                },
                {
                  "name": "recommendations[].confidence",
                  "type": "enum",
                  "description": "How sure Navlo is.",
                  "values": [
                    "HIGH",
                    "MEDIUM",
                    "LOW"
                  ]
                },
                {
                  "name": "recommendations[].computedAt",
                  "type": "timestamp",
                  "description": "When the card’s text was last produced (UTC)."
                }
              ]
            },
            {
              "kind": "heading",
              "id": "intelligence-navlo-eta",
              "title": "navloEta"
            },
            {
              "kind": "prose",
              "text": "Navlo’s own arrival prediction for each live ocean container; `confidence` says how far to trust it. Always `[]` for air shipments."
            },
            {
              "kind": "code",
              "samples": [
                {
                  "lang": "json",
                  "label": "navloEta",
                  "code": "{\n  \"navloEta\": [\n    {\n      \"containerNumber\": \"MEDU1234562\",\n      \"predictedEta\": \"2026-10-31T02:00:00Z\",\n      \"confidence\": \"MEDIUM\",\n      \"computedAt\": \"2026-10-22T05:42:19Z\",\n      \"carrierEta\": \"2026-10-30T06:00:00Z\"\n    }\n  ]\n}"
                }
              ]
            },
            {
              "kind": "fields",
              "fields": [
                {
                  "name": "navloEta[].containerNumber",
                  "type": "string",
                  "description": "The container — one entry per live container."
                },
                {
                  "name": "navloEta[].predictedEta",
                  "type": "timestamp",
                  "nullable": true,
                  "description": "Navlo’s predicted arrival at the port of discharge; null when Navlo has no trustworthy prediction (then `confidence` and `computedAt` are null too)."
                },
                {
                  "name": "navloEta[].confidence",
                  "type": "enum",
                  "nullable": true,
                  "description": "How far to trust `predictedEta`.",
                  "values": [
                    "HIGH",
                    "MEDIUM",
                    "LOW"
                  ]
                },
                {
                  "name": "navloEta[].computedAt",
                  "type": "timestamp",
                  "nullable": true,
                  "description": "When the prediction last changed (UTC)."
                },
                {
                  "name": "navloEta[].carrierEta",
                  "type": "timestamp",
                  "nullable": true,
                  "description": "The carrier’s ETA at the same moment, for comparison."
                }
              ]
            },
            {
              "kind": "heading",
              "id": "intelligence-dnd",
              "title": "dnd"
            },
            {
              "kind": "prose",
              "text": "Free time and demurrage (ocean) or storage (air) at destination. The deadline comes from the first available source: free time your team set, the carrier’s published free time, then your accepted tariff."
            },
            {
              "kind": "code",
              "samples": [
                {
                  "lang": "json",
                  "label": "dnd",
                  "code": "{\n  \"dnd\": {\n    \"available\": true,\n    \"source\": \"CARRIER\",\n    \"freeTimeStartAt\": \"2026-10-30T06:00:00Z\",\n    \"freeTimeEndsAt\": \"2026-11-06T00:00:00Z\",\n    \"freeTimeStarted\": false,\n    \"freeTimeDaysLeft\": null,\n    \"demurrageDaysSoFar\": null,\n    \"demurrageStoppedAt\": null,\n    \"carrierFreeTimeDays\": 7,\n    \"carrierFreeTimeBasis\": \"Calendar Days\"\n  }\n}"
                }
              ]
            },
            {
              "kind": "fields",
              "fields": [
                {
                  "name": "dnd.available",
                  "type": "boolean",
                  "description": "`true` when there is a free-time window or a carrier allowance; `false` otherwise, and every other field is then null."
                },
                {
                  "name": "dnd.source",
                  "type": "enum",
                  "nullable": true,
                  "description": "Where the free time comes from: `CARRIER` (the carrier’s own free time), `MANUAL` (set by your team), `SYSTEM` (your accepted tariff).",
                  "values": [
                    "CARRIER",
                    "MANUAL",
                    "SYSTEM"
                  ]
                },
                {
                  "name": "dnd.freeTimeStartAt",
                  "type": "timestamp",
                  "nullable": true,
                  "description": "When the free-time clock starts — the discharge (or ETA while still sailing) for ocean, cargo availability for air."
                },
                {
                  "name": "dnd.freeTimeEndsAt",
                  "type": "timestamp",
                  "nullable": true,
                  "description": "When free time ends; demurrage or storage charges start after it. Falls back to the carrier’s published expiry when no window could be anchored."
                },
                {
                  "name": "dnd.freeTimeStarted",
                  "type": "boolean",
                  "description": "`true` once the cargo has actually arrived and the clock runs."
                },
                {
                  "name": "dnd.freeTimeDaysLeft",
                  "type": "integer",
                  "nullable": true,
                  "description": "Calendar days of free time left while the clock runs (started, not yet ended); null before it starts and after it ends."
                },
                {
                  "name": "dnd.demurrageDaysSoFar",
                  "type": "integer",
                  "nullable": true,
                  "description": "Days past the end of free time — day 1 is the first chargeable day. Null while still free."
                },
                {
                  "name": "dnd.demurrageStoppedAt",
                  "type": "timestamp",
                  "nullable": true,
                  "description": "When charges stopped accruing (empty container returned, or shipment completed)."
                },
                {
                  "name": "dnd.carrierFreeTimeDays",
                  "type": "integer",
                  "nullable": true,
                  "description": "Free days the carrier grants, when it publishes them."
                },
                {
                  "name": "dnd.carrierFreeTimeBasis",
                  "type": "string",
                  "nullable": true,
                  "description": "The carrier’s own wording for how days count, e.g. `Calendar Days`, `Working Days`."
                }
              ]
            },
            {
              "kind": "heading",
              "id": "intelligence-carbon",
              "title": "carbon"
            },
            {
              "kind": "prose",
              "text": "CO₂e for the shipment and each unit: Navlo’s GLEC Framework estimate, or the carrier’s own published figure (`source` says which)."
            },
            {
              "kind": "code",
              "samples": [
                {
                  "lang": "json",
                  "label": "carbon",
                  "code": "{\n  \"carbon\": {\n    \"co2eKg\": 1856.4,\n    \"source\": \"GLEC\",\n    \"units\": [\n      {\n        \"containerNumber\": \"MEDU1234562\",\n        \"awbNumber\": null,\n        \"co2eKg\": 1856.4,\n        \"source\": \"GLEC\"\n      }\n    ]\n  }\n}"
                }
              ]
            },
            {
              "kind": "fields",
              "fields": [
                {
                  "name": "carbon.co2eKg",
                  "type": "number",
                  "nullable": true,
                  "description": "The shipment’s CO₂e in kilograms — the sum of the units that have a figure; null when none has."
                },
                {
                  "name": "carbon.source",
                  "type": "enum",
                  "nullable": true,
                  "description": "`GLEC` — Navlo’s GLEC Framework estimate. `CARRIER` — the carrier’s own published figure. Null when units disagree.",
                  "values": [
                    "GLEC",
                    "CARRIER"
                  ]
                },
                {
                  "name": "carbon.units",
                  "type": "array<object>",
                  "description": "One per live container (ocean) or waybill (air), with or without a figure."
                },
                {
                  "name": "carbon.units[].containerNumber",
                  "type": "string",
                  "nullable": true,
                  "description": "OCEAN: the container; null on air units."
                },
                {
                  "name": "carbon.units[].awbNumber",
                  "type": "string",
                  "nullable": true,
                  "description": "AIR: the waybill; null on ocean units."
                },
                {
                  "name": "carbon.units[].co2eKg",
                  "type": "number",
                  "nullable": true,
                  "description": "That unit’s CO₂e in kg, or null when it can’t be computed yet."
                },
                {
                  "name": "carbon.units[].source",
                  "type": "enum",
                  "nullable": true,
                  "description": "As above, per unit.",
                  "values": [
                    "GLEC",
                    "CARRIER"
                  ]
                }
              ]
            },
            {
              "kind": "heading",
              "id": "intelligence-alerts",
              "title": "alerts"
            },
            {
              "kind": "prose",
              "text": "Natural hazards and maritime security incidents within 500 km of the shipment’s route — what the shipment map shows. At most 20, recent ones only. With none available right now you get `[]`, never an error."
            },
            {
              "kind": "code",
              "samples": [
                {
                  "lang": "json",
                  "label": "alerts",
                  "code": "{\n  \"alerts\": [\n    {\n      \"type\": \"EARTHQUAKE\",\n      \"severity\": \"MEDIUM\",\n      \"title\": \"Earthquake near the route\",\n      \"description\": \"Medium-severity earthquake reported near this shipment's route on 21 Oct 2026.\",\n      \"location\": {\n        \"name\": null,\n        \"code\": null,\n        \"latitude\": 34.71,\n        \"longitude\": 24.93\n      },\n      \"startsAt\": \"2026-10-21T19:42:00Z\",\n      \"endsAt\": null\n    }\n  ]\n}"
                }
              ]
            },
            {
              "kind": "fields",
              "fields": [
                {
                  "name": "alerts[].type",
                  "type": "enum",
                  "description": "Hazard category. `SECURITY` covers piracy, attacks and other maritime security incidents. Treat unknown values as `OTHER`.",
                  "values": [
                    "TROPICAL_CYCLONE",
                    "EARTHQUAKE",
                    "FLOOD",
                    "TSUNAMI",
                    "VOLCANO",
                    "DROUGHT",
                    "WILDFIRE",
                    "SECURITY",
                    "OTHER"
                  ]
                },
                {
                  "name": "alerts[].severity",
                  "type": "enum",
                  "description": "Alert level. Low-level alerts are not returned.",
                  "values": [
                    "MEDIUM",
                    "HIGH",
                    "CRITICAL"
                  ]
                },
                {
                  "name": "alerts[].title",
                  "type": "string",
                  "description": "A short headline from the type, e.g. \"Earthquake near the route\"."
                },
                {
                  "name": "alerts[].description",
                  "type": "string",
                  "nullable": true,
                  "description": "One sentence with the severity and the date."
                },
                {
                  "name": "alerts[].location",
                  "type": "object",
                  "nullable": true,
                  "description": "Where it is: `latitude` and `longitude` (`name` and `code` are null for these point alerts)."
                },
                {
                  "name": "alerts[].startsAt",
                  "type": "timestamp",
                  "nullable": true,
                  "description": "When the alert was published (UTC)."
                },
                {
                  "name": "alerts[].endsAt",
                  "type": "timestamp",
                  "nullable": true,
                  "description": "When it ends; null when unknown."
                }
              ]
            },
            {
              "kind": "heading",
              "id": "intelligence-customer-tags",
              "title": "customer and tags"
            },
            {
              "kind": "code",
              "samples": [
                {
                  "lang": "json",
                  "label": "customer, tags",
                  "code": "{\n  \"customer\": {\n    \"id\": \"c7d2a9e4-3f1b-4e8a-9b6c-1d5e7f3a2b90\",\n    \"ref\": \"C-1042\",\n    \"name\": \"Acme Trading Ltd.\",\n    \"countryCode\": \"TR\"\n  },\n  \"tags\": [\n    {\n      \"id\": \"a3f9c2d1-7b4e-4c8a-9e16-2d5f8b0c7e41\",\n      \"name\": \"Priority\",\n      \"color\": \"#ef4444\"\n    },\n    {\n      \"id\": \"b81e4d7a-2c9f-4a63-8d05-6e3b1f9c2a77\",\n      \"name\": \"Q4 launch\",\n      \"color\": \"#3b82f6\"\n    }\n  ]\n}"
                }
              ]
            },
            {
              "kind": "fields",
              "fields": [
                {
                  "name": "customer",
                  "type": "object",
                  "nullable": true,
                  "description": "The shipment’s customer, or null."
                },
                {
                  "name": "customer.id",
                  "type": "uuid",
                  "description": "Navlo’s customer id."
                },
                {
                  "name": "customer.ref",
                  "type": "string",
                  "nullable": true,
                  "description": "Your reference for the customer, when it has one."
                },
                {
                  "name": "customer.name",
                  "type": "string",
                  "description": "The customer’s name, as shown on the Companies page."
                },
                {
                  "name": "customer.countryCode",
                  "type": "string",
                  "nullable": true,
                  "description": "ISO 3166-1 alpha-2 country code, e.g. `TR`."
                },
                {
                  "name": "tags",
                  "type": "array<object>",
                  "description": "The shipment’s tags."
                },
                {
                  "name": "tags[].id",
                  "type": "uuid",
                  "description": "Tag id."
                },
                {
                  "name": "tags[].name",
                  "type": "string",
                  "description": "Tag name."
                },
                {
                  "name": "tags[].color",
                  "type": "string",
                  "nullable": true,
                  "description": "Hex colour, e.g. `#ef4444`."
                }
              ]
            },
            {
              "kind": "heading",
              "id": "intelligence-details",
              "title": "details"
            },
            {
              "kind": "prose",
              "text": "Operational detail the app shows on the shipment page: terminals, the vessel’s IMO, the next connection, and Navlo’s polling times."
            },
            {
              "kind": "code",
              "samples": [
                {
                  "lang": "json",
                  "label": "details",
                  "code": "{\n  \"details\": {\n    \"lastCarrierEventAt\": \"2026-09-27T03:40:00Z\",\n    \"pollingStoppedAt\": null,\n    \"notificationsMuted\": false,\n    \"relatedIdentifiers\": [\n      \"MEDUSH448021\",\n      \"177SHA2611987\"\n    ],\n    \"containers\": [\n      {\n        \"containerNumber\": \"MEDU1234562\",\n        \"originTerminal\": \"Yangshan Deep Water Port Phase IV\",\n        \"destinationTerminal\": \"Marport Ambarli\",\n        \"originCountryCode\": \"CN\",\n        \"destinationCountryCode\": \"TR\",\n        \"currentLocation\": \"Shanghai\",\n        \"currentLocationCode\": \"CNSHA\",\n        \"vesselImo\": \"9461805\",\n        \"voyage\": \"438W\",\n        \"aboardVessel\": true,\n        \"nextPlannedVessel\": {\n          \"vesselName\": \"MSC ARIANE\",\n          \"voyageNumber\": \"IP243A\",\n          \"plannedAt\": \"2026-10-27T18:00:00Z\",\n          \"portName\": \"Piraeus\",\n          \"portCode\": \"GRPIR\"\n        },\n        \"transshipmentPorts\": [\n          {\n            \"code\": \"GRPIR\",\n            \"name\": \"Piraeus\"\n          }\n        ]\n      }\n    ],\n    \"airShipments\": []\n  }\n}"
                }
              ]
            },
            {
              "kind": "fields",
              "fields": [
                {
                  "name": "details.lastCarrierEventAt",
                  "type": "timestamp",
                  "nullable": true,
                  "description": "The newest event the carrier reported — use it to spot carriers that went quiet."
                },
                {
                  "name": "details.pollingStoppedAt",
                  "type": "timestamp",
                  "nullable": true,
                  "description": "Set while tracking is paused ([stop](/developers/shipments#shipments-stop))."
                },
                {
                  "name": "details.notificationsMuted",
                  "type": "boolean",
                  "description": "Whether the shipment’s emails and in-app notifications are muted. Webhooks fire regardless."
                },
                {
                  "name": "details.relatedIdentifiers",
                  "type": "array<string>",
                  "description": "Other numbers Navlo linked to the shipment — its B/L, booking, sibling containers."
                },
                {
                  "name": "details.containers",
                  "type": "array<object>",
                  "description": "OCEAN: per-container detail beyond the base response."
                },
                {
                  "name": "details.containers[].originTerminal",
                  "type": "string",
                  "nullable": true,
                  "description": "Terminal at the port of loading."
                },
                {
                  "name": "details.containers[].destinationTerminal",
                  "type": "string",
                  "nullable": true,
                  "description": "Terminal at the port of discharge."
                },
                {
                  "name": "details.containers[].originCountryCode",
                  "type": "string",
                  "nullable": true,
                  "description": "ISO alpha-2 country of the port of loading."
                },
                {
                  "name": "details.containers[].destinationCountryCode",
                  "type": "string",
                  "nullable": true,
                  "description": "ISO alpha-2 country of the port of discharge."
                },
                {
                  "name": "details.containers[].currentLocation",
                  "type": "string",
                  "nullable": true,
                  "description": "Where the container was last reported."
                },
                {
                  "name": "details.containers[].currentLocationCode",
                  "type": "string",
                  "nullable": true,
                  "description": "UN/LOCODE of that place."
                },
                {
                  "name": "details.containers[].vesselImo",
                  "type": "string",
                  "nullable": true,
                  "description": "IMO number of the current vessel."
                },
                {
                  "name": "details.containers[].voyage",
                  "type": "string",
                  "nullable": true,
                  "description": "Current voyage number."
                },
                {
                  "name": "details.containers[].aboardVessel",
                  "type": "boolean",
                  "description": "`true` when the container is verifiably on the vessel now (loaded and not yet discharged)."
                },
                {
                  "name": "details.containers[].nextPlannedVessel",
                  "type": "object",
                  "nullable": true,
                  "description": "The next connection, when known: `{ vesselName, voyageNumber, plannedAt, portName, portCode }`."
                },
                {
                  "name": "details.containers[].transshipmentPorts",
                  "type": "array<object>",
                  "description": "Transshipment ports in order, `[{ code, name }]`."
                },
                {
                  "name": "details.airShipments",
                  "type": "array<object>",
                  "description": "AIR: `[{ awbNumber }]`."
                }
              ]
            },
            {
              "kind": "heading",
              "id": "intelligence-list-includes",
              "title": "On the shipment list"
            },
            {
              "kind": "prose",
              "text": "[`GET /v1/shipments`](/developers/shipments#shipments-list) takes a lighter `include`: `customer`, `tags`, `risk` (level, computedAt and stale only) and `lastChangedAt`, so a list screen needs one request."
            },
            {
              "kind": "fields",
              "fields": [
                {
                  "name": "shipments[].customer",
                  "type": "object",
                  "nullable": true,
                  "description": "With `include=customer`: the shipment’s customer (`id`, `ref`, `name`, `countryCode`), or null."
                },
                {
                  "name": "shipments[].tags",
                  "type": "array<object>",
                  "description": "With `include=tags`: the shipment’s tags, `[{ id, name, color }]`."
                },
                {
                  "name": "shipments[].risk",
                  "type": "object",
                  "description": "With `include=risk`: `{ level, computedAt, stale }` — the same freshness rule as the detail’s [risk](/developers/shipment-intelligence#intelligence-risk)."
                },
                {
                  "name": "shipments[].lastChangedAt",
                  "type": "timestamp",
                  "nullable": true,
                  "description": "With `include=lastChangedAt`: when the shipment’s data last changed — the value `updatedSince` and `sort=updatedAt` use. If no change is recorded yet, it falls back to the shipment’s last update time."
                }
              ]
            }
          ]
        },
        {
          "id": "shipment-actions",
          "title": "Shipment actions",
          "summary": "Notes, documents, share links, email subscribers, mute, complete and change carrier — everything the shipment page lets your team do.",
          "blocks": [
            {
              "kind": "prose",
              "text": "Every action here is what the shipment page in the app does, with the same rules. All routes take the shipment id and answer `404 Shipment not found` for ids outside your organization. Tags have [their own page](/developers/tags)."
            },
            {
              "kind": "heading",
              "id": "actions-notes",
              "title": "Notes"
            },
            {
              "kind": "prose",
              "text": "Team notes on a shipment, newest first. Notes written through the API are authored by the key’s creator, and — as in the app — only the author can edit or delete a note. Mention a teammate with `@[<user id>|Name]` to notify them."
            },
            {
              "kind": "endpoint",
              "id": "actions-notes-list",
              "method": "GET",
              "path": "/v1/shipments/{id}/notes",
              "summary": "List notes",
              "description": [
                "The shipment’s notes, newest first."
              ],
              "auth": "apiKey",
              "rateLimit": "general",
              "since": "2026-10-22",
              "pathParams": [
                {
                  "name": "id",
                  "type": "uuid",
                  "required": true,
                  "description": "The shipment id."
                }
              ],
              "queryParams": [
                {
                  "name": "page",
                  "type": "integer",
                  "required": false,
                  "description": "Zero-based page index.",
                  "defaultValue": "0"
                },
                {
                  "name": "size",
                  "type": "integer",
                  "required": false,
                  "description": "Page size, 1–100.",
                  "defaultValue": "20"
                }
              ],
              "headers": [],
              "response": {
                "status": 200,
                "contentType": "application/json",
                "fields": [
                  {
                    "name": "page",
                    "type": "integer",
                    "description": "Page index."
                  },
                  {
                    "name": "size",
                    "type": "integer",
                    "description": "Page size."
                  },
                  {
                    "name": "totalElements",
                    "type": "integer",
                    "description": "Notes on the shipment."
                  },
                  {
                    "name": "totalPages",
                    "type": "integer",
                    "description": "Pages at this size."
                  },
                  {
                    "name": "notes",
                    "type": "array<object>",
                    "description": "The notes; fields as on [create](#actions-notes-create)."
                  }
                ]
              },
              "requestExamples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl \"https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/notes\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\""
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const res = await fetch('https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/notes', {\n  headers: { 'X-API-Key': process.env.NAVLO_API_KEY },\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\nconst notes = await res.json()"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.get(\n    \"https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/notes\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\nnotes = r.json()"
                }
              ],
              "responseExamples": [
                {
                  "status": 200,
                  "contentType": "application/json",
                  "body": "{\n  \"page\": 0,\n  \"size\": 20,\n  \"totalElements\": 1,\n  \"totalPages\": 1,\n  \"notes\": [\n    {\n      \"id\": \"e2c7a9f1-4b3d-4e8c-a1f6-9d0b5c7e3a28\",\n      \"content\": \"Customs broker confirmed the import declaration for Ambarli. Truck booked for 31 Oct.\",\n      \"authorName\": \"Elif Yılmaz\",\n      \"createdAt\": \"2026-10-22T08:31:07Z\",\n      \"updatedAt\": \"2026-10-22T08:31:07Z\"\n    }\n  ]\n}"
                }
              ],
              "errors": [
                {
                  "status": 404,
                  "message": "Shipment not found",
                  "when": "Unknown id, deleted, or another organization’s shipment."
                },
                {
                  "status": 401,
                  "message": "Invalid or revoked API key",
                  "when": "The X-API-Key header is missing, wrong or revoked."
                },
                {
                  "status": 429,
                  "message": "Rate limit exceeded (60 requests/minute)",
                  "when": "Over the per-key budget; wait Retry-After seconds."
                }
              ],
              "notes": []
            },
            {
              "kind": "endpoint",
              "id": "actions-notes-create",
              "method": "POST",
              "path": "/v1/shipments/{id}/notes",
              "summary": "Add a note",
              "description": [],
              "auth": "apiKey",
              "rateLimit": "general",
              "since": "2026-10-22",
              "pathParams": [
                {
                  "name": "id",
                  "type": "uuid",
                  "required": true,
                  "description": "The shipment id."
                }
              ],
              "queryParams": [],
              "headers": [],
              "body": {
                "contentType": "application/json",
                "fields": [
                  {
                    "name": "content",
                    "type": "string",
                    "required": true,
                    "description": "The note, up to 10,000 characters."
                  }
                ]
              },
              "response": {
                "status": 201,
                "contentType": "application/json",
                "fields": [
                  {
                    "name": "id",
                    "type": "uuid",
                    "description": "Note id."
                  },
                  {
                    "name": "content",
                    "type": "string",
                    "description": "The note text."
                  },
                  {
                    "name": "authorName",
                    "type": "string",
                    "description": "Who wrote it — for API notes, the key’s creator."
                  },
                  {
                    "name": "createdAt",
                    "type": "timestamp",
                    "description": "When it was written (UTC)."
                  },
                  {
                    "name": "updatedAt",
                    "type": "timestamp",
                    "description": "When it was last edited — equal to `createdAt` until then."
                  }
                ]
              },
              "requestExamples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl -X POST \"https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/notes\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"content\": \"Customs broker confirmed the import declaration for Ambarli. Truck booked for 31 Oct.\"\n  }'"
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const res = await fetch('https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/notes', {\n  method: 'POST',\n  headers: {\n    'X-API-Key': process.env.NAVLO_API_KEY,\n    'Content-Type': 'application/json',\n  },\n  body: JSON.stringify({\n    content: 'Customs broker confirmed the import declaration for Ambarli. Truck booked for 31 Oct.',\n  }),\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\nconst note = await res.json()"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.post(\n    \"https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/notes\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    json={\n        \"content\": \"Customs broker confirmed the import declaration for Ambarli. Truck booked for 31 Oct.\",\n    },\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\nnote = r.json()"
                }
              ],
              "responseExamples": [
                {
                  "status": 201,
                  "contentType": "application/json",
                  "body": "{\n  \"id\": \"e2c7a9f1-4b3d-4e8c-a1f6-9d0b5c7e3a28\",\n  \"content\": \"Customs broker confirmed the import declaration for Ambarli. Truck booked for 31 Oct.\",\n  \"authorName\": \"Elif Yılmaz\",\n  \"createdAt\": \"2026-10-22T08:31:07Z\",\n  \"updatedAt\": \"2026-10-22T08:31:07Z\"\n}"
                }
              ],
              "errors": [
                {
                  "status": 404,
                  "message": "Shipment not found",
                  "when": "Unknown id, deleted, or another organization’s shipment."
                },
                {
                  "status": 400,
                  "message": "content is required",
                  "when": "`content` missing or blank."
                },
                {
                  "status": 400,
                  "message": "content must be at most 10000 characters",
                  "when": "Over 10,000 characters."
                },
                {
                  "status": 401,
                  "message": "Invalid or revoked API key",
                  "when": "The X-API-Key header is missing, wrong or revoked."
                },
                {
                  "status": 429,
                  "message": "Rate limit exceeded (60 requests/minute)",
                  "when": "Over the per-key budget; wait Retry-After seconds."
                }
              ],
              "notes": []
            },
            {
              "kind": "endpoint",
              "id": "actions-notes-update",
              "method": "PUT",
              "path": "/v1/shipments/{id}/notes/{noteId}",
              "summary": "Edit a note",
              "description": [],
              "auth": "apiKey",
              "rateLimit": "general",
              "since": "2026-10-22",
              "pathParams": [
                {
                  "name": "id",
                  "type": "uuid",
                  "required": true,
                  "description": "The shipment id."
                },
                {
                  "name": "noteId",
                  "type": "uuid",
                  "required": true,
                  "description": "The note id."
                }
              ],
              "queryParams": [],
              "headers": [],
              "body": {
                "contentType": "application/json",
                "fields": [
                  {
                    "name": "content",
                    "type": "string",
                    "required": true,
                    "description": "The new text, up to 10,000 characters."
                  }
                ]
              },
              "response": {
                "status": 200,
                "contentType": "application/json",
                "fields": [
                  {
                    "name": "id",
                    "type": "uuid",
                    "description": "Note id."
                  },
                  {
                    "name": "content",
                    "type": "string",
                    "description": "The note text."
                  },
                  {
                    "name": "authorName",
                    "type": "string",
                    "description": "Who wrote it — for API notes, the key’s creator."
                  },
                  {
                    "name": "createdAt",
                    "type": "timestamp",
                    "description": "When it was written (UTC)."
                  },
                  {
                    "name": "updatedAt",
                    "type": "timestamp",
                    "description": "When it was last edited — equal to `createdAt` until then."
                  }
                ]
              },
              "requestExamples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl -X PUT \"https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/notes/e2c7a9f1-4b3d-4e8c-a1f6-9d0b5c7e3a28\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"content\": \"Customs cleared. Truck booked for 31 Oct, 09:00.\"\n  }'"
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const res = await fetch('https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/notes/e2c7a9f1-4b3d-4e8c-a1f6-9d0b5c7e3a28', {\n  method: 'PUT',\n  headers: {\n    'X-API-Key': process.env.NAVLO_API_KEY,\n    'Content-Type': 'application/json',\n  },\n  body: JSON.stringify({ content: 'Customs cleared. Truck booked for 31 Oct, 09:00.' }),\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\nconst note = await res.json()"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.put(\n    \"https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/notes/e2c7a9f1-4b3d-4e8c-a1f6-9d0b5c7e3a28\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    json={\"content\": \"Customs cleared. Truck booked for 31 Oct, 09:00.\"},\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\nnote = r.json()"
                }
              ],
              "responseExamples": [
                {
                  "status": 200,
                  "contentType": "application/json",
                  "body": "{\n  \"id\": \"e2c7a9f1-4b3d-4e8c-a1f6-9d0b5c7e3a28\",\n  \"content\": \"Customs cleared. Truck booked for 31 Oct, 09:00.\",\n  \"authorName\": \"Elif Yılmaz\",\n  \"createdAt\": \"2026-10-22T08:31:07Z\",\n  \"updatedAt\": \"2026-10-22T10:02:44Z\"\n}"
                }
              ],
              "errors": [
                {
                  "status": 404,
                  "message": "Shipment not found",
                  "when": "Unknown id, deleted, or another organization’s shipment."
                },
                {
                  "status": 404,
                  "message": "Note not found",
                  "when": "Unknown note id on this shipment."
                },
                {
                  "status": 403,
                  "message": "You can only edit your own notes",
                  "when": "The note was written by someone else."
                },
                {
                  "status": 400,
                  "message": "content must be at most 10000 characters",
                  "when": "Over 10,000 characters."
                },
                {
                  "status": 401,
                  "message": "Invalid or revoked API key",
                  "when": "The X-API-Key header is missing, wrong or revoked."
                },
                {
                  "status": 429,
                  "message": "Rate limit exceeded (60 requests/minute)",
                  "when": "Over the per-key budget; wait Retry-After seconds."
                }
              ],
              "notes": []
            },
            {
              "kind": "endpoint",
              "id": "actions-notes-delete",
              "method": "DELETE",
              "path": "/v1/shipments/{id}/notes/{noteId}",
              "summary": "Delete a note",
              "description": [],
              "auth": "apiKey",
              "rateLimit": "general",
              "since": "2026-10-22",
              "pathParams": [
                {
                  "name": "id",
                  "type": "uuid",
                  "required": true,
                  "description": "The shipment id."
                },
                {
                  "name": "noteId",
                  "type": "uuid",
                  "required": true,
                  "description": "The note id."
                }
              ],
              "queryParams": [],
              "headers": [],
              "response": {
                "status": 204,
                "contentType": "",
                "description": "No body.",
                "fields": []
              },
              "requestExamples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl -X DELETE \"https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/notes/e2c7a9f1-4b3d-4e8c-a1f6-9d0b5c7e3a28\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\""
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const res = await fetch('https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/notes/e2c7a9f1-4b3d-4e8c-a1f6-9d0b5c7e3a28', {\n  method: 'DELETE',\n  headers: { 'X-API-Key': process.env.NAVLO_API_KEY },\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\n// 204 No Content: nothing to parse"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.delete(\n    \"https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/notes/e2c7a9f1-4b3d-4e8c-a1f6-9d0b5c7e3a28\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\n# 204 No Content: nothing to parse"
                }
              ],
              "responseExamples": [
                {
                  "status": 204,
                  "contentType": "",
                  "body": ""
                }
              ],
              "errors": [
                {
                  "status": 404,
                  "message": "Shipment not found",
                  "when": "Unknown id, deleted, or another organization’s shipment."
                },
                {
                  "status": 404,
                  "message": "Note not found",
                  "when": "Unknown note id on this shipment."
                },
                {
                  "status": 403,
                  "message": "You can only delete your own notes",
                  "when": "The note was written by someone else."
                },
                {
                  "status": 401,
                  "message": "Invalid or revoked API key",
                  "when": "The X-API-Key header is missing, wrong or revoked."
                },
                {
                  "status": 429,
                  "message": "Rate limit exceeded (60 requests/minute)",
                  "when": "Over the per-key budget; wait Retry-After seconds."
                }
              ],
              "notes": []
            },
            {
              "kind": "heading",
              "id": "actions-documents",
              "title": "Documents"
            },
            {
              "kind": "prose",
              "text": "Files on a shipment — bills of lading, invoices, packing lists. Up to 10 MB per file; allowed types: pdf, png, jpg, jpeg, csv, xlsx, xls, doc, docx, tiff, bmp. Anyone in your organization can delete a document."
            },
            {
              "kind": "endpoint",
              "id": "actions-documents-list",
              "method": "GET",
              "path": "/v1/shipments/{id}/documents",
              "summary": "List documents",
              "description": [],
              "auth": "apiKey",
              "rateLimit": "general",
              "since": "2026-10-22",
              "pathParams": [
                {
                  "name": "id",
                  "type": "uuid",
                  "required": true,
                  "description": "The shipment id."
                }
              ],
              "queryParams": [],
              "headers": [],
              "response": {
                "status": 200,
                "contentType": "application/json",
                "description": "An array of documents, newest first.",
                "fields": [
                  {
                    "name": "[].id",
                    "type": "uuid",
                    "description": "Document id."
                  },
                  {
                    "name": "[].fileName",
                    "type": "string",
                    "description": "The original file name."
                  },
                  {
                    "name": "[].documentType",
                    "type": "string",
                    "description": "The document’s type, e.g. `BILL_OF_LADING`."
                  },
                  {
                    "name": "[].contentType",
                    "type": "string",
                    "description": "Set by Navlo from the file extension (`application/pdf`, `image/png`, … — `application/octet-stream` for doc, docx, tiff and bmp)."
                  },
                  {
                    "name": "[].sizeBytes",
                    "type": "integer",
                    "description": "File size in bytes."
                  },
                  {
                    "name": "[].uploadedBy",
                    "type": "string",
                    "description": "Who uploaded it."
                  },
                  {
                    "name": "[].createdAt",
                    "type": "timestamp",
                    "description": "Upload time (UTC)."
                  }
                ]
              },
              "requestExamples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl \"https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/documents\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\""
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const res = await fetch('https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/documents', {\n  headers: { 'X-API-Key': process.env.NAVLO_API_KEY },\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\nconst documents = await res.json()"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.get(\n    \"https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/documents\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\ndocuments = r.json()"
                }
              ],
              "responseExamples": [
                {
                  "status": 200,
                  "contentType": "application/json",
                  "body": "[\n  {\n    \"id\": \"d4b8e1c3-6a2f-4d97-8c5e-1f0a3b7d9e62\",\n    \"fileName\": \"MEDUSH448021-bill-of-lading.pdf\",\n    \"documentType\": \"BILL_OF_LADING\",\n    \"contentType\": \"application/pdf\",\n    \"sizeBytes\": 284913,\n    \"uploadedBy\": \"Elif Yılmaz\",\n    \"createdAt\": \"2026-10-22T08:34:52Z\"\n  }\n]"
                }
              ],
              "errors": [
                {
                  "status": 404,
                  "message": "Shipment not found",
                  "when": "Unknown id, deleted, or another organization’s shipment."
                },
                {
                  "status": 401,
                  "message": "Invalid or revoked API key",
                  "when": "The X-API-Key header is missing, wrong or revoked."
                },
                {
                  "status": 429,
                  "message": "Rate limit exceeded (60 requests/minute)",
                  "when": "Over the per-key budget; wait Retry-After seconds."
                }
              ],
              "notes": []
            },
            {
              "kind": "endpoint",
              "id": "actions-documents-upload",
              "method": "POST",
              "path": "/v1/shipments/{id}/documents",
              "summary": "Upload a document",
              "description": [
                "Send the file as `multipart/form-data`."
              ],
              "auth": "apiKey",
              "rateLimit": "general",
              "since": "2026-10-22",
              "pathParams": [
                {
                  "name": "id",
                  "type": "uuid",
                  "required": true,
                  "description": "The shipment id."
                }
              ],
              "queryParams": [],
              "headers": [],
              "body": {
                "contentType": "multipart/form-data",
                "fields": [
                  {
                    "name": "file",
                    "type": "file",
                    "required": true,
                    "description": "The file, up to 10 MB. The type is taken from its extension."
                  },
                  {
                    "name": "documentType",
                    "type": "enum",
                    "required": false,
                    "description": "What the file is (case-insensitive) — the types the app offers.",
                    "values": [
                      "BILL_OF_LADING",
                      "INVOICE",
                      "PACKING_LIST",
                      "CUSTOMS_DECLARATION",
                      "OTHER"
                    ],
                    "defaultValue": "OTHER"
                  }
                ]
              },
              "response": {
                "status": 201,
                "contentType": "application/json",
                "fields": [
                  {
                    "name": "id",
                    "type": "uuid",
                    "description": "Document id."
                  },
                  {
                    "name": "fileName",
                    "type": "string",
                    "description": "The original file name."
                  },
                  {
                    "name": "documentType",
                    "type": "string",
                    "description": "The document’s type, e.g. `BILL_OF_LADING`."
                  },
                  {
                    "name": "contentType",
                    "type": "string",
                    "description": "Set by Navlo from the file extension (`application/pdf`, `image/png`, … — `application/octet-stream` for doc, docx, tiff and bmp)."
                  },
                  {
                    "name": "sizeBytes",
                    "type": "integer",
                    "description": "File size in bytes."
                  },
                  {
                    "name": "uploadedBy",
                    "type": "string",
                    "description": "Who uploaded it."
                  },
                  {
                    "name": "createdAt",
                    "type": "timestamp",
                    "description": "Upload time (UTC)."
                  }
                ]
              },
              "requestExamples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl -X POST \"https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/documents\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\" \\\n  -F \"file=@MEDUSH448021-bill-of-lading.pdf;type=application/pdf\" \\\n  -F \"documentType=BILL_OF_LADING\""
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "import { readFile } from 'node:fs/promises'\n\nconst form = new FormData()\nform.append('file', new Blob([await readFile('MEDUSH448021-bill-of-lading.pdf')], { type: 'application/pdf' }), 'MEDUSH448021-bill-of-lading.pdf')\nform.append('documentType', 'BILL_OF_LADING')\n\nconst res = await fetch('https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/documents', {\n  method: 'POST',\n  headers: { 'X-API-Key': process.env.NAVLO_API_KEY },\n  body: form,\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\nconst uploaded = await res.json()"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.post(\n    \"https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/documents\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    files={\"file\": (\"MEDUSH448021-bill-of-lading.pdf\", open(\"MEDUSH448021-bill-of-lading.pdf\", \"rb\"), \"application/pdf\")},\n    data={\"documentType\": \"BILL_OF_LADING\"},\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\nuploaded = r.json()"
                }
              ],
              "responseExamples": [
                {
                  "status": 201,
                  "contentType": "application/json",
                  "body": "{\n  \"id\": \"d4b8e1c3-6a2f-4d97-8c5e-1f0a3b7d9e62\",\n  \"fileName\": \"MEDUSH448021-bill-of-lading.pdf\",\n  \"documentType\": \"BILL_OF_LADING\",\n  \"contentType\": \"application/pdf\",\n  \"sizeBytes\": 284913,\n  \"uploadedBy\": \"Elif Yılmaz\",\n  \"createdAt\": \"2026-10-22T08:34:52Z\"\n}"
                }
              ],
              "errors": [
                {
                  "status": 404,
                  "message": "Shipment not found",
                  "when": "Unknown id, deleted, or another organization’s shipment."
                },
                {
                  "status": 400,
                  "message": "file is required",
                  "when": "No `file` part."
                },
                {
                  "status": 400,
                  "message": "File is empty",
                  "when": "A zero-byte file."
                },
                {
                  "status": 400,
                  "message": "documentType must be one of BILL_OF_LADING, INVOICE, PACKING_LIST, CUSTOMS_DECLARATION, OTHER",
                  "when": "Another `documentType`."
                },
                {
                  "status": 413,
                  "message": "The file is too large. The maximum upload size is 10 MB.",
                  "when": "Larger than 10 MB (general error shape, `error`: \"File too large\")."
                },
                {
                  "status": 400,
                  "message": "File type .gif is not allowed for documents. Allowed: .pdf, .png, .jpg, .jpeg, .csv, .xlsx, .xls, .doc, .docx, .tiff, .bmp",
                  "when": "An extension outside the list."
                },
                {
                  "status": 401,
                  "message": "Invalid or revoked API key",
                  "when": "The X-API-Key header is missing, wrong or revoked."
                },
                {
                  "status": 429,
                  "message": "Rate limit exceeded (60 requests/minute)",
                  "when": "Over the per-key budget; wait Retry-After seconds."
                }
              ],
              "notes": []
            },
            {
              "kind": "endpoint",
              "id": "actions-documents-download",
              "method": "GET",
              "path": "/v1/shipments/{id}/documents/{documentId}/download",
              "summary": "Get a download link",
              "description": [
                "Returns a short-lived link to the file. Fetch it with a plain GET — no API key — within 15 minutes. The link redirects to the file, so let your client follow redirects (`curl -L`).",
                "An expired link, or one whose document was deleted, answers `404` — ask for a new one."
              ],
              "auth": "apiKey",
              "rateLimit": "general",
              "since": "2026-10-22",
              "pathParams": [
                {
                  "name": "id",
                  "type": "uuid",
                  "required": true,
                  "description": "The shipment id."
                },
                {
                  "name": "documentId",
                  "type": "uuid",
                  "required": true,
                  "description": "The document id."
                }
              ],
              "queryParams": [],
              "headers": [],
              "response": {
                "status": 200,
                "contentType": "application/json",
                "fields": [
                  {
                    "name": "url",
                    "type": "string",
                    "description": "Download link on `api.navlo.io`. Anyone with it can download the file, so keep it private until it expires."
                  },
                  {
                    "name": "expiresAt",
                    "type": "timestamp",
                    "description": "When the link stops working (UTC), 15 minutes after the request."
                  }
                ]
              },
              "requestExamples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl \"https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/documents/d4b8e1c3-6a2f-4d97-8c5e-1f0a3b7d9e62/download\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\""
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const res = await fetch('https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/documents/d4b8e1c3-6a2f-4d97-8c5e-1f0a3b7d9e62/download', {\n  headers: { 'X-API-Key': process.env.NAVLO_API_KEY },\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\nconst link = await res.json()"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.get(\n    \"https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/documents/d4b8e1c3-6a2f-4d97-8c5e-1f0a3b7d9e62/download\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\nlink = r.json()"
                }
              ],
              "responseExamples": [
                {
                  "status": 200,
                  "contentType": "application/json",
                  "body": "{\n  \"url\": \"https://api.navlo.io/api/documents/d/AbC123.xYz789\",\n  \"expiresAt\": \"2026-10-22T09:15:00Z\"\n}"
                }
              ],
              "errors": [
                {
                  "status": 404,
                  "message": "Shipment not found",
                  "when": "Unknown id, deleted, or another organization’s shipment."
                },
                {
                  "status": 404,
                  "message": "Document not found",
                  "when": "Unknown document id on this shipment."
                },
                {
                  "status": 401,
                  "message": "Invalid or revoked API key",
                  "when": "The X-API-Key header is missing, wrong or revoked."
                },
                {
                  "status": 429,
                  "message": "Rate limit exceeded (60 requests/minute)",
                  "when": "Over the per-key budget; wait Retry-After seconds."
                }
              ],
              "notes": []
            },
            {
              "kind": "endpoint",
              "id": "actions-documents-delete",
              "method": "DELETE",
              "path": "/v1/shipments/{id}/documents/{documentId}",
              "summary": "Delete a document",
              "description": [],
              "auth": "apiKey",
              "rateLimit": "general",
              "since": "2026-10-22",
              "pathParams": [
                {
                  "name": "id",
                  "type": "uuid",
                  "required": true,
                  "description": "The shipment id."
                },
                {
                  "name": "documentId",
                  "type": "uuid",
                  "required": true,
                  "description": "The document id."
                }
              ],
              "queryParams": [],
              "headers": [],
              "response": {
                "status": 204,
                "contentType": "",
                "description": "No body.",
                "fields": []
              },
              "requestExamples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl -X DELETE \"https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/documents/d4b8e1c3-6a2f-4d97-8c5e-1f0a3b7d9e62\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\""
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const res = await fetch('https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/documents/d4b8e1c3-6a2f-4d97-8c5e-1f0a3b7d9e62', {\n  method: 'DELETE',\n  headers: { 'X-API-Key': process.env.NAVLO_API_KEY },\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\n// 204 No Content: nothing to parse"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.delete(\n    \"https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/documents/d4b8e1c3-6a2f-4d97-8c5e-1f0a3b7d9e62\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\n# 204 No Content: nothing to parse"
                }
              ],
              "responseExamples": [
                {
                  "status": 204,
                  "contentType": "",
                  "body": ""
                }
              ],
              "errors": [
                {
                  "status": 404,
                  "message": "Shipment not found",
                  "when": "Unknown id, deleted, or another organization’s shipment."
                },
                {
                  "status": 404,
                  "message": "Document not found",
                  "when": "Unknown document id on this shipment."
                },
                {
                  "status": 401,
                  "message": "Invalid or revoked API key",
                  "when": "The X-API-Key header is missing, wrong or revoked."
                },
                {
                  "status": 429,
                  "message": "Rate limit exceeded (60 requests/minute)",
                  "when": "Over the per-key budget; wait Retry-After seconds."
                }
              ],
              "notes": []
            },
            {
              "kind": "heading",
              "id": "actions-share-link",
              "title": "Share link"
            },
            {
              "kind": "prose",
              "text": "A public, read-only page for one shipment — milestones, vessel, ports and dates, with none of your internal data (no tags, customer, notes, risk). Anyone with the link can open it without a Navlo account."
            },
            {
              "kind": "endpoint",
              "id": "actions-share-link-create",
              "method": "POST",
              "path": "/v1/shipments/{id}/share-link",
              "summary": "Create or get the share link",
              "description": [
                "Idempotent: while a link exists, every call returns the same one."
              ],
              "auth": "apiKey",
              "rateLimit": "general",
              "since": "2026-10-22",
              "pathParams": [
                {
                  "name": "id",
                  "type": "uuid",
                  "required": true,
                  "description": "The shipment id."
                }
              ],
              "queryParams": [],
              "headers": [],
              "response": {
                "status": 200,
                "contentType": "application/json",
                "fields": [
                  {
                    "name": "url",
                    "type": "string",
                    "description": "The public page, `https://app.navlo.io/shipment/shared/<token>`."
                  },
                  {
                    "name": "token",
                    "type": "string",
                    "description": "The 27-character URL-safe token in the link."
                  }
                ]
              },
              "requestExamples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl -X POST \"https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/share-link\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\""
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const res = await fetch('https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/share-link', {\n  method: 'POST',\n  headers: { 'X-API-Key': process.env.NAVLO_API_KEY },\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\nconst share = await res.json()"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.post(\n    \"https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/share-link\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\nshare = r.json()"
                }
              ],
              "responseExamples": [
                {
                  "status": 200,
                  "contentType": "application/json",
                  "body": "{\n  \"url\": \"https://app.navlo.io/shipment/shared/5t1QJ0wQe7bS2xk9vG3nDm4LhA8\",\n  \"token\": \"5t1QJ0wQe7bS2xk9vG3nDm4LhA8\"\n}"
                }
              ],
              "errors": [
                {
                  "status": 404,
                  "message": "Shipment not found",
                  "when": "Unknown id, deleted, or another organization’s shipment."
                },
                {
                  "status": 401,
                  "message": "Invalid or revoked API key",
                  "when": "The X-API-Key header is missing, wrong or revoked."
                },
                {
                  "status": 429,
                  "message": "Rate limit exceeded (60 requests/minute)",
                  "when": "Over the per-key budget; wait Retry-After seconds."
                }
              ],
              "notes": []
            },
            {
              "kind": "endpoint",
              "id": "actions-share-link-revoke",
              "method": "DELETE",
              "path": "/v1/shipments/{id}/share-link",
              "summary": "Revoke the share link",
              "description": [
                "The old link stops working at once. Creating a link again gives a new token."
              ],
              "auth": "apiKey",
              "rateLimit": "general",
              "since": "2026-10-22",
              "pathParams": [
                {
                  "name": "id",
                  "type": "uuid",
                  "required": true,
                  "description": "The shipment id."
                }
              ],
              "queryParams": [],
              "headers": [],
              "response": {
                "status": 204,
                "contentType": "",
                "description": "No body.",
                "fields": []
              },
              "requestExamples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl -X DELETE \"https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/share-link\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\""
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const res = await fetch('https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/share-link', {\n  method: 'DELETE',\n  headers: { 'X-API-Key': process.env.NAVLO_API_KEY },\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\n// 204 No Content: nothing to parse"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.delete(\n    \"https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/share-link\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\n# 204 No Content: nothing to parse"
                }
              ],
              "responseExamples": [
                {
                  "status": 204,
                  "contentType": "",
                  "body": ""
                }
              ],
              "errors": [
                {
                  "status": 404,
                  "message": "Shipment not found",
                  "when": "Unknown id, deleted, or another organization’s shipment."
                },
                {
                  "status": 401,
                  "message": "Invalid or revoked API key",
                  "when": "The X-API-Key header is missing, wrong or revoked."
                },
                {
                  "status": 429,
                  "message": "Rate limit exceeded (60 requests/minute)",
                  "when": "Over the per-key budget; wait Retry-After seconds."
                }
              ],
              "notes": [
                "Status emails to [subscribers](#actions-subscribers) carry the share link, so while a shipment has subscribers the next status email creates a fresh link. Remove the subscribers too if the shipment must stop being visible."
              ]
            },
            {
              "kind": "heading",
              "id": "actions-subscribers",
              "title": "Email subscribers"
            },
            {
              "kind": "prose",
              "text": "People outside Navlo — your customer’s team, a broker — who get an email with the share link now and on every status change from then on. Each email has a **Stop these emails** link; people who use it disappear from the list. Muted shipments send them nothing."
            },
            {
              "kind": "endpoint",
              "id": "actions-subscribers-list",
              "method": "GET",
              "path": "/v1/shipments/{id}/subscribers",
              "summary": "List subscribers",
              "description": [],
              "auth": "apiKey",
              "rateLimit": "general",
              "since": "2026-10-22",
              "pathParams": [
                {
                  "name": "id",
                  "type": "uuid",
                  "required": true,
                  "description": "The shipment id."
                }
              ],
              "queryParams": [],
              "headers": [],
              "response": {
                "status": 200,
                "contentType": "application/json",
                "description": "An array of live subscribers, oldest first.",
                "fields": [
                  {
                    "name": "[].id",
                    "type": "uuid",
                    "description": "Subscriber id."
                  },
                  {
                    "name": "[].email",
                    "type": "string",
                    "description": "Their address, lower-cased."
                  },
                  {
                    "name": "[].events",
                    "type": "array<enum>",
                    "description": "The status categories they get emails for; `[]` means every status change.",
                    "values": [
                      "PRE_SHIPMENT",
                      "ORIGIN",
                      "TRANSIT",
                      "DESTINATION",
                      "COMPLETED"
                    ]
                  },
                  {
                    "name": "[].createdAt",
                    "type": "timestamp",
                    "description": "When they were subscribed (UTC)."
                  }
                ]
              },
              "requestExamples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl \"https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/subscribers\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\""
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const res = await fetch('https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/subscribers', {\n  headers: { 'X-API-Key': process.env.NAVLO_API_KEY },\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\nconst subscribers = await res.json()"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.get(\n    \"https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/subscribers\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\nsubscribers = r.json()"
                }
              ],
              "responseExamples": [
                {
                  "status": 200,
                  "contentType": "application/json",
                  "body": "[\n  {\n    \"id\": \"f1a6c3e8-9d2b-4f47-b0e5-7c3a1d8f6b94\",\n    \"email\": \"import.ops@acme-trading.example\",\n    \"events\": [\n      \"DESTINATION\",\n      \"COMPLETED\"\n    ],\n    \"createdAt\": \"2026-10-22T08:40:16Z\"\n  }\n]"
                }
              ],
              "errors": [
                {
                  "status": 404,
                  "message": "Shipment not found",
                  "when": "Unknown id, deleted, or another organization’s shipment."
                },
                {
                  "status": 401,
                  "message": "Invalid or revoked API key",
                  "when": "The X-API-Key header is missing, wrong or revoked."
                },
                {
                  "status": 429,
                  "message": "Rate limit exceeded (60 requests/minute)",
                  "when": "Over the per-key budget; wait Retry-After seconds."
                }
              ],
              "notes": []
            },
            {
              "kind": "endpoint",
              "id": "actions-subscribers-add",
              "method": "POST",
              "path": "/v1/shipments/{id}/subscribers",
              "summary": "Email the shipment and subscribe people",
              "description": [
                "Sends each address an email with the share link (creating the link if needed) and subscribes them to status-change emails. Subscribing someone again updates their `events`.",
                "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."
              ],
              "auth": "apiKey",
              "rateLimit": "general",
              "since": "2026-10-22",
              "pathParams": [
                {
                  "name": "id",
                  "type": "uuid",
                  "required": true,
                  "description": "The shipment id."
                }
              ],
              "queryParams": [],
              "headers": [],
              "body": {
                "contentType": "application/json",
                "fields": [
                  {
                    "name": "emails",
                    "type": "array<string>",
                    "required": true,
                    "description": "1–10 addresses, all valid; stored lower-cased."
                  },
                  {
                    "name": "events",
                    "type": "array<enum>",
                    "required": false,
                    "description": "Only email them for these status categories. Omit or send `[]` for every status change.",
                    "values": [
                      "PRE_SHIPMENT",
                      "ORIGIN",
                      "TRANSIT",
                      "DESTINATION",
                      "COMPLETED"
                    ]
                  },
                  {
                    "name": "note",
                    "type": "string",
                    "required": false,
                    "description": "A personal message in the first email, up to 2,000 characters."
                  }
                ]
              },
              "response": {
                "status": 200,
                "contentType": "application/json",
                "fields": [
                  {
                    "name": "sent",
                    "type": "integer",
                    "description": "Emails sent."
                  },
                  {
                    "name": "failed",
                    "type": "array<string>",
                    "description": "Addresses the email could not be sent to."
                  }
                ]
              },
              "requestExamples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl -X POST \"https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/subscribers\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"emails\": [\n      \"import.ops@acme-trading.example\",\n      \"broker@ambarli-customs.example\"\n    ],\n    \"events\": [\n      \"DESTINATION\",\n      \"COMPLETED\"\n    ],\n    \"note\": \"Live tracking for your MSC container to Ambarli.\"\n  }'"
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const res = await fetch('https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/subscribers', {\n  method: 'POST',\n  headers: {\n    'X-API-Key': process.env.NAVLO_API_KEY,\n    'Content-Type': 'application/json',\n  },\n  body: JSON.stringify({\n    emails: [\n      'import.ops@acme-trading.example',\n      'broker@ambarli-customs.example',\n    ],\n    events: ['DESTINATION', 'COMPLETED'],\n    note: 'Live tracking for your MSC container to Ambarli.',\n  }),\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\nconst result = await res.json()"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.post(\n    \"https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/subscribers\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    json={\n        \"emails\": [\n            \"import.ops@acme-trading.example\",\n            \"broker@ambarli-customs.example\",\n        ],\n        \"events\": [\"DESTINATION\", \"COMPLETED\"],\n        \"note\": \"Live tracking for your MSC container to Ambarli.\",\n    },\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\nresult = r.json()"
                }
              ],
              "responseExamples": [
                {
                  "status": 200,
                  "contentType": "application/json",
                  "body": "{\n  \"sent\": 2,\n  \"failed\": []\n}"
                }
              ],
              "errors": [
                {
                  "status": 404,
                  "message": "Shipment not found",
                  "when": "Unknown id, deleted, or another organization’s shipment."
                },
                {
                  "status": 400,
                  "message": "emails is required",
                  "when": "`emails` missing or empty."
                },
                {
                  "status": 400,
                  "message": "At most 10 emails per request",
                  "when": "More than 10 addresses."
                },
                {
                  "status": 400,
                  "message": "Invalid email address: import.ops@",
                  "when": "An address that isn’t valid — nothing is sent."
                },
                {
                  "status": 400,
                  "message": "Unknown event SHIPPED. Allowed: PRE_SHIPMENT, ORIGIN, TRANSIT, DESTINATION, COMPLETED",
                  "when": "An `events` value outside the list."
                },
                {
                  "status": 400,
                  "message": "note must be at most 2000 characters",
                  "when": "A longer `note`."
                },
                {
                  "status": 429,
                  "message": "Daily email limit: your organization can email 4 more recipient(s) in the next 24 hours.",
                  "when": "The addresses would take your organization past 500 recipients in 24 hours — nothing is sent. With none left: `Daily email limit reached: …`."
                },
                {
                  "status": 400,
                  "message": "Request body is missing or is not valid JSON",
                  "when": "The body could not be parsed."
                },
                {
                  "status": 401,
                  "message": "Invalid or revoked API key",
                  "when": "The X-API-Key header is missing, wrong or revoked."
                },
                {
                  "status": 429,
                  "message": "Rate limit exceeded (60 requests/minute)",
                  "when": "Over the per-key budget; wait Retry-After seconds."
                }
              ],
              "notes": []
            },
            {
              "kind": "endpoint",
              "id": "actions-subscribers-remove",
              "method": "DELETE",
              "path": "/v1/shipments/{id}/subscribers/{subscriberId}",
              "summary": "Remove a subscriber",
              "description": [
                "Stops their emails. Idempotent."
              ],
              "auth": "apiKey",
              "rateLimit": "general",
              "since": "2026-10-22",
              "pathParams": [
                {
                  "name": "id",
                  "type": "uuid",
                  "required": true,
                  "description": "The shipment id."
                },
                {
                  "name": "subscriberId",
                  "type": "uuid",
                  "required": true,
                  "description": "The subscriber id."
                }
              ],
              "queryParams": [],
              "headers": [],
              "response": {
                "status": 204,
                "contentType": "",
                "description": "No body.",
                "fields": []
              },
              "requestExamples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl -X DELETE \"https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/subscribers/f1a6c3e8-9d2b-4f47-b0e5-7c3a1d8f6b94\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\""
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const res = await fetch('https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/subscribers/f1a6c3e8-9d2b-4f47-b0e5-7c3a1d8f6b94', {\n  method: 'DELETE',\n  headers: { 'X-API-Key': process.env.NAVLO_API_KEY },\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\n// 204 No Content: nothing to parse"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.delete(\n    \"https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/subscribers/f1a6c3e8-9d2b-4f47-b0e5-7c3a1d8f6b94\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\n# 204 No Content: nothing to parse"
                }
              ],
              "responseExamples": [
                {
                  "status": 204,
                  "contentType": "",
                  "body": ""
                }
              ],
              "errors": [
                {
                  "status": 404,
                  "message": "Shipment not found",
                  "when": "Unknown id, deleted, or another organization’s shipment."
                },
                {
                  "status": 404,
                  "message": "Subscriber not found",
                  "when": "Unknown subscriber id on this shipment."
                },
                {
                  "status": 401,
                  "message": "Invalid or revoked API key",
                  "when": "The X-API-Key header is missing, wrong or revoked."
                },
                {
                  "status": 429,
                  "message": "Rate limit exceeded (60 requests/minute)",
                  "when": "Over the per-key budget; wait Retry-After seconds."
                }
              ],
              "notes": []
            },
            {
              "kind": "heading",
              "id": "actions-mute",
              "title": "Mute notifications"
            },
            {
              "kind": "prose",
              "text": "Muting silences everything about the shipment for people: your team’s emails, push and in-app notifications, digest rows and subscriber emails. **Webhooks keep firing** — your systems still hear every change."
            },
            {
              "kind": "endpoint",
              "id": "actions-mute-set",
              "method": "PUT",
              "path": "/v1/shipments/{id}/mute",
              "summary": "Mute a shipment",
              "description": [
                "Idempotent. Allowed for organization admins and the person who added the shipment."
              ],
              "auth": "apiKey",
              "rateLimit": "general",
              "since": "2026-10-22",
              "pathParams": [
                {
                  "name": "id",
                  "type": "uuid",
                  "required": true,
                  "description": "The shipment id."
                }
              ],
              "queryParams": [],
              "headers": [],
              "response": {
                "status": 200,
                "contentType": "application/json",
                "fields": [
                  {
                    "name": "id",
                    "type": "uuid",
                    "description": "The shipment id."
                  },
                  {
                    "name": "notificationsMuted",
                    "type": "boolean",
                    "description": "`true` after muting, `false` after unmuting."
                  }
                ]
              },
              "requestExamples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl -X PUT \"https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/mute\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\""
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const res = await fetch('https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/mute', {\n  method: 'PUT',\n  headers: { 'X-API-Key': process.env.NAVLO_API_KEY },\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\nconst result = await res.json()"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.put(\n    \"https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/mute\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\nresult = r.json()"
                }
              ],
              "responseExamples": [
                {
                  "status": 200,
                  "contentType": "application/json",
                  "body": "{\n  \"id\": \"8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07\",\n  \"notificationsMuted\": true\n}"
                }
              ],
              "errors": [
                {
                  "status": 404,
                  "message": "Shipment not found",
                  "when": "Unknown id, deleted, or another organization’s shipment."
                },
                {
                  "status": 403,
                  "message": "Only an organization admin or the person who added this shipment can mute or unmute its notifications",
                  "when": "The key’s creator is neither."
                },
                {
                  "status": 401,
                  "message": "Invalid or revoked API key",
                  "when": "The X-API-Key header is missing, wrong or revoked."
                },
                {
                  "status": 429,
                  "message": "Rate limit exceeded (60 requests/minute)",
                  "when": "Over the per-key budget; wait Retry-After seconds."
                }
              ],
              "notes": []
            },
            {
              "kind": "endpoint",
              "id": "actions-unmute",
              "method": "DELETE",
              "path": "/v1/shipments/{id}/mute",
              "summary": "Unmute a shipment",
              "description": [
                "Idempotent. Same permission as muting."
              ],
              "auth": "apiKey",
              "rateLimit": "general",
              "since": "2026-10-22",
              "pathParams": [
                {
                  "name": "id",
                  "type": "uuid",
                  "required": true,
                  "description": "The shipment id."
                }
              ],
              "queryParams": [],
              "headers": [],
              "response": {
                "status": 200,
                "contentType": "application/json",
                "fields": [
                  {
                    "name": "id",
                    "type": "uuid",
                    "description": "The shipment id."
                  },
                  {
                    "name": "notificationsMuted",
                    "type": "boolean",
                    "description": "Always `false`."
                  }
                ]
              },
              "requestExamples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl -X DELETE \"https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/mute\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\""
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const res = await fetch('https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/mute', {\n  method: 'DELETE',\n  headers: { 'X-API-Key': process.env.NAVLO_API_KEY },\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\nconst result = await res.json()"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.delete(\n    \"https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/mute\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\nresult = r.json()"
                }
              ],
              "responseExamples": [
                {
                  "status": 200,
                  "contentType": "application/json",
                  "body": "{\n  \"id\": \"8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07\",\n  \"notificationsMuted\": false\n}"
                }
              ],
              "errors": [
                {
                  "status": 404,
                  "message": "Shipment not found",
                  "when": "Unknown id, deleted, or another organization’s shipment."
                },
                {
                  "status": 401,
                  "message": "Invalid or revoked API key",
                  "when": "The X-API-Key header is missing, wrong or revoked."
                },
                {
                  "status": 429,
                  "message": "Rate limit exceeded (60 requests/minute)",
                  "when": "Over the per-key budget; wait Retry-After seconds."
                }
              ],
              "notes": []
            },
            {
              "kind": "heading",
              "id": "actions-complete",
              "title": "Mark as completed"
            },
            {
              "kind": "endpoint",
              "id": "actions-complete-shipment",
              "method": "POST",
              "path": "/v1/shipments/{id}/complete",
              "summary": "Mark a shipment completed",
              "description": [
                "For a shipment you know is done when the carrier never says so. Polling stops, the shipment leaves active lists, and it stays in reports and history. Idempotent; there is no un-complete."
              ],
              "auth": "apiKey",
              "rateLimit": "general",
              "since": "2026-10-22",
              "pathParams": [
                {
                  "name": "id",
                  "type": "uuid",
                  "required": true,
                  "description": "The shipment id."
                }
              ],
              "queryParams": [],
              "headers": [],
              "response": {
                "status": 200,
                "contentType": "application/json",
                "fields": [
                  {
                    "name": "id",
                    "type": "uuid",
                    "description": "The shipment id."
                  },
                  {
                    "name": "status",
                    "type": "enum",
                    "description": "Always `completed`.",
                    "values": [
                      "completed"
                    ]
                  }
                ]
              },
              "requestExamples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl -X POST \"https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/complete\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\""
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const res = await fetch('https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/complete', {\n  method: 'POST',\n  headers: { 'X-API-Key': process.env.NAVLO_API_KEY },\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\nconst result = await res.json()"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.post(\n    \"https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/complete\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\nresult = r.json()"
                }
              ],
              "responseExamples": [
                {
                  "status": 200,
                  "contentType": "application/json",
                  "body": "{\n  \"id\": \"8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07\",\n  \"status\": \"completed\"\n}"
                }
              ],
              "errors": [
                {
                  "status": 404,
                  "message": "Shipment not found",
                  "when": "Unknown id, deleted, or another organization’s shipment."
                },
                {
                  "status": 401,
                  "message": "Invalid or revoked API key",
                  "when": "The X-API-Key header is missing, wrong or revoked."
                },
                {
                  "status": 429,
                  "message": "Rate limit exceeded (60 requests/minute)",
                  "when": "Over the per-key budget; wait Retry-After seconds."
                }
              ],
              "notes": [
                "No completion email and no `shipment.completed` webhook are sent — your system made the change, so it already knows."
              ]
            },
            {
              "kind": "heading",
              "id": "actions-carrier",
              "title": "Change carrier"
            },
            {
              "kind": "endpoint",
              "id": "actions-carrier-change",
              "method": "POST",
              "path": "/v1/shipments/{id}/carrier",
              "summary": "Change the carrier",
              "description": [
                "When Navlo tracks a shipment with the wrong carrier, switch it. Carrier data — containers, events, ETA history, risk, carbon — is cleared and discovery starts again with the new carrier; notes, tags, documents, free-time overrides and the customer stay. Allowed once per shipment."
              ],
              "auth": "apiKey",
              "rateLimit": "general",
              "since": "2026-10-22",
              "pathParams": [
                {
                  "name": "id",
                  "type": "uuid",
                  "required": true,
                  "description": "The shipment id."
                }
              ],
              "queryParams": [],
              "headers": [],
              "body": {
                "contentType": "application/json",
                "fields": [
                  {
                    "name": "carrier",
                    "type": "string",
                    "required": true,
                    "description": "The carrier code, e.g. `MAERSK`, `HAPAG`, `EMIRATES` — or its name as you write it, resolved like `carrier` on [create](/developers/shipments#shipments-create)."
                  }
                ]
              },
              "response": {
                "status": 200,
                "contentType": "application/json",
                "fields": [
                  {
                    "name": "id",
                    "type": "uuid",
                    "description": "The shipment id."
                  },
                  {
                    "name": "carrier",
                    "type": "string",
                    "description": "The new carrier code."
                  },
                  {
                    "name": "status",
                    "type": "enum",
                    "description": "Navlo is fetching data from the new carrier: `discovering` for ocean, `tracking` for air.",
                    "values": [
                      "discovering",
                      "tracking"
                    ]
                  }
                ]
              },
              "requestExamples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl -X POST \"https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/carrier\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"carrier\": \"MAERSK\"\n  }'"
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const res = await fetch('https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/carrier', {\n  method: 'POST',\n  headers: {\n    'X-API-Key': process.env.NAVLO_API_KEY,\n    'Content-Type': 'application/json',\n  },\n  body: JSON.stringify({ carrier: 'MAERSK' }),\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\nconst result = await res.json()"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.post(\n    \"https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/carrier\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    json={\"carrier\": \"MAERSK\"},\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\nresult = r.json()"
                }
              ],
              "responseExamples": [
                {
                  "status": 200,
                  "contentType": "application/json",
                  "body": "{\n  \"id\": \"8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07\",\n  \"carrier\": \"MAERSK\",\n  \"status\": \"discovering\"\n}"
                }
              ],
              "errors": [
                {
                  "status": 404,
                  "message": "Shipment not found",
                  "when": "Unknown id, deleted, or another organization’s shipment."
                },
                {
                  "status": 409,
                  "message": "Carrier was already changed once on this shipment; no further changes allowed.",
                  "when": "The one change was already used."
                },
                {
                  "status": 400,
                  "message": "carrier is required",
                  "when": "`carrier` missing or blank."
                },
                {
                  "status": 400,
                  "message": "Unknown carrier Oceanic Star Lines for OCEAN shipments",
                  "when": "Navlo can’t resolve the carrier — your one change is not used up."
                },
                {
                  "status": 400,
                  "message": "Carrier MAERSK does not support AIR tracking",
                  "when": "The carrier doesn’t track this mode."
                },
                {
                  "status": 400,
                  "message": "Request body is missing or is not valid JSON",
                  "when": "The body could not be parsed."
                },
                {
                  "status": 401,
                  "message": "Invalid or revoked API key",
                  "when": "The X-API-Key header is missing, wrong or revoked."
                },
                {
                  "status": 429,
                  "message": "Rate limit exceeded (60 requests/minute)",
                  "when": "Over the per-key budget; wait Retry-After seconds."
                }
              ],
              "notes": []
            }
          ]
        },
        {
          "id": "tags",
          "title": "Tags",
          "summary": "Your organization’s labels for shipments — list, create and delete them, and put them on shipments.",
          "blocks": [
            {
              "kind": "prose",
              "text": "Tags are shared across your organization and show on the Shipments page. Filter the shipment list by them with `tag=`, and read them per shipment with `include=tags`. Tag names are unique in your organization, ignoring case."
            },
            {
              "kind": "endpoint",
              "id": "tags-list",
              "method": "GET",
              "path": "/v1/tags",
              "summary": "List tags",
              "description": [],
              "auth": "apiKey",
              "rateLimit": "general",
              "since": "2026-10-22",
              "pathParams": [],
              "queryParams": [],
              "headers": [],
              "response": {
                "status": 200,
                "contentType": "application/json",
                "description": "An array of your organization’s tags, sorted by name.",
                "fields": [
                  {
                    "name": "[].id",
                    "type": "uuid",
                    "description": "Tag id."
                  },
                  {
                    "name": "[].name",
                    "type": "string",
                    "description": "Tag name, unique in your organization (case-insensitive)."
                  },
                  {
                    "name": "[].color",
                    "type": "string",
                    "nullable": true,
                    "description": "Hex colour `#rrggbb`, or null."
                  }
                ]
              },
              "requestExamples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl \"https://api.navlo.io/v1/tags\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\""
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const res = await fetch('https://api.navlo.io/v1/tags', {\n  headers: { 'X-API-Key': process.env.NAVLO_API_KEY },\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\nconst tags = await res.json()"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.get(\n    \"https://api.navlo.io/v1/tags\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\ntags = r.json()"
                }
              ],
              "responseExamples": [
                {
                  "status": 200,
                  "contentType": "application/json",
                  "body": "[\n  {\n    \"id\": \"a3f9c2d1-7b4e-4c8a-9e16-2d5f8b0c7e41\",\n    \"name\": \"Priority\",\n    \"color\": \"#ef4444\"\n  },\n  {\n    \"id\": \"b81e4d7a-2c9f-4a63-8d05-6e3b1f9c2a77\",\n    \"name\": \"Q4 launch\",\n    \"color\": \"#3b82f6\"\n  }\n]"
                }
              ],
              "errors": [
                {
                  "status": 401,
                  "message": "Invalid or revoked API key",
                  "when": "The X-API-Key header is missing, wrong or revoked."
                },
                {
                  "status": 429,
                  "message": "Rate limit exceeded (60 requests/minute)",
                  "when": "Over the per-key budget; wait Retry-After seconds."
                }
              ],
              "notes": []
            },
            {
              "kind": "endpoint",
              "id": "tags-create",
              "method": "POST",
              "path": "/v1/tags",
              "summary": "Create a tag",
              "description": [],
              "auth": "apiKey",
              "rateLimit": "general",
              "since": "2026-10-22",
              "pathParams": [],
              "queryParams": [],
              "headers": [],
              "body": {
                "contentType": "application/json",
                "fields": [
                  {
                    "name": "name",
                    "type": "string",
                    "required": true,
                    "description": "1–50 characters (trimmed), unique in your organization ignoring case."
                  },
                  {
                    "name": "color",
                    "type": "string",
                    "required": false,
                    "description": "Hex colour, `#rgb` or `#rrggbb`. The app’s palette: `#3b82f6`, `#10b981`, `#f59e0b`, `#ef4444`, `#8b5cf6`, `#ec4899`, `#6b7280`, `#06b6d4`.",
                    "defaultValue": "#3b82f6"
                  }
                ]
              },
              "response": {
                "status": 201,
                "contentType": "application/json",
                "fields": [
                  {
                    "name": "id",
                    "type": "uuid",
                    "description": "Tag id."
                  },
                  {
                    "name": "name",
                    "type": "string",
                    "description": "Tag name, unique in your organization (case-insensitive)."
                  },
                  {
                    "name": "color",
                    "type": "string",
                    "nullable": true,
                    "description": "Hex colour `#rrggbb`, or null."
                  }
                ]
              },
              "requestExamples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl -X POST \"https://api.navlo.io/v1/tags\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"name\": \"Priority\",\n    \"color\": \"#ef4444\"\n  }'"
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const res = await fetch('https://api.navlo.io/v1/tags', {\n  method: 'POST',\n  headers: {\n    'X-API-Key': process.env.NAVLO_API_KEY,\n    'Content-Type': 'application/json',\n  },\n  body: JSON.stringify({ name: 'Priority', color: '#ef4444' }),\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\nconst tag = await res.json()"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.post(\n    \"https://api.navlo.io/v1/tags\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    json={\"name\": \"Priority\", \"color\": \"#ef4444\"},\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\ntag = r.json()"
                }
              ],
              "responseExamples": [
                {
                  "status": 201,
                  "contentType": "application/json",
                  "body": "{\n  \"id\": \"a3f9c2d1-7b4e-4c8a-9e16-2d5f8b0c7e41\",\n  \"name\": \"Priority\",\n  \"color\": \"#ef4444\"\n}"
                }
              ],
              "errors": [
                {
                  "status": 409,
                  "message": "A tag with name 'Priority' already exists",
                  "when": "The name is taken (ignoring case)."
                },
                {
                  "status": 400,
                  "message": "name must be at most 50 characters",
                  "when": "Over 50 characters."
                },
                {
                  "status": 400,
                  "message": "name is required",
                  "when": "`name` missing or blank."
                },
                {
                  "status": 400,
                  "message": "color must be a hex colour like #3b82f6",
                  "when": "A `color` that isn’t `#rgb` / `#rrggbb`."
                },
                {
                  "status": 401,
                  "message": "Invalid or revoked API key",
                  "when": "The X-API-Key header is missing, wrong or revoked."
                },
                {
                  "status": 429,
                  "message": "Rate limit exceeded (60 requests/minute)",
                  "when": "Over the per-key budget; wait Retry-After seconds."
                }
              ],
              "notes": []
            },
            {
              "kind": "endpoint",
              "id": "tags-delete",
              "method": "DELETE",
              "path": "/v1/tags/{tagId}",
              "summary": "Delete a tag",
              "description": [
                "Removes the tag from every shipment, then deletes it. Organization admins only."
              ],
              "auth": "apiKey",
              "rateLimit": "general",
              "since": "2026-10-22",
              "pathParams": [
                {
                  "name": "tagId",
                  "type": "uuid",
                  "required": true,
                  "description": "The tag id."
                }
              ],
              "queryParams": [],
              "headers": [],
              "response": {
                "status": 204,
                "contentType": "",
                "description": "No body.",
                "fields": []
              },
              "requestExamples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl -X DELETE \"https://api.navlo.io/v1/tags/b81e4d7a-2c9f-4a63-8d05-6e3b1f9c2a77\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\""
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const res = await fetch('https://api.navlo.io/v1/tags/b81e4d7a-2c9f-4a63-8d05-6e3b1f9c2a77', {\n  method: 'DELETE',\n  headers: { 'X-API-Key': process.env.NAVLO_API_KEY },\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\n// 204 No Content: nothing to parse"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.delete(\n    \"https://api.navlo.io/v1/tags/b81e4d7a-2c9f-4a63-8d05-6e3b1f9c2a77\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\n# 204 No Content: nothing to parse"
                }
              ],
              "responseExamples": [
                {
                  "status": 204,
                  "contentType": "",
                  "body": ""
                }
              ],
              "errors": [
                {
                  "status": 404,
                  "message": "Tag not found",
                  "when": "Unknown tag id, or another organization’s."
                },
                {
                  "status": 403,
                  "message": "Only organization admins can delete tags",
                  "when": "The key’s creator is not an admin."
                },
                {
                  "status": 401,
                  "message": "Invalid or revoked API key",
                  "when": "The X-API-Key header is missing, wrong or revoked."
                },
                {
                  "status": 429,
                  "message": "Rate limit exceeded (60 requests/minute)",
                  "when": "Over the per-key budget; wait Retry-After seconds."
                }
              ],
              "notes": []
            },
            {
              "kind": "endpoint",
              "id": "tags-assign",
              "method": "POST",
              "path": "/v1/shipments/{id}/tags",
              "summary": "Tag a shipment",
              "description": [
                "Adds a tag by id, or by name — a name is matched ignoring case and the tag is created (in `#3b82f6`) if it doesn’t exist yet. `tagId` wins when both are sent. Adding a tag the shipment already has changes nothing. Returns the shipment’s tags, sorted by name."
              ],
              "auth": "apiKey",
              "rateLimit": "general",
              "since": "2026-10-22",
              "pathParams": [
                {
                  "name": "id",
                  "type": "uuid",
                  "required": true,
                  "description": "The shipment id."
                }
              ],
              "queryParams": [],
              "headers": [],
              "body": {
                "contentType": "application/json",
                "fields": [
                  {
                    "name": "tagId",
                    "type": "uuid",
                    "required": false,
                    "description": "An existing tag. Send `tagId` or `name`."
                  },
                  {
                    "name": "name",
                    "type": "string",
                    "required": false,
                    "description": "A tag name; created when new (up to 50 characters)."
                  }
                ]
              },
              "response": {
                "status": 200,
                "contentType": "application/json",
                "description": "The shipment’s tags after the change.",
                "fields": [
                  {
                    "name": "[].id",
                    "type": "uuid",
                    "description": "Tag id."
                  },
                  {
                    "name": "[].name",
                    "type": "string",
                    "description": "Tag name, unique in your organization (case-insensitive)."
                  },
                  {
                    "name": "[].color",
                    "type": "string",
                    "nullable": true,
                    "description": "Hex colour `#rrggbb`, or null."
                  }
                ]
              },
              "requestExamples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl -X POST \"https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/tags\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"name\": \"Q4 launch\"\n  }'"
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const res = await fetch('https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/tags', {\n  method: 'POST',\n  headers: {\n    'X-API-Key': process.env.NAVLO_API_KEY,\n    'Content-Type': 'application/json',\n  },\n  body: JSON.stringify({ name: 'Q4 launch' }),\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\nconst tags = await res.json()"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.post(\n    \"https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/tags\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    json={\"name\": \"Q4 launch\"},\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\ntags = r.json()"
                }
              ],
              "responseExamples": [
                {
                  "status": 200,
                  "contentType": "application/json",
                  "body": "[\n  {\n    \"id\": \"a3f9c2d1-7b4e-4c8a-9e16-2d5f8b0c7e41\",\n    \"name\": \"Priority\",\n    \"color\": \"#ef4444\"\n  },\n  {\n    \"id\": \"b81e4d7a-2c9f-4a63-8d05-6e3b1f9c2a77\",\n    \"name\": \"Q4 launch\",\n    \"color\": \"#3b82f6\"\n  }\n]"
                }
              ],
              "errors": [
                {
                  "status": 404,
                  "message": "Shipment not found",
                  "when": "Unknown id, deleted, or another organization’s shipment."
                },
                {
                  "status": 404,
                  "message": "Tag not found",
                  "when": "Unknown tag id, or another organization’s."
                },
                {
                  "status": 400,
                  "message": "tagId or name is required",
                  "when": "Neither was sent."
                },
                {
                  "status": 401,
                  "message": "Invalid or revoked API key",
                  "when": "The X-API-Key header is missing, wrong or revoked."
                },
                {
                  "status": 429,
                  "message": "Rate limit exceeded (60 requests/minute)",
                  "when": "Over the per-key budget; wait Retry-After seconds."
                }
              ],
              "notes": []
            },
            {
              "kind": "endpoint",
              "id": "tags-unassign",
              "method": "DELETE",
              "path": "/v1/shipments/{id}/tags/{tagId}",
              "summary": "Untag a shipment",
              "description": [
                "Removes the tag from this shipment only. Idempotent. Returns the shipment’s remaining tags."
              ],
              "auth": "apiKey",
              "rateLimit": "general",
              "since": "2026-10-22",
              "pathParams": [
                {
                  "name": "id",
                  "type": "uuid",
                  "required": true,
                  "description": "The shipment id."
                },
                {
                  "name": "tagId",
                  "type": "uuid",
                  "required": true,
                  "description": "The tag id."
                }
              ],
              "queryParams": [],
              "headers": [],
              "response": {
                "status": 200,
                "contentType": "application/json",
                "fields": [
                  {
                    "name": "[].id",
                    "type": "uuid",
                    "description": "Tag id."
                  },
                  {
                    "name": "[].name",
                    "type": "string",
                    "description": "Tag name, unique in your organization (case-insensitive)."
                  },
                  {
                    "name": "[].color",
                    "type": "string",
                    "nullable": true,
                    "description": "Hex colour `#rrggbb`, or null."
                  }
                ]
              },
              "requestExamples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl -X DELETE \"https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/tags/b81e4d7a-2c9f-4a63-8d05-6e3b1f9c2a77\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\""
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const res = await fetch('https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/tags/b81e4d7a-2c9f-4a63-8d05-6e3b1f9c2a77', {\n  method: 'DELETE',\n  headers: { 'X-API-Key': process.env.NAVLO_API_KEY },\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\nconst tags = await res.json()"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.delete(\n    \"https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/tags/b81e4d7a-2c9f-4a63-8d05-6e3b1f9c2a77\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\ntags = r.json()"
                }
              ],
              "responseExamples": [
                {
                  "status": 200,
                  "contentType": "application/json",
                  "body": "[\n  {\n    \"id\": \"a3f9c2d1-7b4e-4c8a-9e16-2d5f8b0c7e41\",\n    \"name\": \"Priority\",\n    \"color\": \"#ef4444\"\n  }\n]"
                }
              ],
              "errors": [
                {
                  "status": 404,
                  "message": "Shipment not found",
                  "when": "Unknown id, deleted, or another organization’s shipment."
                },
                {
                  "status": 401,
                  "message": "Invalid or revoked API key",
                  "when": "The X-API-Key header is missing, wrong or revoked."
                },
                {
                  "status": 429,
                  "message": "Rate limit exceeded (60 requests/minute)",
                  "when": "Over the per-key budget; wait Retry-After seconds."
                }
              ],
              "notes": []
            }
          ]
        },
        {
          "id": "reports-and-export",
          "title": "Reports & export",
          "summary": "Download your shipments as CSV or Excel, and generate the same status, cost and D&D reports Navlo AI writes.",
          "blocks": [
            {
              "kind": "endpoint",
              "id": "reports-export",
              "method": "GET",
              "path": "/v1/shipments/export",
              "summary": "Export shipments",
              "description": [
                "The Shipments page export: one row per container (ocean) or waybill (air), as CSV or XLSX, with the list filters applied. The file comes back directly as an attachment. Dates are `yyyy-MM-dd HH:mm` in UTC; CSV is UTF-8 with a byte-order mark so Excel opens accented names correctly."
              ],
              "auth": "apiKey",
              "rateLimit": "general",
              "since": "2026-10-22",
              "pathParams": [],
              "queryParams": [
                {
                  "name": "format",
                  "type": "enum",
                  "required": false,
                  "description": "File format.",
                  "values": [
                    "csv",
                    "xlsx"
                  ],
                  "defaultValue": "csv"
                },
                {
                  "name": "columns",
                  "type": "csv",
                  "required": false,
                  "description": "Column keys to include (see the table below); default all. `trackingIdentifier` is always included and columns keep the table’s order whatever order you send."
                },
                {
                  "name": "status",
                  "type": "csv",
                  "required": false,
                  "description": "As on the [shipment list](/developers/shipments#shipments-list): `active` also matches `tracking`.",
                  "values": [
                    "discovering",
                    "resolving",
                    "active",
                    "tracking",
                    "completed",
                    "stopped"
                  ]
                },
                {
                  "name": "mode",
                  "type": "enum",
                  "required": false,
                  "description": "Only ocean or only air.",
                  "values": [
                    "OCEAN",
                    "AIR"
                  ]
                },
                {
                  "name": "carrier",
                  "type": "string",
                  "required": false,
                  "description": "Carrier code."
                },
                {
                  "name": "customerId",
                  "type": "uuid | none",
                  "required": false,
                  "description": "Only this customer’s shipments — or `none` for shipments without a customer."
                },
                {
                  "name": "tag",
                  "type": "csv",
                  "required": false,
                  "description": "Tag names (case-insensitive); shipments carrying any of them. Names that match no tag are ignored — if none match, the file is empty."
                },
                {
                  "name": "etaFrom",
                  "type": "timestamp | date",
                  "required": false,
                  "description": "ETA on or after."
                },
                {
                  "name": "etaTo",
                  "type": "timestamp | date",
                  "required": false,
                  "description": "ETA on or before; a date means the end of that day."
                },
                {
                  "name": "createdFrom",
                  "type": "timestamp | date",
                  "required": false,
                  "description": "Started on or after (UTC)."
                },
                {
                  "name": "createdTo",
                  "type": "timestamp | date",
                  "required": false,
                  "description": "Started on or before (UTC); a date means the end of that day."
                }
              ],
              "headers": [],
              "response": {
                "status": 200,
                "contentType": "text/csv or application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
                "description": "The file, with `Content-Disposition: attachment; filename=\"navlo-trackings-2026-10-22.xlsx\"` (date in UTC).",
                "fields": []
              },
              "requestExamples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl \"https://api.navlo.io/v1/shipments/export?format=xlsx&status=active&customerId=c7d2a9e4-3f1b-4e8a-9b6c-1d5e7f3a2b90\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\" \\\n  -o navlo-trackings.xlsx"
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "import { writeFile } from 'node:fs/promises'\n\nconst params = new URLSearchParams({\n  format: 'xlsx',\n  status: 'active',\n  customerId: 'c7d2a9e4-3f1b-4e8a-9b6c-1d5e7f3a2b90',\n})\n\nconst res = await fetch(`https://api.navlo.io/v1/shipments/export?${params}`, {\n  headers: { 'X-API-Key': process.env.NAVLO_API_KEY },\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\nawait writeFile('navlo-trackings.xlsx', Buffer.from(await res.arrayBuffer()))"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.get(\n    \"https://api.navlo.io/v1/shipments/export\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    params={\n        \"format\": \"xlsx\",\n        \"status\": \"active\",\n        \"customerId\": \"c7d2a9e4-3f1b-4e8a-9b6c-1d5e7f3a2b90\",\n    },\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\nwith open(\"navlo-trackings.xlsx\", \"wb\") as f:\n    f.write(r.content)"
                }
              ],
              "responseExamples": [
                {
                  "status": 200,
                  "label": "format=csv&columns=mode,status,carrier,podCode,eta,customer",
                  "contentType": "text/csv",
                  "body": "Tracking Identifier,Mode,Status,Carrier,PoD Code,ETA,Customer\nMEDU1234562,OCEAN,In Transit,MSC,TRAMR,2026-10-30 06:00,Acme Trading Ltd.\nTGHU8126501,OCEAN,In Transit,Hapag-Lloyd,TRMER,2026-11-04 18:00,Acme Trading Ltd."
                }
              ],
              "errors": [
                {
                  "status": 400,
                  "message": "format must be one of csv, xlsx",
                  "when": "Another `format`."
                },
                {
                  "status": 400,
                  "message": "Unknown report column: vessel.",
                  "when": "A `columns` key outside the table."
                },
                {
                  "status": 400,
                  "message": "customerId must be a customer id or none",
                  "when": "A malformed `customerId`."
                },
                {
                  "status": 400,
                  "message": "Unknown status shipped. Allowed: discovering, resolving, active, tracking, completed, stopped",
                  "when": "A `status` outside the list."
                },
                {
                  "status": 401,
                  "message": "Invalid or revoked API key",
                  "when": "The X-API-Key header is missing, wrong or revoked."
                },
                {
                  "status": 429,
                  "message": "Rate limit exceeded (60 requests/minute)",
                  "when": "Over the per-key budget; wait Retry-After seconds."
                }
              ],
              "notes": []
            },
            {
              "kind": "table",
              "title": "Export columns",
              "columns": [
                "Column key",
                "Header in the file"
              ],
              "rows": [
                [
                  "`trackingIdentifier`",
                  "Tracking Identifier"
                ],
                [
                  "`identifierType`",
                  "Identifier Type"
                ],
                [
                  "`mode`",
                  "Mode"
                ],
                [
                  "`status`",
                  "Status"
                ],
                [
                  "`carrier`",
                  "Carrier"
                ],
                [
                  "`vesselFlight`",
                  "Vessel/Flight"
                ],
                [
                  "`polCode`",
                  "PoL Code"
                ],
                [
                  "`polName`",
                  "PoL Name"
                ],
                [
                  "`polCountry`",
                  "PoL Country"
                ],
                [
                  "`podCode`",
                  "PoD Code"
                ],
                [
                  "`podName`",
                  "PoD Name"
                ],
                [
                  "`podCountry`",
                  "PoD Country"
                ],
                [
                  "`transshipmentCount`",
                  "Transshipment Count"
                ],
                [
                  "`containerAwbNumber`",
                  "Container/AWB Number"
                ],
                [
                  "`etd`",
                  "ETD"
                ],
                [
                  "`atd`",
                  "ATD"
                ],
                [
                  "`eta`",
                  "ETA"
                ],
                [
                  "`ata`",
                  "ATA"
                ],
                [
                  "`trackedBy`",
                  "Tracked By"
                ],
                [
                  "`createdAt`",
                  "Created At"
                ],
                [
                  "`lastUpdated`",
                  "Last Updated"
                ],
                [
                  "`customer`",
                  "Customer"
                ],
                [
                  "`relatedContainers`",
                  "Related Containers"
                ],
                [
                  "`tags`",
                  "Tags"
                ],
                [
                  "`risk`",
                  "Risk"
                ],
                [
                  "`riskNote`",
                  "Risk Note"
                ]
              ]
            },
            {
              "kind": "endpoint",
              "id": "reports-create",
              "method": "POST",
              "path": "/v1/reports",
              "summary": "Generate a report",
              "description": [
                "Builds the same Excel report Navlo AI produces when you ask it for a status, cost or D&D risk report — directly, with no AI credits spent. Returns a download link valid for 7 days."
              ],
              "auth": "apiKey",
              "rateLimit": "general",
              "since": "2026-10-22",
              "pathParams": [],
              "queryParams": [],
              "headers": [],
              "body": {
                "contentType": "application/json",
                "fields": [
                  {
                    "name": "type",
                    "type": "enum",
                    "required": true,
                    "description": "`STATUS` — one row per shipment (up to 500). `COST` — the cost analysis figures for a period. `DND_RISK` — free time, days remaining and D&D exposure per shipment (up to 200).",
                    "values": [
                      "STATUS",
                      "COST",
                      "DND_RISK"
                    ]
                  },
                  {
                    "name": "filters",
                    "type": "object",
                    "required": false,
                    "description": "Narrow the report. Any other key is rejected rather than ignored, so a report never looks filtered when it isn’t."
                  },
                  {
                    "name": "filters.mode",
                    "type": "enum",
                    "required": false,
                    "description": "`OCEAN` or `AIR`. COST with `AIR` analyses air storage charges.",
                    "values": [
                      "OCEAN",
                      "AIR"
                    ]
                  },
                  {
                    "name": "filters.status",
                    "type": "array<enum>",
                    "required": false,
                    "description": "STATUS and DND_RISK only. A string or an array of public statuses; `active` also matches `tracking`.",
                    "values": [
                      "discovering",
                      "resolving",
                      "active",
                      "tracking",
                      "completed",
                      "stopped"
                    ]
                  },
                  {
                    "name": "filters.customerId",
                    "type": "uuid | none",
                    "required": false,
                    "description": "STATUS and DND_RISK only: one customer’s shipments, or `none` for shipments without a customer. Not together with `customerRef`."
                  },
                  {
                    "name": "filters.customerRef",
                    "type": "string",
                    "required": false,
                    "description": "STATUS and DND_RISK only: the customer with your own reference, e.g. `C-1042`."
                  },
                  {
                    "name": "filters.tag",
                    "type": "string | array<string>",
                    "required": false,
                    "description": "STATUS and DND_RISK only: tag names — a string (comma-separated allowed) or an array; shipments carrying any of them. Every name must match one of your tags."
                  },
                  {
                    "name": "filters.carrier",
                    "type": "string",
                    "required": false,
                    "description": "Carrier code or name."
                  },
                  {
                    "name": "filters.originPort",
                    "type": "string",
                    "required": false,
                    "description": "Port of loading, UN/LOCODE (airport code for air). Not for COST — use `originCountry`."
                  },
                  {
                    "name": "filters.destinationPort",
                    "type": "string",
                    "required": false,
                    "description": "Port of discharge, UN/LOCODE (airport code for air). COST also takes a port name."
                  },
                  {
                    "name": "filters.originCountry",
                    "type": "string",
                    "required": false,
                    "description": "ISO alpha-2 country of loading."
                  },
                  {
                    "name": "filters.destinationCountry",
                    "type": "string",
                    "required": false,
                    "description": "ISO alpha-2 country of discharge."
                  },
                  {
                    "name": "filters.etaFrom",
                    "type": "date",
                    "required": false,
                    "description": "ETA on or after this UTC day (an ISO timestamp is reduced to its day)."
                  },
                  {
                    "name": "filters.etaTo",
                    "type": "date",
                    "required": false,
                    "description": "ETA on or before this UTC day."
                  },
                  {
                    "name": "filters.shipments",
                    "type": "array<string>",
                    "required": false,
                    "description": "STATUS and DND_RISK only: exactly these identifiers (up to 100) — on its own, with no other filter (`customerId`, `customerRef` and `tag` included)."
                  },
                  {
                    "name": "filters.from",
                    "type": "date",
                    "required": false,
                    "description": "COST only: first day of the period (default 30 days before `to`)."
                  },
                  {
                    "name": "filters.to",
                    "type": "date",
                    "required": false,
                    "description": "COST only: last day of the period (default today)."
                  }
                ]
              },
              "response": {
                "status": 201,
                "contentType": "application/json",
                "fields": [
                  {
                    "name": "type",
                    "type": "enum",
                    "description": "The report type.",
                    "values": [
                      "STATUS",
                      "COST",
                      "DND_RISK"
                    ]
                  },
                  {
                    "name": "fileName",
                    "type": "string",
                    "description": "e.g. `shipment-status-report-20261022.xlsx`, `cost-report-…`, `dnd-risk-report-…`."
                  },
                  {
                    "name": "url",
                    "type": "string",
                    "description": "Download link (`https://api.navlo.io/api/ai/d/…`). Open it with a plain GET, no key: it redirects to the file. Keep it private until it expires."
                  },
                  {
                    "name": "expiresAt",
                    "type": "timestamp",
                    "description": "When the link stops working (UTC), 7 days after generation."
                  }
                ]
              },
              "requestExamples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl -X POST \"https://api.navlo.io/v1/reports\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"type\": \"STATUS\",\n    \"filters\": {\n      \"status\": [\n        \"active\"\n      ],\n      \"customerRef\": \"C-1042\"\n    }\n  }'"
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const res = await fetch('https://api.navlo.io/v1/reports', {\n  method: 'POST',\n  headers: {\n    'X-API-Key': process.env.NAVLO_API_KEY,\n    'Content-Type': 'application/json',\n  },\n  body: JSON.stringify({\n    type: 'STATUS',\n    filters: { status: ['active'], customerRef: 'C-1042' },\n  }),\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\nconst report = await res.json()"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.post(\n    \"https://api.navlo.io/v1/reports\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    json={\n        \"type\": \"STATUS\",\n        \"filters\": {\"status\": [\"active\"], \"customerRef\": \"C-1042\"},\n    },\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\nreport = r.json()"
                }
              ],
              "responseExamples": [
                {
                  "status": 201,
                  "contentType": "application/json",
                  "body": "{\n  \"type\": \"STATUS\",\n  \"fileName\": \"shipment-status-report-20261022.xlsx\",\n  \"url\": \"https://api.navlo.io/api/ai/d/AbC123.xYz789\",\n  \"expiresAt\": \"2026-10-29T09:20:13Z\"\n}"
                }
              ],
              "errors": [
                {
                  "status": 400,
                  "message": "type must be one of STATUS, COST, DND_RISK",
                  "when": "A `type` outside the list."
                },
                {
                  "status": 400,
                  "message": "Unsupported report filter createdFrom. Supported: …",
                  "when": "A filter key the report can’t apply — the message lists the supported keys."
                },
                {
                  "status": 400,
                  "message": "from and to only apply to COST reports",
                  "when": "A period on STATUS or DND_RISK."
                },
                {
                  "status": 400,
                  "message": "status does not apply to COST reports",
                  "when": "`status` on COST."
                },
                {
                  "status": 400,
                  "message": "originPort does not apply to COST reports; use originCountry",
                  "when": "`originPort` on COST."
                },
                {
                  "status": 400,
                  "message": "shipments cannot be combined with other filters on STATUS and DND_RISK reports",
                  "when": "`shipments` plus another filter."
                },
                {
                  "status": 400,
                  "message": "Unknown customerRef C-9999",
                  "when": "No customer has that reference."
                },
                {
                  "status": 400,
                  "message": "Unknown tag VIP",
                  "when": "A `tag` name that matches none of your tags — refused rather than ignored, so the report is never wider than asked."
                },
                {
                  "status": 400,
                  "message": "Send customerId or customerRef, not both",
                  "when": "Both were sent."
                },
                {
                  "status": 400,
                  "message": "customerId, customerRef and tag do not apply to COST reports",
                  "when": "One of them on COST."
                },
                {
                  "status": 400,
                  "message": "At most 100 shipments per report",
                  "when": "More than 100 identifiers."
                },
                {
                  "status": 500,
                  "message": "The report could not be generated. Please try again.",
                  "when": "Generation failed — retry."
                },
                {
                  "status": 400,
                  "message": "Request body is missing or is not valid JSON",
                  "when": "The body could not be parsed."
                },
                {
                  "status": 401,
                  "message": "Invalid or revoked API key",
                  "when": "The X-API-Key header is missing, wrong or revoked."
                },
                {
                  "status": 429,
                  "message": "Rate limit exceeded (60 requests/minute)",
                  "when": "Over the per-key budget; wait Retry-After seconds."
                }
              ],
              "notes": []
            },
            {
              "kind": "heading",
              "id": "reports-contents",
              "title": "What each report contains"
            },
            {
              "kind": "definitions",
              "items": [
                {
                  "term": "`STATUS`",
                  "description": "Sheet “Shipments”, one row per shipment (up to 500): Identifier, Type, Mode, Status, Carrier, Vessel/Flight, Origin Port, Origin Country, Destination Port, Destination Country, ETA (UTC), Transshipments, Tracked By."
                },
                {
                  "term": "`COST`",
                  "description": "Sheet “Cost Analysis”: Metric and Value rows — the period’s cost figures by carrier, route and port."
                },
                {
                  "term": "`DND_RISK`",
                  "description": "Sheet “D&D Risk”, one row per shipment (up to 200): Container/BL, Carrier, Origin, Destination, Status, ETA, Free time (days), Days remaining, Notes."
                }
              ]
            },
            {
              "kind": "callout",
              "tone": "tip",
              "text": "Prefer data to files? Every figure in these reports is also available as JSON: shipments from [`GET /v1/shipments`](/developers/shipments#shipments-list), D&D per shipment with [`include=dnd`](/developers/shipment-intelligence#intelligence-dnd). Shipment MEDU1234562 shows up in all three."
            },
            {
              "kind": "list",
              "ordered": false,
              "items": [
                "Report links work without an API key — anyone holding the link can download the file until it expires.",
                "Reports run on your data at the moment you call; generate a new one for fresh figures.",
                "STATUS and DND_RISK reports take `customerId` or `customerRef`, and `tag` — a per-customer report is one call. COST takes none of the three; for per-customer figures use the [usage report](/developers/usage-and-credits#usage-report)."
              ]
            }
          ]
        }
      ]
    },
    {
      "id": "customers-billing",
      "title": "Customers & billing",
      "pages": [
        {
          "id": "customers",
          "title": "Customers",
          "summary": "The companies you work for — called Companies in the app — with your own reference on each, so usage maps onto your billing.",
          "blocks": [
            {
              "kind": "prose",
              "text": "Customers are the companies on the app’s **Companies** page. Give each one your own reference (`ref`) — the code your ERP or accounting system uses — and you can put shipments, vessel follows and Navlo AI questions on customers by that code, then pull per-customer usage for [re-billing](/developers/usage-and-credits#usage-rebilling)."
            },
            {
              "kind": "heading",
              "id": "customers-ref",
              "title": "References"
            },
            {
              "kind": "list",
              "ordered": false,
              "items": [
                "`ref` is optional, up to 100 characters, unique in your organization, matched ignoring case and surrounding spaces.",
                "Sending `customer: { \"ref\": \"C-1042\", \"name\": \"Acme Trading Ltd.\" }` on a shipment creates the customer when the ref is new, so you don’t have to create customers up front.",
                "In the app the reference shows as **Your reference** on the Companies page and can be edited there, or added through the bulk import."
              ]
            },
            {
              "kind": "endpoint",
              "id": "customers-list",
              "method": "GET",
              "path": "/v1/customers",
              "summary": "List customers",
              "description": [],
              "auth": "apiKey",
              "rateLimit": "general",
              "since": "2026-10-22",
              "pathParams": [],
              "queryParams": [
                {
                  "name": "search",
                  "type": "string",
                  "required": false,
                  "description": "Matches the name or the reference."
                },
                {
                  "name": "ref",
                  "type": "string",
                  "required": false,
                  "description": "Exact reference (ignoring case) — returns at most one customer."
                },
                {
                  "name": "includeArchived",
                  "type": "boolean",
                  "required": false,
                  "description": "Include archived customers.",
                  "defaultValue": "false"
                },
                {
                  "name": "page",
                  "type": "integer",
                  "required": false,
                  "description": "Zero-based page index.",
                  "defaultValue": "0"
                },
                {
                  "name": "size",
                  "type": "integer",
                  "required": false,
                  "description": "Page size, 1–100 (values outside are clamped).",
                  "defaultValue": "20"
                }
              ],
              "headers": [],
              "response": {
                "status": 200,
                "contentType": "application/json",
                "fields": [
                  {
                    "name": "page",
                    "type": "integer",
                    "description": "Page index."
                  },
                  {
                    "name": "size",
                    "type": "integer",
                    "description": "Page size."
                  },
                  {
                    "name": "totalElements",
                    "type": "integer",
                    "description": "Matching customers."
                  },
                  {
                    "name": "totalPages",
                    "type": "integer",
                    "description": "Pages at this size."
                  },
                  {
                    "name": "customers",
                    "type": "array<object>",
                    "description": "The customers, fields as on [retrieve](#customers-get)."
                  }
                ]
              },
              "requestExamples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl \"https://api.navlo.io/v1/customers?search=foods\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\""
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const params = new URLSearchParams({ search: 'foods' })\n\nconst res = await fetch(`https://api.navlo.io/v1/customers?${params}`, {\n  headers: { 'X-API-Key': process.env.NAVLO_API_KEY },\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\nconst page = await res.json()"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.get(\n    \"https://api.navlo.io/v1/customers\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    params={\"search\": \"foods\"},\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\npage = r.json()"
                }
              ],
              "responseExamples": [
                {
                  "status": 200,
                  "contentType": "application/json",
                  "body": "{\n  \"page\": 0,\n  \"size\": 20,\n  \"totalElements\": 1,\n  \"totalPages\": 1,\n  \"customers\": [\n    {\n      \"id\": \"5a8e1f47-9c3d-4b26-8e71-0f4c2d9b6a13\",\n      \"ref\": \"C-2107\",\n      \"name\": \"Sample Foods Ltd.\",\n      \"taxId\": null,\n      \"address\": null,\n      \"city\": \"Bursa\",\n      \"countryCode\": \"TR\",\n      \"archived\": false,\n      \"contacts\": [],\n      \"shipmentCount\": 19,\n      \"createdAt\": \"2026-10-18T11:02:51Z\",\n      \"updatedAt\": \"2026-10-18T11:02:51Z\"\n    }\n  ]\n}"
                }
              ],
              "errors": [
                {
                  "status": 401,
                  "message": "Invalid or revoked API key",
                  "when": "The X-API-Key header is missing, wrong or revoked."
                },
                {
                  "status": 429,
                  "message": "Rate limit exceeded (60 requests/minute)",
                  "when": "Over the per-key budget; wait Retry-After seconds."
                }
              ],
              "notes": []
            },
            {
              "kind": "endpoint",
              "id": "customers-create",
              "method": "POST",
              "path": "/v1/customers",
              "summary": "Create a customer",
              "description": [],
              "auth": "apiKey",
              "rateLimit": "general",
              "since": "2026-10-22",
              "pathParams": [],
              "queryParams": [],
              "headers": [],
              "body": {
                "contentType": "application/json",
                "fields": [
                  {
                    "name": "name",
                    "type": "string",
                    "required": true,
                    "description": "Company name, up to 200 characters, unique in your organization."
                  },
                  {
                    "name": "ref",
                    "type": "string",
                    "required": false,
                    "description": "Your reference, up to 100 characters, unique."
                  },
                  {
                    "name": "taxId",
                    "type": "string",
                    "required": false,
                    "description": "Tax / VAT number, up to 100 characters."
                  },
                  {
                    "name": "address",
                    "type": "string",
                    "required": false,
                    "description": "Street address."
                  },
                  {
                    "name": "city",
                    "type": "string",
                    "required": false,
                    "description": "City, up to 100 characters."
                  },
                  {
                    "name": "countryCode",
                    "type": "string",
                    "required": false,
                    "description": "ISO 3166-1 alpha-2 (`TR`, `DE`); stored upper-case."
                  },
                  {
                    "name": "contacts",
                    "type": "array<object>",
                    "required": false,
                    "description": "People at the customer."
                  },
                  {
                    "name": "contacts[].name",
                    "type": "string",
                    "required": true,
                    "description": "Full name, up to 200 characters."
                  },
                  {
                    "name": "contacts[].email",
                    "type": "string",
                    "required": false,
                    "description": "Email (stored lower-cased), up to 320 characters."
                  },
                  {
                    "name": "contacts[].phone",
                    "type": "string",
                    "required": false,
                    "description": "Phone, up to 50 characters, any format."
                  },
                  {
                    "name": "contacts[].role",
                    "type": "string",
                    "required": false,
                    "description": "Free text, up to 100 characters, e.g. \"Import manager\"."
                  },
                  {
                    "name": "contacts[].primary",
                    "type": "boolean",
                    "required": false,
                    "description": "The main contact. At most one; if several are flagged, the first wins.",
                    "defaultValue": "false"
                  }
                ]
              },
              "response": {
                "status": 201,
                "contentType": "application/json",
                "fields": [
                  {
                    "name": "id",
                    "type": "uuid",
                    "description": "Navlo’s customer id."
                  },
                  {
                    "name": "ref",
                    "type": "string",
                    "nullable": true,
                    "description": "Your reference — the code your own systems use."
                  },
                  {
                    "name": "name",
                    "type": "string",
                    "description": "Company name."
                  },
                  {
                    "name": "taxId",
                    "type": "string",
                    "nullable": true,
                    "description": "Tax / VAT number."
                  },
                  {
                    "name": "address",
                    "type": "string",
                    "nullable": true,
                    "description": "Street address."
                  },
                  {
                    "name": "city",
                    "type": "string",
                    "nullable": true,
                    "description": "City."
                  },
                  {
                    "name": "countryCode",
                    "type": "string",
                    "nullable": true,
                    "description": "ISO 3166-1 alpha-2, e.g. `TR`."
                  },
                  {
                    "name": "archived",
                    "type": "boolean",
                    "description": "Archived customers are hidden from lists unless asked for and can’t be put on new shipments."
                  },
                  {
                    "name": "contacts",
                    "type": "array<object>",
                    "description": "People at the customer — `name`, `email`, `phone`, `role`, `primary` — the primary contact first, then by name."
                  },
                  {
                    "name": "shipmentCount",
                    "type": "integer",
                    "description": "Shipments currently assigned to the customer."
                  },
                  {
                    "name": "createdAt",
                    "type": "timestamp",
                    "description": "Created (UTC)."
                  },
                  {
                    "name": "updatedAt",
                    "type": "timestamp",
                    "description": "Last changed (UTC)."
                  }
                ]
              },
              "requestExamples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl -X POST \"https://api.navlo.io/v1/customers\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"name\": \"Acme Trading Ltd.\",\n    \"ref\": \"C-1042\",\n    \"taxId\": \"1234567890\",\n    \"city\": \"İzmir\",\n    \"countryCode\": \"TR\",\n    \"contacts\": [\n      {\n        \"name\": \"Deniz Kaya\",\n        \"email\": \"deniz.kaya@acme-trading.example\",\n        \"role\": \"Import manager\",\n        \"primary\": true\n      }\n    ]\n  }'"
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const res = await fetch('https://api.navlo.io/v1/customers', {\n  method: 'POST',\n  headers: {\n    'X-API-Key': process.env.NAVLO_API_KEY,\n    'Content-Type': 'application/json',\n  },\n  body: JSON.stringify({\n    name: 'Acme Trading Ltd.',\n    ref: 'C-1042',\n    taxId: '1234567890',\n    city: 'İzmir',\n    countryCode: 'TR',\n    contacts: [\n      {\n        name: 'Deniz Kaya',\n        email: 'deniz.kaya@acme-trading.example',\n        role: 'Import manager',\n        primary: true,\n      },\n    ],\n  }),\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\nconst customer = await res.json()"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.post(\n    \"https://api.navlo.io/v1/customers\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    json={\n        \"name\": \"Acme Trading Ltd.\",\n        \"ref\": \"C-1042\",\n        \"taxId\": \"1234567890\",\n        \"city\": \"İzmir\",\n        \"countryCode\": \"TR\",\n        \"contacts\": [\n            {\n                \"name\": \"Deniz Kaya\",\n                \"email\": \"deniz.kaya@acme-trading.example\",\n                \"role\": \"Import manager\",\n                \"primary\": True,\n            },\n        ],\n    },\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\ncustomer = r.json()"
                }
              ],
              "responseExamples": [
                {
                  "status": 201,
                  "contentType": "application/json",
                  "body": "{\n  \"id\": \"c7d2a9e4-3f1b-4e8a-9b6c-1d5e7f3a2b90\",\n  \"ref\": \"C-1042\",\n  \"name\": \"Acme Trading Ltd.\",\n  \"taxId\": \"1234567890\",\n  \"address\": \"Liman Cad. No: 12, 35210\",\n  \"city\": \"İzmir\",\n  \"countryCode\": \"TR\",\n  \"archived\": false,\n  \"contacts\": [\n    {\n      \"name\": \"Deniz Kaya\",\n      \"email\": \"deniz.kaya@acme-trading.example\",\n      \"phone\": \"+90 232 000 00 00\",\n      \"role\": \"Import manager\",\n      \"primary\": true\n    }\n  ],\n  \"shipmentCount\": 0,\n  \"createdAt\": \"2026-06-11T08:02:19Z\",\n  \"updatedAt\": \"2026-06-11T08:02:19Z\"\n}"
                }
              ],
              "errors": [
                {
                  "status": 400,
                  "message": "name cannot be empty",
                  "when": "`name` missing or blank."
                },
                {
                  "status": 400,
                  "message": "countryCode: must be an ISO 3166-1 alpha-2 code",
                  "when": "A `countryCode` that isn’t two letters."
                },
                {
                  "status": 409,
                  "message": "A customer with this reference already exists",
                  "when": "Another customer has this `ref` (ignoring case)."
                },
                {
                  "status": 400,
                  "message": "A customer named \"Acme Trading Ltd.\" already exists.",
                  "when": "The name is taken (ignoring case)."
                },
                {
                  "status": 400,
                  "message": "An archived customer named \"Acme Trading Ltd.\" already exists. Restore it from Show archived.",
                  "when": "An archived customer has the name — restore it instead."
                },
                {
                  "status": 400,
                  "message": "Request body is missing or is not valid JSON",
                  "when": "The body could not be parsed."
                },
                {
                  "status": 401,
                  "message": "Invalid or revoked API key",
                  "when": "The X-API-Key header is missing, wrong or revoked."
                },
                {
                  "status": 429,
                  "message": "Rate limit exceeded (60 requests/minute)",
                  "when": "Over the per-key budget; wait Retry-After seconds."
                }
              ],
              "notes": []
            },
            {
              "kind": "endpoint",
              "id": "customers-get",
              "method": "GET",
              "path": "/v1/customers/{id}",
              "summary": "Retrieve a customer",
              "description": [],
              "auth": "apiKey",
              "rateLimit": "general",
              "since": "2026-10-22",
              "pathParams": [
                {
                  "name": "id",
                  "type": "uuid",
                  "required": true,
                  "description": "The customer id."
                }
              ],
              "queryParams": [],
              "headers": [],
              "response": {
                "status": 200,
                "contentType": "application/json",
                "fields": [
                  {
                    "name": "id",
                    "type": "uuid",
                    "description": "Navlo’s customer id."
                  },
                  {
                    "name": "ref",
                    "type": "string",
                    "nullable": true,
                    "description": "Your reference — the code your own systems use."
                  },
                  {
                    "name": "name",
                    "type": "string",
                    "description": "Company name."
                  },
                  {
                    "name": "taxId",
                    "type": "string",
                    "nullable": true,
                    "description": "Tax / VAT number."
                  },
                  {
                    "name": "address",
                    "type": "string",
                    "nullable": true,
                    "description": "Street address."
                  },
                  {
                    "name": "city",
                    "type": "string",
                    "nullable": true,
                    "description": "City."
                  },
                  {
                    "name": "countryCode",
                    "type": "string",
                    "nullable": true,
                    "description": "ISO 3166-1 alpha-2, e.g. `TR`."
                  },
                  {
                    "name": "archived",
                    "type": "boolean",
                    "description": "Archived customers are hidden from lists unless asked for and can’t be put on new shipments."
                  },
                  {
                    "name": "contacts",
                    "type": "array<object>",
                    "description": "People at the customer — `name`, `email`, `phone`, `role`, `primary` — the primary contact first, then by name."
                  },
                  {
                    "name": "shipmentCount",
                    "type": "integer",
                    "description": "Shipments currently assigned to the customer."
                  },
                  {
                    "name": "createdAt",
                    "type": "timestamp",
                    "description": "Created (UTC)."
                  },
                  {
                    "name": "updatedAt",
                    "type": "timestamp",
                    "description": "Last changed (UTC)."
                  }
                ]
              },
              "requestExamples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl \"https://api.navlo.io/v1/customers/c7d2a9e4-3f1b-4e8a-9b6c-1d5e7f3a2b90\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\""
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const res = await fetch('https://api.navlo.io/v1/customers/c7d2a9e4-3f1b-4e8a-9b6c-1d5e7f3a2b90', {\n  headers: { 'X-API-Key': process.env.NAVLO_API_KEY },\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\nconst customer = await res.json()"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.get(\n    \"https://api.navlo.io/v1/customers/c7d2a9e4-3f1b-4e8a-9b6c-1d5e7f3a2b90\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\ncustomer = r.json()"
                }
              ],
              "responseExamples": [
                {
                  "status": 200,
                  "contentType": "application/json",
                  "body": "{\n  \"id\": \"c7d2a9e4-3f1b-4e8a-9b6c-1d5e7f3a2b90\",\n  \"ref\": \"C-1042\",\n  \"name\": \"Acme Trading Ltd.\",\n  \"taxId\": \"1234567890\",\n  \"address\": \"Liman Cad. No: 12, 35210\",\n  \"city\": \"İzmir\",\n  \"countryCode\": \"TR\",\n  \"archived\": false,\n  \"contacts\": [\n    {\n      \"name\": \"Deniz Kaya\",\n      \"email\": \"deniz.kaya@acme-trading.example\",\n      \"phone\": \"+90 232 000 00 00\",\n      \"role\": \"Import manager\",\n      \"primary\": true\n    },\n    {\n      \"name\": \"Murat Demir\",\n      \"email\": \"murat.demir@acme-trading.example\",\n      \"phone\": null,\n      \"role\": \"Customs\",\n      \"primary\": false\n    }\n  ],\n  \"shipmentCount\": 38,\n  \"createdAt\": \"2026-06-11T08:02:19Z\",\n  \"updatedAt\": \"2026-10-22T08:41:55Z\"\n}"
                }
              ],
              "errors": [
                {
                  "status": 404,
                  "message": "Customer not found",
                  "when": "Unknown id, or another organization’s customer."
                },
                {
                  "status": 401,
                  "message": "Invalid or revoked API key",
                  "when": "The X-API-Key header is missing, wrong or revoked."
                },
                {
                  "status": 429,
                  "message": "Rate limit exceeded (60 requests/minute)",
                  "when": "Over the per-key budget; wait Retry-After seconds."
                }
              ],
              "notes": []
            },
            {
              "kind": "endpoint",
              "id": "customers-update",
              "method": "PATCH",
              "path": "/v1/customers/{id}",
              "summary": "Update a customer",
              "description": [
                "A merge patch: only the keys you send change. `null` or `\"\"` clears an optional field. `contacts`, when sent, replaces the whole list — send the full list you want to keep; `\"contacts\": null` removes them all. `name` can’t be cleared."
              ],
              "auth": "apiKey",
              "rateLimit": "general",
              "since": "2026-10-22",
              "pathParams": [
                {
                  "name": "id",
                  "type": "uuid",
                  "required": true,
                  "description": "The customer id."
                }
              ],
              "queryParams": [],
              "headers": [],
              "body": {
                "contentType": "application/json",
                "fields": [
                  {
                    "name": "name",
                    "type": "string",
                    "required": false,
                    "description": "New name."
                  },
                  {
                    "name": "ref",
                    "type": "string | null",
                    "required": false,
                    "description": "New reference, or `null` / `\"\"` to remove it."
                  },
                  {
                    "name": "taxId",
                    "type": "string | null",
                    "required": false,
                    "description": "Tax / VAT number."
                  },
                  {
                    "name": "address",
                    "type": "string | null",
                    "required": false,
                    "description": "Street address."
                  },
                  {
                    "name": "city",
                    "type": "string | null",
                    "required": false,
                    "description": "City."
                  },
                  {
                    "name": "countryCode",
                    "type": "string | null",
                    "required": false,
                    "description": "ISO alpha-2 country."
                  },
                  {
                    "name": "contacts",
                    "type": "array<object> | null",
                    "required": false,
                    "description": "The complete new contact list; `null` removes all contacts."
                  }
                ]
              },
              "response": {
                "status": 200,
                "contentType": "application/json",
                "fields": [
                  {
                    "name": "id",
                    "type": "uuid",
                    "description": "Navlo’s customer id."
                  },
                  {
                    "name": "ref",
                    "type": "string",
                    "nullable": true,
                    "description": "Your reference — the code your own systems use."
                  },
                  {
                    "name": "name",
                    "type": "string",
                    "description": "Company name."
                  },
                  {
                    "name": "taxId",
                    "type": "string",
                    "nullable": true,
                    "description": "Tax / VAT number."
                  },
                  {
                    "name": "address",
                    "type": "string",
                    "nullable": true,
                    "description": "Street address."
                  },
                  {
                    "name": "city",
                    "type": "string",
                    "nullable": true,
                    "description": "City."
                  },
                  {
                    "name": "countryCode",
                    "type": "string",
                    "nullable": true,
                    "description": "ISO 3166-1 alpha-2, e.g. `TR`."
                  },
                  {
                    "name": "archived",
                    "type": "boolean",
                    "description": "Archived customers are hidden from lists unless asked for and can’t be put on new shipments."
                  },
                  {
                    "name": "contacts",
                    "type": "array<object>",
                    "description": "People at the customer — `name`, `email`, `phone`, `role`, `primary` — the primary contact first, then by name."
                  },
                  {
                    "name": "shipmentCount",
                    "type": "integer",
                    "description": "Shipments currently assigned to the customer."
                  },
                  {
                    "name": "createdAt",
                    "type": "timestamp",
                    "description": "Created (UTC)."
                  },
                  {
                    "name": "updatedAt",
                    "type": "timestamp",
                    "description": "Last changed (UTC)."
                  }
                ]
              },
              "requestExamples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl -X PATCH \"https://api.navlo.io/v1/customers/c7d2a9e4-3f1b-4e8a-9b6c-1d5e7f3a2b90\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"address\": \"Liman Cad. No: 12, 35210\"\n  }'"
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const res = await fetch('https://api.navlo.io/v1/customers/c7d2a9e4-3f1b-4e8a-9b6c-1d5e7f3a2b90', {\n  method: 'PATCH',\n  headers: {\n    'X-API-Key': process.env.NAVLO_API_KEY,\n    'Content-Type': 'application/json',\n  },\n  body: JSON.stringify({ address: 'Liman Cad. No: 12, 35210' }),\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\nconst customer = await res.json()"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.patch(\n    \"https://api.navlo.io/v1/customers/c7d2a9e4-3f1b-4e8a-9b6c-1d5e7f3a2b90\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    json={\"address\": \"Liman Cad. No: 12, 35210\"},\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\ncustomer = r.json()"
                }
              ],
              "responseExamples": [
                {
                  "status": 200,
                  "contentType": "application/json",
                  "body": "{\n  \"id\": \"c7d2a9e4-3f1b-4e8a-9b6c-1d5e7f3a2b90\",\n  \"ref\": \"C-1042\",\n  \"name\": \"Acme Trading Ltd.\",\n  \"taxId\": \"1234567890\",\n  \"address\": \"Liman Cad. No: 12, 35210\",\n  \"city\": \"İzmir\",\n  \"countryCode\": \"TR\",\n  \"archived\": false,\n  \"contacts\": [\n    {\n      \"name\": \"Deniz Kaya\",\n      \"email\": \"deniz.kaya@acme-trading.example\",\n      \"phone\": \"+90 232 000 00 00\",\n      \"role\": \"Import manager\",\n      \"primary\": true\n    },\n    {\n      \"name\": \"Murat Demir\",\n      \"email\": \"murat.demir@acme-trading.example\",\n      \"phone\": null,\n      \"role\": \"Customs\",\n      \"primary\": false\n    }\n  ],\n  \"shipmentCount\": 38,\n  \"createdAt\": \"2026-06-11T08:02:19Z\",\n  \"updatedAt\": \"2026-10-22T08:41:55Z\"\n}"
                }
              ],
              "errors": [
                {
                  "status": 404,
                  "message": "Customer not found",
                  "when": "Unknown id, or another organization’s customer."
                },
                {
                  "status": 400,
                  "message": "name cannot be empty",
                  "when": "`name` sent blank or `null`."
                },
                {
                  "status": 400,
                  "message": "Request body must be a JSON object",
                  "when": "The body is not a JSON object."
                },
                {
                  "status": 409,
                  "message": "A customer with this reference already exists",
                  "when": "Another customer has this `ref` (ignoring case)."
                },
                {
                  "status": 400,
                  "message": "A customer named \"Acme Trading Ltd.\" already exists.",
                  "when": "The name is taken (ignoring case)."
                },
                {
                  "status": 400,
                  "message": "An archived customer named \"Acme Trading Ltd.\" already exists. Restore it from Show archived.",
                  "when": "An archived customer has the name — restore it instead."
                },
                {
                  "status": 401,
                  "message": "Invalid or revoked API key",
                  "when": "The X-API-Key header is missing, wrong or revoked."
                },
                {
                  "status": 429,
                  "message": "Rate limit exceeded (60 requests/minute)",
                  "when": "Over the per-key budget; wait Retry-After seconds."
                }
              ],
              "notes": []
            },
            {
              "kind": "endpoint",
              "id": "customers-archive",
              "method": "POST",
              "path": "/v1/customers/{id}/archive",
              "summary": "Archive a customer",
              "description": [
                "Hides the customer from lists and stops it being put on new shipments; its shipments keep it and its history stays. Idempotent. Customers are archived, never deleted."
              ],
              "auth": "apiKey",
              "rateLimit": "general",
              "since": "2026-10-22",
              "pathParams": [
                {
                  "name": "id",
                  "type": "uuid",
                  "required": true,
                  "description": "The customer id."
                }
              ],
              "queryParams": [],
              "headers": [],
              "response": {
                "status": 200,
                "contentType": "application/json",
                "fields": [
                  {
                    "name": "id",
                    "type": "uuid",
                    "description": "Navlo’s customer id."
                  },
                  {
                    "name": "ref",
                    "type": "string",
                    "nullable": true,
                    "description": "Your reference — the code your own systems use."
                  },
                  {
                    "name": "name",
                    "type": "string",
                    "description": "Company name."
                  },
                  {
                    "name": "taxId",
                    "type": "string",
                    "nullable": true,
                    "description": "Tax / VAT number."
                  },
                  {
                    "name": "address",
                    "type": "string",
                    "nullable": true,
                    "description": "Street address."
                  },
                  {
                    "name": "city",
                    "type": "string",
                    "nullable": true,
                    "description": "City."
                  },
                  {
                    "name": "countryCode",
                    "type": "string",
                    "nullable": true,
                    "description": "ISO 3166-1 alpha-2, e.g. `TR`."
                  },
                  {
                    "name": "archived",
                    "type": "boolean",
                    "description": "Archived customers are hidden from lists unless asked for and can’t be put on new shipments."
                  },
                  {
                    "name": "contacts",
                    "type": "array<object>",
                    "description": "People at the customer — `name`, `email`, `phone`, `role`, `primary` — the primary contact first, then by name."
                  },
                  {
                    "name": "shipmentCount",
                    "type": "integer",
                    "description": "Shipments currently assigned to the customer."
                  },
                  {
                    "name": "createdAt",
                    "type": "timestamp",
                    "description": "Created (UTC)."
                  },
                  {
                    "name": "updatedAt",
                    "type": "timestamp",
                    "description": "Last changed (UTC)."
                  }
                ]
              },
              "requestExamples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl -X POST \"https://api.navlo.io/v1/customers/5a8e1f47-9c3d-4b26-8e71-0f4c2d9b6a13/archive\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\""
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const res = await fetch('https://api.navlo.io/v1/customers/5a8e1f47-9c3d-4b26-8e71-0f4c2d9b6a13/archive', {\n  method: 'POST',\n  headers: { 'X-API-Key': process.env.NAVLO_API_KEY },\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\nconst customer = await res.json()"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.post(\n    \"https://api.navlo.io/v1/customers/5a8e1f47-9c3d-4b26-8e71-0f4c2d9b6a13/archive\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\ncustomer = r.json()"
                }
              ],
              "responseExamples": [
                {
                  "status": 200,
                  "contentType": "application/json",
                  "body": "{\n  \"id\": \"5a8e1f47-9c3d-4b26-8e71-0f4c2d9b6a13\",\n  \"ref\": \"C-2107\",\n  \"name\": \"Sample Foods Ltd.\",\n  \"taxId\": null,\n  \"address\": null,\n  \"city\": \"Bursa\",\n  \"countryCode\": \"TR\",\n  \"archived\": true,\n  \"contacts\": [],\n  \"shipmentCount\": 19,\n  \"createdAt\": \"2026-10-18T11:02:51Z\",\n  \"updatedAt\": \"2026-10-22T09:30:00Z\"\n}"
                }
              ],
              "errors": [
                {
                  "status": 404,
                  "message": "Customer not found",
                  "when": "Unknown id, or another organization’s customer."
                },
                {
                  "status": 401,
                  "message": "Invalid or revoked API key",
                  "when": "The X-API-Key header is missing, wrong or revoked."
                },
                {
                  "status": 429,
                  "message": "Rate limit exceeded (60 requests/minute)",
                  "when": "Over the per-key budget; wait Retry-After seconds."
                }
              ],
              "notes": []
            },
            {
              "kind": "endpoint",
              "id": "customers-restore",
              "method": "POST",
              "path": "/v1/customers/{id}/restore",
              "summary": "Restore a customer",
              "description": [
                "Brings an archived customer back. Idempotent."
              ],
              "auth": "apiKey",
              "rateLimit": "general",
              "since": "2026-10-22",
              "pathParams": [
                {
                  "name": "id",
                  "type": "uuid",
                  "required": true,
                  "description": "The customer id."
                }
              ],
              "queryParams": [],
              "headers": [],
              "response": {
                "status": 200,
                "contentType": "application/json",
                "fields": [
                  {
                    "name": "id",
                    "type": "uuid",
                    "description": "Navlo’s customer id."
                  },
                  {
                    "name": "ref",
                    "type": "string",
                    "nullable": true,
                    "description": "Your reference — the code your own systems use."
                  },
                  {
                    "name": "name",
                    "type": "string",
                    "description": "Company name."
                  },
                  {
                    "name": "taxId",
                    "type": "string",
                    "nullable": true,
                    "description": "Tax / VAT number."
                  },
                  {
                    "name": "address",
                    "type": "string",
                    "nullable": true,
                    "description": "Street address."
                  },
                  {
                    "name": "city",
                    "type": "string",
                    "nullable": true,
                    "description": "City."
                  },
                  {
                    "name": "countryCode",
                    "type": "string",
                    "nullable": true,
                    "description": "ISO 3166-1 alpha-2, e.g. `TR`."
                  },
                  {
                    "name": "archived",
                    "type": "boolean",
                    "description": "Archived customers are hidden from lists unless asked for and can’t be put on new shipments."
                  },
                  {
                    "name": "contacts",
                    "type": "array<object>",
                    "description": "People at the customer — `name`, `email`, `phone`, `role`, `primary` — the primary contact first, then by name."
                  },
                  {
                    "name": "shipmentCount",
                    "type": "integer",
                    "description": "Shipments currently assigned to the customer."
                  },
                  {
                    "name": "createdAt",
                    "type": "timestamp",
                    "description": "Created (UTC)."
                  },
                  {
                    "name": "updatedAt",
                    "type": "timestamp",
                    "description": "Last changed (UTC)."
                  }
                ]
              },
              "requestExamples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl -X POST \"https://api.navlo.io/v1/customers/5a8e1f47-9c3d-4b26-8e71-0f4c2d9b6a13/restore\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\""
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const res = await fetch('https://api.navlo.io/v1/customers/5a8e1f47-9c3d-4b26-8e71-0f4c2d9b6a13/restore', {\n  method: 'POST',\n  headers: { 'X-API-Key': process.env.NAVLO_API_KEY },\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\nconst customer = await res.json()"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.post(\n    \"https://api.navlo.io/v1/customers/5a8e1f47-9c3d-4b26-8e71-0f4c2d9b6a13/restore\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\ncustomer = r.json()"
                }
              ],
              "responseExamples": [
                {
                  "status": 200,
                  "contentType": "application/json",
                  "body": "{\n  \"id\": \"5a8e1f47-9c3d-4b26-8e71-0f4c2d9b6a13\",\n  \"ref\": \"C-2107\",\n  \"name\": \"Sample Foods Ltd.\",\n  \"taxId\": null,\n  \"address\": null,\n  \"city\": \"Bursa\",\n  \"countryCode\": \"TR\",\n  \"archived\": false,\n  \"contacts\": [],\n  \"shipmentCount\": 19,\n  \"createdAt\": \"2026-10-18T11:02:51Z\",\n  \"updatedAt\": \"2026-10-22T09:31:12Z\"\n}"
                }
              ],
              "errors": [
                {
                  "status": 404,
                  "message": "Customer not found",
                  "when": "Unknown id, or another organization’s customer."
                },
                {
                  "status": 401,
                  "message": "Invalid or revoked API key",
                  "when": "The X-API-Key header is missing, wrong or revoked."
                },
                {
                  "status": 429,
                  "message": "Rate limit exceeded (60 requests/minute)",
                  "when": "Over the per-key budget; wait Retry-After seconds."
                }
              ],
              "notes": []
            },
            {
              "kind": "callout",
              "tone": "info",
              "text": "An archived customer still resolves by `ref`, but can’t be put on a shipment until it is restored — the request fails with `400 \"Sample Foods Ltd.\" is archived. Restore it before assigning shipments.` Restore it first."
            }
          ]
        },
        {
          "id": "usage-and-credits",
          "title": "Usage & credits",
          "summary": "Your balances, and a usage report per customer, shipment or day — everything you need to invoice your own customers.",
          "blocks": [
            {
              "kind": "prose",
              "text": "Navlo charges in credits: tracking credits for new shipments and vessel follows, AI credits for Navlo AI answers. These endpoints tell you what is left and where it went."
            },
            {
              "kind": "definitions",
              "items": [
                {
                  "term": "A new shipment",
                  "description": "1 tracking credit. Free when your organization already tracks the identifier or Navlo can’t track that carrier; refunded when no data is ever found."
                },
                {
                  "term": "A vessel follow",
                  "description": "2 tracking credits per voyage. Free when one of your tracked containers is on that vessel."
                },
                {
                  "term": "A Navlo AI answer",
                  "description": "AI credits — each answer’s amount is in its `creditsUsed` and in this report."
                }
              ]
            },
            {
              "kind": "endpoint",
              "id": "usage-credits",
              "method": "GET",
              "path": "/v1/credits",
              "summary": "Get balances",
              "description": [
                "The balances the key’s requests draw from — the key creator’s, which for an organization admin is the organization’s pool."
              ],
              "auth": "apiKey",
              "rateLimit": "general",
              "since": "2026-10-22",
              "pathParams": [],
              "queryParams": [],
              "headers": [],
              "response": {
                "status": 200,
                "contentType": "application/json",
                "fields": [
                  {
                    "name": "trackingCredits",
                    "type": "number",
                    "description": "Tracking credits available: shipments and vessel follows."
                  },
                  {
                    "name": "aiCredits",
                    "type": "number",
                    "description": "AI credits available: Navlo AI answers."
                  }
                ]
              },
              "requestExamples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl \"https://api.navlo.io/v1/credits\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\""
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const res = await fetch('https://api.navlo.io/v1/credits', {\n  headers: { 'X-API-Key': process.env.NAVLO_API_KEY },\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\nconst credits = await res.json()"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.get(\n    \"https://api.navlo.io/v1/credits\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\ncredits = r.json()"
                }
              ],
              "responseExamples": [
                {
                  "status": 200,
                  "contentType": "application/json",
                  "body": "{\n  \"trackingCredits\": 248,\n  \"aiCredits\": 14.3725\n}"
                }
              ],
              "errors": [
                {
                  "status": 401,
                  "message": "Invalid or revoked API key",
                  "when": "The X-API-Key header is missing, wrong or revoked."
                },
                {
                  "status": 429,
                  "message": "Rate limit exceeded (60 requests/minute)",
                  "when": "Over the per-key budget; wait Retry-After seconds."
                }
              ],
              "notes": []
            },
            {
              "kind": "endpoint",
              "id": "usage-report",
              "method": "GET",
              "path": "/v1/usage",
              "summary": "Usage report",
              "description": [
                "Credits your organization spent in a date range, grouped the way you invoice. Built from the credit ledger: tracking charges and refunds, vessel follows and Navlo AI answers.",
                "Attribution uses each item’s **current** customer when you run the report: a shipment’s credits follow its customer, a vessel follow’s its own customer, an AI answer its conversation’s customer. Re-assign a shipment and re-run the report to move its usage."
              ],
              "auth": "apiKey",
              "rateLimit": "general",
              "since": "2026-10-22",
              "pathParams": [],
              "queryParams": [
                {
                  "name": "from",
                  "type": "date",
                  "required": false,
                  "description": "First day included, `YYYY-MM-DD` (UTC). Sent alone: the calendar month starting there.",
                  "defaultValue": "first day of this month"
                },
                {
                  "name": "to",
                  "type": "date",
                  "required": false,
                  "description": "First day NOT included, `YYYY-MM-DD`; at most 366 days after `from`. Sent alone: the calendar month ending there.",
                  "defaultValue": "first day of next month"
                },
                {
                  "name": "groupBy",
                  "type": "enum",
                  "required": false,
                  "description": "One group per customer, per shipment or per day, or only totals.",
                  "values": [
                    "customer",
                    "shipment",
                    "day",
                    "none"
                  ],
                  "defaultValue": "customer"
                },
                {
                  "name": "customerId",
                  "type": "uuid",
                  "required": false,
                  "description": "Only this customer’s usage. Wins over `customerRef`."
                },
                {
                  "name": "customerRef",
                  "type": "string",
                  "required": false,
                  "description": "Only the usage of the customer with this reference."
                },
                {
                  "name": "format",
                  "type": "enum",
                  "required": false,
                  "description": "`csv` returns one line per ledger row instead (see below).",
                  "values": [
                    "json",
                    "csv"
                  ],
                  "defaultValue": "json"
                }
              ],
              "headers": [],
              "response": {
                "status": 200,
                "contentType": "application/json",
                "fields": [
                  {
                    "name": "from",
                    "type": "date",
                    "description": "The range start used."
                  },
                  {
                    "name": "to",
                    "type": "date",
                    "description": "The range end used (exclusive)."
                  },
                  {
                    "name": "groupBy",
                    "type": "enum",
                    "description": "The grouping used.",
                    "values": [
                      "customer",
                      "shipment",
                      "day",
                      "none"
                    ]
                  },
                  {
                    "name": "totals",
                    "type": "object",
                    "description": "The whole range: the six totals below."
                  },
                  {
                    "name": "totals.shipmentsStarted",
                    "type": "integer",
                    "description": "Shipments created in the range, free ones included."
                  },
                  {
                    "name": "totals.trackingCredits",
                    "type": "number",
                    "description": "Tracking credits charged for new shipments."
                  },
                  {
                    "name": "totals.refundedCredits",
                    "type": "number",
                    "description": "Tracking credits given back in the range, for example for identifiers that never produced data."
                  },
                  {
                    "name": "totals.vesselCredits",
                    "type": "number",
                    "description": "Credits charged for vessel follows."
                  },
                  {
                    "name": "totals.aiCredits",
                    "type": "number",
                    "description": "AI credits spent on Navlo AI answers."
                  },
                  {
                    "name": "totals.netCredits",
                    "type": "number",
                    "description": "`trackingCredits − refundedCredits + vesselCredits + aiCredits` — what to bill on."
                  },
                  {
                    "name": "groups",
                    "type": "array<object>",
                    "description": "One per customer / shipment / day; `[]` for `groupBy=none`. Each carries the six totals plus the keys below."
                  },
                  {
                    "name": "groups[].customer",
                    "type": "object",
                    "nullable": true,
                    "description": "`{ id, ref, name, countryCode }`; null for usage with no customer — the “Unassigned” group. Set on `groupBy=shipment` groups too."
                  },
                  {
                    "name": "groups[].shipment",
                    "type": "object",
                    "nullable": true,
                    "description": "`groupBy=shipment`: `{ id, identifier }`. Vessel and Navlo AI usage has no shipment: it comes after the shipments as one group per customer with `shipment: null`. Shipments started in the range without a charge appear with 0 credits."
                  },
                  {
                    "name": "groups[].day",
                    "type": "date",
                    "nullable": true,
                    "description": "`groupBy=day`: the UTC day, `YYYY-MM-DD`."
                  }
                ]
              },
              "requestExamples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl \"https://api.navlo.io/v1/usage?from=2026-10-01&to=2026-11-01&groupBy=customer\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\""
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const params = new URLSearchParams({ from: '2026-10-01', to: '2026-11-01', groupBy: 'customer' })\n\nconst res = await fetch(`https://api.navlo.io/v1/usage?${params}`, {\n  headers: { 'X-API-Key': process.env.NAVLO_API_KEY },\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\nconst usage = await res.json()"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.get(\n    \"https://api.navlo.io/v1/usage\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    params={\n        \"from\": \"2026-10-01\",\n        \"to\": \"2026-11-01\",\n        \"groupBy\": \"customer\",\n    },\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\nusage = r.json()"
                }
              ],
              "responseExamples": [
                {
                  "status": 200,
                  "label": "groupBy=customer",
                  "contentType": "application/json",
                  "body": "{\n  \"from\": \"2026-10-01\",\n  \"to\": \"2026-11-01\",\n  \"groupBy\": \"customer\",\n  \"totals\": {\n    \"shipmentsStarted\": 61,\n    \"trackingCredits\": 57,\n    \"refundedCredits\": 2,\n    \"vesselCredits\": 4,\n    \"aiCredits\": 1.8125,\n    \"netCredits\": 60.8125\n  },\n  \"groups\": [\n    {\n      \"customer\": {\n        \"id\": \"c7d2a9e4-3f1b-4e8a-9b6c-1d5e7f3a2b90\",\n        \"ref\": \"C-1042\",\n        \"name\": \"Acme Trading Ltd.\",\n        \"countryCode\": \"TR\"\n      },\n      \"shipment\": null,\n      \"day\": null,\n      \"shipmentsStarted\": 38,\n      \"trackingCredits\": 36,\n      \"refundedCredits\": 1,\n      \"vesselCredits\": 2,\n      \"aiCredits\": 1.235,\n      \"netCredits\": 38.235\n    },\n    {\n      \"customer\": {\n        \"id\": \"5a8e1f47-9c3d-4b26-8e71-0f4c2d9b6a13\",\n        \"ref\": \"C-2107\",\n        \"name\": \"Sample Foods Ltd.\",\n        \"countryCode\": \"TR\"\n      },\n      \"shipment\": null,\n      \"day\": null,\n      \"shipmentsStarted\": 19,\n      \"trackingCredits\": 18,\n      \"refundedCredits\": 1,\n      \"vesselCredits\": 2,\n      \"aiCredits\": 0.4625,\n      \"netCredits\": 19.4625\n    },\n    {\n      \"customer\": null,\n      \"shipment\": null,\n      \"day\": null,\n      \"shipmentsStarted\": 4,\n      \"trackingCredits\": 3,\n      \"refundedCredits\": 0,\n      \"vesselCredits\": 0,\n      \"aiCredits\": 0.115,\n      \"netCredits\": 3.115\n    }\n  ]\n}"
                },
                {
                  "status": 200,
                  "label": "format=csv",
                  "contentType": "text/csv",
                  "body": "date,type,credits,shipment_id,identifier,vessel_follow_id,conversation_id,customer_id,customer_ref,customer_name,user_email\n2026-10-02T13:20:07Z,TRACKING_CHARGE,1,6b1f0c9a-4d2e-4f7b-9a3c-8e5d21f0a4b7,TGHU8126501,,,c7d2a9e4-3f1b-4e8a-9b6c-1d5e7f3a2b90,C-1042,Acme Trading Ltd.,elif.yilmaz@forwarder.example\n2026-10-05T09:12:44Z,VESSEL,2,,NORDIC AURORA,7c1e4a9d-3b6f-4d28-9e05-a2f8c6b1d3e7,,c7d2a9e4-3f1b-4e8a-9b6c-1d5e7f3a2b90,C-1042,Acme Trading Ltd.,elif.yilmaz@forwarder.example\n2026-10-14T09:31:10Z,AI,0.2,,,,9d3f7a2e-1c8b-4e6d-b5a9-3f0e7c2d1b84,c7d2a9e4-3f1b-4e8a-9b6c-1d5e7f3a2b90,C-1042,Acme Trading Ltd.,elif.yilmaz@forwarder.example\n2026-10-18T11:02:51Z,TRACKING_CHARGE,1,5c2e8a1f-9b3d-4e72-a6c0-3d8f1b7e4a59,871-12345675,,,5a8e1f47-9c3d-4b26-8e71-0f4c2d9b6a13,C-2107,Sample Foods Ltd.,elif.yilmaz@forwarder.example\n2026-10-20T16:45:00Z,TRACKING_REFUND,-1,b5d13c88-9e2f-4a7b-8c41-6f0a3e9d72c5,176-12345675,,,5a8e1f47-9c3d-4b26-8e71-0f4c2d9b6a13,C-2107,Sample Foods Ltd.,elif.yilmaz@forwarder.example"
                }
              ],
              "errors": [
                {
                  "status": 400,
                  "message": "from must be before to",
                  "when": "`to` is on or before `from`."
                },
                {
                  "status": 400,
                  "message": "The report can cover at most 366 days",
                  "when": "A longer range."
                },
                {
                  "status": 400,
                  "message": "from must be a date like 2026-10-01",
                  "when": "Not a `YYYY-MM-DD` date."
                },
                {
                  "status": 400,
                  "message": "groupBy must be one of: customer, shipment, day, none",
                  "when": "Another `groupBy`."
                },
                {
                  "status": 400,
                  "message": "Unknown customer id",
                  "when": "`customerId` is not one of your customers (or not a UUID)."
                },
                {
                  "status": 400,
                  "message": "Unknown customer ref",
                  "when": "No customer has that `customerRef`."
                },
                {
                  "status": 400,
                  "message": "format must be json or csv",
                  "when": "Another `format`."
                },
                {
                  "status": 401,
                  "message": "Invalid or revoked API key",
                  "when": "The X-API-Key header is missing, wrong or revoked."
                },
                {
                  "status": 429,
                  "message": "Rate limit exceeded (60 requests/minute)",
                  "when": "Over the per-key budget; wait Retry-After seconds."
                }
              ],
              "notes": [
                "CSV (`navlo-usage-<from>_<to>.csv`, CRLF lines, no byte-order mark — the app’s Export CSV adds one for Excel): one line per ledger row with the header `date,type,credits,shipment_id,identifier,vessel_follow_id,conversation_id,customer_id,customer_ref,customer_name,user_email`. `date` is the row’s UTC timestamp; `type` is `TRACKING_CHARGE`, `TRACKING_REFUND`, `VESSEL` or `AI`; refund lines carry negative credits, so the column sums to `netCredits`; `identifier` is the shipment number, the vessel name on a `VESSEL` line, empty on `AI`; `user_email` is who spent the credits.",
                "Every charge and refund in your credit ledger is counted, so the totals reconcile with the Ledger page. Numbers carry no trailing zeros (`12`, `0.5`)."
              ]
            },
            {
              "kind": "heading",
              "id": "usage-rebilling",
              "title": "Re-billing your customers"
            },
            {
              "kind": "list",
              "ordered": true,
              "items": [
                "**Put a customer on everything that costs credits.** Send `customer` on [`POST /v1/shipments`](/developers/shipments#shipments-create), batch items, [vessel follows](/developers/vessels#vessels-follow) and [Navlo AI](/developers/navlo-ai#ai-ask) — by your own `ref`, so no lookup is needed. Fix older shipments with [`PATCH /v1/shipments/{id}`](/developers/shipments#shipments-update) or on the Companies page.",
                "**At month end, pull the report**: `GET /v1/usage?groupBy=customer&from=2026-10-01&to=2026-11-01`. One group per customer, plus a `customer: null` group for anything unassigned — assign those and run it again.",
                "**Turn credits into money** with your own price per credit: `netCredits × your rate`, plus whatever service fee you add. `shipmentsStarted` is there if you bill per shipment instead.",
                "**Attach the detail.** `format=csv&customerRef=C-1042` gives one line per charge, refund, vessel follow and AI answer for that customer — the invoice annex."
              ]
            },
            {
              "kind": "code",
              "title": "Invoice lines from the usage report",
              "samples": [
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "// Month-end: one invoice line per customer, priced at your own rate per credit.\nconst PRICE_PER_CREDIT_EUR = 2.5\n\nconst params = new URLSearchParams({ from: '2026-10-01', to: '2026-11-01', groupBy: 'customer' })\nconst res = await fetch(`https://api.navlo.io/v1/usage?${params}`, {\n  headers: { 'X-API-Key': process.env.NAVLO_API_KEY },\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\nconst usage = await res.json()\n\nfor (const g of usage.groups) {\n  if (!g.customer) {\n    console.warn(`${g.netCredits} credits have no customer — assign them before invoicing`)\n    continue\n  }\n  const amount = (g.netCredits * PRICE_PER_CREDIT_EUR).toFixed(2)\n  console.log(`${g.customer.ref}\\t${g.customer.name}\\t${g.shipmentsStarted} shipments\\t€${amount}`)\n}"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nPRICE_PER_CREDIT_EUR = 2.5  # your own rate\n\nr = requests.get(\n    \"https://api.navlo.io/v1/usage\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    params={\"from\": \"2026-10-01\", \"to\": \"2026-11-01\", \"groupBy\": \"customer\"},\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\n\nfor g in r.json()[\"groups\"]:\n    if g[\"customer\"] is None:\n        print(f\"WARNING: {g['netCredits']} credits have no customer — assign them before invoicing\")\n        continue\n    amount = round(g[\"netCredits\"] * PRICE_PER_CREDIT_EUR, 2)\n    print(f\"{g['customer']['ref']}\\t{g['customer']['name']}\\t{g['shipmentsStarted']} shipments\\t€{amount:.2f}\")"
                }
              ]
            },
            {
              "kind": "callout",
              "tone": "tip",
              "text": "The same report is in the app under [Ledger → By customer](https://app.navlo.io/ledger?view=customers), with the same numbers and an Export CSV button — handy for checking your invoice run."
            },
            {
              "kind": "code",
              "title": "One customer’s month",
              "samples": [
                {
                  "lang": "json",
                  "label": "Example group",
                  "code": "{\n  \"customer\": {\n    \"id\": \"c7d2a9e4-3f1b-4e8a-9b6c-1d5e7f3a2b90\",\n    \"ref\": \"C-1042\",\n    \"name\": \"Acme Trading Ltd.\",\n    \"countryCode\": \"TR\"\n  },\n  \"shipment\": null,\n  \"day\": null,\n  \"shipmentsStarted\": 38,\n  \"trackingCredits\": 36,\n  \"refundedCredits\": 1,\n  \"vesselCredits\": 2,\n  \"aiCredits\": 1.235,\n  \"netCredits\": 38.235\n}"
                }
              ]
            }
          ]
        }
      ]
    },
    {
      "id": "ai-group",
      "title": "Navlo AI",
      "pages": [
        {
          "id": "navlo-ai",
          "title": "Navlo AI",
          "summary": "Ask Navlo AI about your shipments over the API — answers stream as they are written, or come back as one JSON object.",
          "blocks": [
            {
              "kind": "prose",
              "text": "Navlo AI is the assistant from the app’s **Navlo AI** page, with the same knowledge of your shipments, the same tools and the same guardrails. Ask one-off questions with [`POST /v1/ai/ask`](#ai-ask), or hold a conversation with follow-ups. Conversations you start over the API appear in the key creator’s Navlo AI list in the app."
            },
            {
              "kind": "definitions",
              "items": [
                {
                  "term": "Streaming",
                  "description": "On by default: `text/event-stream`, the answer arrives as it is written. `\"stream\": false` returns one JSON object."
                },
                {
                  "term": "Rate limit",
                  "description": "10 requests a minute per key, separate from the general 60, and at most 2 answers running at once per organization ([Rate limits](/developers/rate-limits))."
                },
                {
                  "term": "Cost",
                  "description": "Answers use AI credits ([Credits](#ai-credits))."
                },
                {
                  "term": "Duration",
                  "description": "Usually 5–30 seconds; a stream stays open up to 5 minutes."
                }
              ]
            },
            {
              "kind": "endpoint",
              "id": "ai-ask",
              "method": "POST",
              "path": "/v1/ai/ask",
              "summary": "Ask a question",
              "description": [
                "Starts a new conversation, asks your question and answers it. Streams [events](#ai-events) by default; send `\"stream\": false` for a single JSON response."
              ],
              "auth": "apiKey",
              "rateLimit": "ai",
              "since": "2026-10-22",
              "pathParams": [],
              "queryParams": [],
              "headers": [],
              "body": {
                "contentType": "application/json",
                "fields": [
                  {
                    "name": "question",
                    "type": "string",
                    "required": true,
                    "description": "Your question, up to 10,000 characters, in any language Navlo AI speaks (answers come in the same language)."
                  },
                  {
                    "name": "shipmentId",
                    "type": "uuid",
                    "required": false,
                    "description": "Ask about one of your shipments; Navlo AI is told which one you mean."
                  },
                  {
                    "name": "customer",
                    "type": "object",
                    "required": false,
                    "description": "Attribute the AI credits to one of your customers: `{ \"ref\", \"name\" }` or `{ \"id\" }` ([resolution rules](/developers/shipments#shipments-customer-input))."
                  },
                  {
                    "name": "stream",
                    "type": "boolean",
                    "required": false,
                    "description": "`true`: server-sent events. `false`: one JSON object when the answer is complete.",
                    "defaultValue": "true"
                  }
                ]
              },
              "response": {
                "status": 200,
                "contentType": "text/event-stream",
                "description": "A stream of [events](#ai-events) ending with `result` or `error`. With `\"stream\": false`: `application/json`, the `result` object:",
                "fields": [
                  {
                    "name": "conversationId",
                    "type": "uuid",
                    "description": "The conversation — continue it with [`POST /v1/ai/conversations/{id}/messages`](#ai-messages-send)."
                  },
                  {
                    "name": "messageId",
                    "type": "uuid",
                    "description": "The id the answer is stored under in the conversation."
                  },
                  {
                    "name": "answer",
                    "type": "string",
                    "description": "The complete answer as Markdown, without chart blocks. Links into the app are absolute (`https://app.navlo.io/shipment/<id>`)."
                  },
                  {
                    "name": "shipments",
                    "type": "array<object>",
                    "description": "Your shipments the answer is about, `[{ id, identifier }]`, in order of first mention (the `shipmentId` you asked about first) — link them in your UI."
                  },
                  {
                    "name": "charts",
                    "type": "array<object>",
                    "description": "Charts in the answer — [format](#ai-charts)."
                  },
                  {
                    "name": "files",
                    "type": "array<object>",
                    "description": "Documents Navlo AI generated — [format](#ai-files)."
                  },
                  {
                    "name": "creditsUsed",
                    "type": "number",
                    "description": "AI credits actually deducted for this answer (up to 4 decimals)."
                  }
                ]
              },
              "requestExamples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl -N -X POST \"https://api.navlo.io/v1/ai/ask\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"question\": \"Where is MEDU1234562 and will it reach Ambarli on time?\",\n    \"customer\": { \"ref\": \"C-1042\" }\n  }'"
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const res = await fetch('https://api.navlo.io/v1/ai/ask', {\n  method: 'POST',\n  headers: {\n    'X-API-Key': process.env.NAVLO_API_KEY,\n    'Content-Type': 'application/json',\n    Accept: 'text/event-stream',\n  },\n  body: JSON.stringify({\n    question: 'Where is MEDU1234562 and will it reach Ambarli on time?',\n    customer: { ref: 'C-1042' },\n  }),\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\n\n// Server-sent events: frames separated by a blank line, each with \"event:\" and \"data:\" lines.\nconst decoder = new TextDecoder()\nlet buffer = ''\nlet result\nfor await (const chunk of res.body) {\n  buffer += decoder.decode(chunk, { stream: true })\n  let end\n  while ((end = buffer.indexOf('\\n\\n')) !== -1) {\n    const frame = buffer.slice(0, end)\n    buffer = buffer.slice(end + 2)\n    const event = frame.match(/^event:\\s?(.*)$/m)?.[1]\n    const data = JSON.parse(frame.match(/^data:\\s?(.*)$/m)?.[1] ?? '{}')\n    if (event === 'step') process.stdout.write(`\\n[${data.label}…]\\n`)\n    if (event === 'text') process.stdout.write(data.delta)\n    if (event === 'result') result = data\n    if (event === 'error') throw new Error(`${data.code}: ${data.message}`)\n  }\n}\nconsole.log('\\nCredits used:', result.creditsUsed)"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import json\nimport os\nimport requests\n\nr = requests.post(\n    \"https://api.navlo.io/v1/ai/ask\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"], \"Accept\": \"text/event-stream\"},\n    json={\"question\": \"Where is MEDU1234562 and will it reach Ambarli on time?\", \"customer\": {\"ref\": \"C-1042\"}},\n    stream=True,\n    timeout=(10, 300),\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\nr.encoding = \"utf-8\"\n\nevent, result = None, None\nfor line in r.iter_lines(decode_unicode=True):\n    if line.startswith(\"event:\"):\n        event = line[6:].strip()\n    elif line.startswith(\"data:\"):\n        data = json.loads(line[5:])\n        if event == \"step\":\n            print(f\"\\n[{data['label']}…]\")\n        elif event == \"text\":\n            print(data[\"delta\"], end=\"\", flush=True)\n        elif event == \"result\":\n            result = data\n        elif event == \"error\":\n            raise RuntimeError(f\"{data['code']}: {data['message']}\")\n\nprint(\"\\nCredits used:\", result[\"creditsUsed\"])"
                }
              ],
              "responseExamples": [
                {
                  "status": 200,
                  "label": "stream",
                  "contentType": "text/event-stream",
                  "body": "event:started\ndata:{\"conversationId\":\"9d3f7a2e-1c8b-4e6d-b5a9-3f0e7c2d1b84\",\"messageId\":\"3c8e1b7f-5a2d-4f96-a0c4-7e9b2d6f1a35\"}\n\nevent:text\ndata:{\"delta\":\"Let me check that container.\"}\n\nevent:step\ndata:{\"label\":\"Looking up shipment\"}\n\nevent:step\ndata:{\"label\":\"Assessing shipment risk\"}\n\nevent:text\ndata:{\"delta\":\"**MEDU1234562** is on the MSC MARTINA south of Crete, due at Piraeus tomorrow (23 Oct) for transshipment onto the MSC ARIANE.\"}\n\nevent:text\ndata:{\"delta\":\"\\n\\n- **ETA Ambarli:** 30 Oct 06:00 from MSC; Navlo predicts 31 Oct 02:00. The ETA has slipped 5 days since departure.\"}\n\nevent:text\ndata:{\"delta\":\"\\n- **Risk: medium.** Piraeus is congested (1.8 days at anchorage against a 0.6-day norm), so the 27 Oct feeder connection may slip.\"}\n\nevent:text\ndata:{\"delta\":\"\\n- **Free time:** 7 calendar days from arrival, ending 6 Nov.\"}\n\nevent:text\ndata:{\"delta\":\"\\n\\nPlan delivery to Acme Trading Ltd. for 31 Oct at the earliest.\"}\n\nevent:result\ndata:{\"conversationId\":\"9d3f7a2e-1c8b-4e6d-b5a9-3f0e7c2d1b84\",\"messageId\":\"7a2f9c4e-1d6b-4b83-9e5a-0c7d3f8b2e61\",\"answer\":\"**MEDU1234562** is on the MSC MARTINA south of Crete, due at Piraeus tomorrow (23 Oct) for transshipment onto the MSC ARIANE.\\n\\n- **ETA Ambarli:** 30 Oct 06:00 from MSC; Navlo predicts 31 Oct 02:00. The ETA has slipped 5 days since departure.\\n- **Risk: medium.** Piraeus is congested (1.8 days at anchorage against a 0.6-day norm), so the 27 Oct feeder connection may slip.\\n- **Free time:** 7 calendar days from arrival, ending 6 Nov.\\n\\nPlan delivery to Acme Trading Ltd. for 31 Oct at the earliest.\",\"shipments\":[{\"id\":\"8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07\",\"identifier\":\"MEDU1234562\"}],\"charts\":[],\"files\":[],\"creditsUsed\":0.2}\n"
                },
                {
                  "status": 200,
                  "label": "\"stream\": false",
                  "contentType": "application/json",
                  "body": "{\n  \"conversationId\": \"9d3f7a2e-1c8b-4e6d-b5a9-3f0e7c2d1b84\",\n  \"messageId\": \"7a2f9c4e-1d6b-4b83-9e5a-0c7d3f8b2e61\",\n  \"answer\": \"**MEDU1234562** is on the MSC MARTINA south of Crete, due at Piraeus tomorrow (23 Oct) for transshipment onto the MSC ARIANE.\\n\\n- **ETA Ambarli:** 30 Oct 06:00 from MSC; Navlo predicts 31 Oct 02:00. The ETA has slipped 5 days since departure.\\n- **Risk: medium.** Piraeus is congested (1.8 days at anchorage against a 0.6-day norm), so the 27 Oct feeder connection may slip.\\n- **Free time:** 7 calendar days from arrival, ending 6 Nov.\\n\\nPlan delivery to Acme Trading Ltd. for 31 Oct at the earliest.\",\n  \"shipments\": [\n    {\n      \"id\": \"8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07\",\n      \"identifier\": \"MEDU1234562\"\n    }\n  ],\n  \"charts\": [],\n  \"files\": [],\n  \"creditsUsed\": 0.2\n}"
                }
              ],
              "errors": [
                {
                  "status": 400,
                  "message": "question: must not be blank",
                  "when": "Empty question."
                },
                {
                  "status": 400,
                  "message": "question: size must be between 0 and 10000",
                  "when": "Longer than 10,000 characters."
                },
                {
                  "status": 402,
                  "message": "You're out of AI credits. Navlo AI is billed in AI credits — Tracking credits can't pay for a chat turn — so transfer some across (they move 1:1) or top up to keep chatting. Shipments you already track keep updating either way.",
                  "when": "No AI credits left — refused before anything is stored. Streams send one `error` event instead."
                },
                {
                  "status": 422,
                  "message": "I'm specialized in logistics and shipping. Try asking me about: …",
                  "when": "JSON mode: not a logistics question. `code: rejected`."
                },
                {
                  "status": 429,
                  "message": "Navlo AI is already answering 2 questions for your organization. Send the next one when one of them finishes.",
                  "when": "Two answers are still running for your organization — streams too, before anything starts. Nothing is stored."
                },
                {
                  "status": 503,
                  "message": "The AI service is busy right now. Please try again in a minute.",
                  "when": "JSON mode: high load. `code: busy` — retry with backoff."
                },
                {
                  "status": 504,
                  "message": "Navlo AI did not finish within 5 minutes. If the answer arrives later, it is stored on the conversation.",
                  "when": "JSON mode: the 5-minute ceiling. `code: timeout`."
                },
                {
                  "status": 500,
                  "message": "Navlo AI could not finish this answer. Please try again.",
                  "when": "JSON mode: anything else. `code: internal`."
                },
                {
                  "status": 400,
                  "message": "Unknown customer id",
                  "when": "`customer.id` is not one of your customers."
                },
                {
                  "status": 404,
                  "message": "Shipment not found",
                  "when": "`shipmentId` is not one of your shipments."
                },
                {
                  "status": 400,
                  "message": "Request body is missing or is not valid JSON",
                  "when": "The body could not be parsed."
                },
                {
                  "status": 401,
                  "message": "Invalid or revoked API key",
                  "when": "The X-API-Key header is missing, wrong or revoked."
                },
                {
                  "status": 429,
                  "message": "Rate limit exceeded (10 requests/minute)",
                  "when": "Over the Navlo AI budget; wait Retry-After seconds."
                }
              ],
              "notes": []
            },
            {
              "kind": "code",
              "title": "JSON mode (\"stream\": false)",
              "samples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl -X POST \"https://api.navlo.io/v1/ai/ask\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"question\": \"Where is MEDU1234562 and will it reach Ambarli on time?\",\n    \"shipmentId\": \"8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07\",\n    \"stream\": false\n  }'"
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const res = await fetch('https://api.navlo.io/v1/ai/ask', {\n  method: 'POST',\n  headers: {\n    'X-API-Key': process.env.NAVLO_API_KEY,\n    'Content-Type': 'application/json',\n  },\n  body: JSON.stringify({\n    question: 'Where is MEDU1234562 and will it reach Ambarli on time?',\n    shipmentId: '8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07',\n    stream: false,\n  }),\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\nconst result = await res.json()"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.post(\n    \"https://api.navlo.io/v1/ai/ask\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    json={\n        \"question\": \"Where is MEDU1234562 and will it reach Ambarli on time?\",\n        \"shipmentId\": \"8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07\",\n        \"stream\": False,\n    },\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\nresult = r.json()"
                }
              ]
            },
            {
              "kind": "callout",
              "tone": "tip",
              "text": "JSON mode holds the request open until the answer is complete — give your HTTP client a timeout of at least 300 seconds. Streaming shows progress and suits user-facing screens; JSON mode suits scripts and back-office jobs. Either way an answer that has started runs to the end — even if you disconnect or the 5-minute ceiling passes — and is stored on the conversation and charged."
            },
            {
              "kind": "heading",
              "id": "ai-events",
              "title": "Stream events"
            },
            {
              "kind": "prose",
              "text": "A stream is standard [server-sent events](https://html.spec.whatwg.org/multipage/server-sent-events.html): frames separated by a blank line, each with an `event:` line and a one-line JSON `data:` line. Accept `data:` with or without a space after the colon. The stream always ends after `result` or `error` — and when you have no AI credits, it is a single `error` event."
            },
            {
              "kind": "definitions",
              "items": [
                {
                  "term": "`started`",
                  "description": "First, once the question is accepted — `{ conversationId, messageId }`."
                },
                {
                  "term": "`step`",
                  "description": "Navlo AI starts a lookup — `{ label }`, the text the app shows."
                },
                {
                  "term": "`text`",
                  "description": "The next piece of the answer, in order — `{ delta }`."
                },
                {
                  "term": "`result`",
                  "description": "Last, on success — the [result object](#ai-ask)."
                },
                {
                  "term": "`error`",
                  "description": "Last, on failure — `{ message, code }`."
                }
              ]
            },
            {
              "kind": "fields",
              "title": "Event data",
              "fields": [
                {
                  "name": "started.conversationId",
                  "type": "uuid",
                  "description": "The new (or continued) conversation."
                },
                {
                  "name": "started.messageId",
                  "type": "uuid",
                  "description": "The id your question is stored under. The answer’s id arrives in `result.messageId`."
                },
                {
                  "name": "step.label",
                  "type": "string",
                  "description": "Human label, e.g. \"Looking up shipment\". Show it as progress; don’t branch on its wording."
                },
                {
                  "name": "text.delta",
                  "type": "string",
                  "description": "Answer text to append, raw Markdown as written: chart blocks included and app links root-relative (`/shipment/<id>`) — `result.answer` separates the charts and makes the links absolute. Render the accumulated text, not each delta alone."
                },
                {
                  "name": "error.message",
                  "type": "string",
                  "description": "What went wrong, readable as is."
                },
                {
                  "name": "error.code",
                  "type": "enum",
                  "description": "`insufficient_credits` — top up AI credits. `rejected` — not a logistics question. `busy` — retry in a minute. `timeout` — no answer within 5 minutes; it may still land on the conversation. `internal` — retry; contact support if it persists.",
                  "values": [
                    "insufficient_credits",
                    "rejected",
                    "busy",
                    "timeout",
                    "internal"
                  ]
                }
              ]
            },
            {
              "kind": "callout",
              "tone": "info",
              "text": "Navlo AI sometimes writes a sentence before looking something up. When a `step` arrives, clear the text you have shown so far — the answer that follows replaces it. `result.answer` is always the complete, final answer."
            },
            {
              "kind": "code",
              "title": "A complete stream",
              "samples": [
                {
                  "lang": "sse",
                  "label": "text/event-stream",
                  "code": "event:started\ndata:{\"conversationId\":\"9d3f7a2e-1c8b-4e6d-b5a9-3f0e7c2d1b84\",\"messageId\":\"3c8e1b7f-5a2d-4f96-a0c4-7e9b2d6f1a35\"}\n\nevent:text\ndata:{\"delta\":\"Let me check that container.\"}\n\nevent:step\ndata:{\"label\":\"Looking up shipment\"}\n\nevent:step\ndata:{\"label\":\"Assessing shipment risk\"}\n\nevent:text\ndata:{\"delta\":\"**MEDU1234562** is on the MSC MARTINA south of Crete, due at Piraeus tomorrow (23 Oct) for transshipment onto the MSC ARIANE.\"}\n\nevent:text\ndata:{\"delta\":\"\\n\\n- **ETA Ambarli:** 30 Oct 06:00 from MSC; Navlo predicts 31 Oct 02:00. The ETA has slipped 5 days since departure.\"}\n\nevent:text\ndata:{\"delta\":\"\\n- **Risk: medium.** Piraeus is congested (1.8 days at anchorage against a 0.6-day norm), so the 27 Oct feeder connection may slip.\"}\n\nevent:text\ndata:{\"delta\":\"\\n- **Free time:** 7 calendar days from arrival, ending 6 Nov.\"}\n\nevent:text\ndata:{\"delta\":\"\\n\\nPlan delivery to Acme Trading Ltd. for 31 Oct at the earliest.\"}\n\nevent:result\ndata:{\"conversationId\":\"9d3f7a2e-1c8b-4e6d-b5a9-3f0e7c2d1b84\",\"messageId\":\"7a2f9c4e-1d6b-4b83-9e5a-0c7d3f8b2e61\",\"answer\":\"**MEDU1234562** is on the MSC MARTINA south of Crete, due at Piraeus tomorrow (23 Oct) for transshipment onto the MSC ARIANE.\\n\\n- **ETA Ambarli:** 30 Oct 06:00 from MSC; Navlo predicts 31 Oct 02:00. The ETA has slipped 5 days since departure.\\n- **Risk: medium.** Piraeus is congested (1.8 days at anchorage against a 0.6-day norm), so the 27 Oct feeder connection may slip.\\n- **Free time:** 7 calendar days from arrival, ending 6 Nov.\\n\\nPlan delivery to Acme Trading Ltd. for 31 Oct at the earliest.\",\"shipments\":[{\"id\":\"8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07\",\"identifier\":\"MEDU1234562\"}],\"charts\":[],\"files\":[],\"creditsUsed\":0.2}\n"
                }
              ]
            },
            {
              "kind": "heading",
              "id": "ai-charts",
              "title": "Charts"
            },
            {
              "kind": "prose",
              "text": "When a question calls for a chart (“shipments by carrier this month”), the answer’s chart blocks are taken out of `answer` and returned in `charts`. Render them with your chart library, or ignore them — the text stands on its own."
            },
            {
              "kind": "code",
              "samples": [
                {
                  "lang": "json",
                  "label": "Chart",
                  "code": "{\n  \"type\": \"bar\",\n  \"title\": \"Shipments by status\",\n  \"xLabel\": \"Status\",\n  \"yLabel\": \"Shipments\",\n  \"data\": [\n    {\n      \"label\": \"In transit\",\n      \"value\": 23\n    },\n    {\n      \"label\": \"At destination\",\n      \"value\": 9\n    },\n    {\n      \"label\": \"Discovering\",\n      \"value\": 2\n    }\n  ]\n}"
                }
              ]
            },
            {
              "kind": "fields",
              "title": "Chart fields",
              "fields": [
                {
                  "name": "type",
                  "type": "enum",
                  "description": "Chart kind.",
                  "values": [
                    "bar",
                    "line",
                    "pie"
                  ]
                },
                {
                  "name": "title",
                  "type": "string",
                  "nullable": true,
                  "description": "Chart title."
                },
                {
                  "name": "xLabel",
                  "type": "string",
                  "nullable": true,
                  "description": "X-axis label (bar charts)."
                },
                {
                  "name": "yLabel",
                  "type": "string",
                  "nullable": true,
                  "description": "Y-axis label (bar charts)."
                },
                {
                  "name": "data",
                  "type": "array<object>",
                  "description": "One point per item: `label` (string) and `value` (number)."
                }
              ]
            },
            {
              "kind": "heading",
              "id": "ai-files",
              "title": "Generated files"
            },
            {
              "kind": "prose",
              "text": "Ask for a report or a trade document and Navlo AI generates it: Excel status, cost and D&D risk reports, and PDF commercial invoices, proforma invoices, packing lists and shipper’s letters of instruction. Each file is listed in `files`."
            },
            {
              "kind": "code",
              "title": "A result with a file and a chart",
              "samples": [
                {
                  "lang": "json",
                  "label": "\"stream\": false",
                  "code": "{\n  \"conversationId\": \"9d3f7a2e-1c8b-4e6d-b5a9-3f0e7c2d1b84\",\n  \"messageId\": \"5e8b2d4f-7a1c-4e39-b6d0-2f9c4a7e1b53\",\n  \"answer\": \"Here is the status report for Acme Trading Ltd.’s 34 active shipments. 23 are in transit, 9 have arrived and 2 are still being discovered; 3 have an ETA that moved this week.\",\n  \"shipments\": [],\n  \"charts\": [\n    {\n      \"type\": \"bar\",\n      \"title\": \"Shipments by status\",\n      \"xLabel\": \"Status\",\n      \"yLabel\": \"Shipments\",\n      \"data\": [\n        {\n          \"label\": \"In transit\",\n          \"value\": 23\n        },\n        {\n          \"label\": \"At destination\",\n          \"value\": 9\n        },\n        {\n          \"label\": \"Discovering\",\n          \"value\": 2\n        }\n      ]\n    }\n  ],\n  \"files\": [\n    {\n      \"name\": \"shipment-status-report-20261022.xlsx\",\n      \"url\": \"https://api.navlo.io/api/ai/d/AbC123.xYz789\",\n      \"expiresAt\": \"2026-10-29T09:12:41.402Z\"\n    }\n  ],\n  \"creditsUsed\": 1\n}"
                }
              ]
            },
            {
              "kind": "fields",
              "title": "File fields",
              "fields": [
                {
                  "name": "name",
                  "type": "string",
                  "description": "File name, e.g. `shipment-status-report-20261022.xlsx`."
                },
                {
                  "name": "url",
                  "type": "string",
                  "description": "Download link. A plain GET — no API key — redirects to the file. Anyone with the link can download it, so keep it private."
                },
                {
                  "name": "expiresAt",
                  "type": "timestamp",
                  "nullable": true,
                  "description": "When the link stops working (UTC) — 7 days after generation."
                }
              ]
            },
            {
              "kind": "prose",
              "text": "Need a report without asking? [`POST /v1/reports`](/developers/reports-and-export#reports-create) builds the same Excel reports directly, without AI credits."
            },
            {
              "kind": "heading",
              "id": "ai-credits",
              "title": "Credits"
            },
            {
              "kind": "list",
              "ordered": false,
              "items": [
                "Answers cost **AI credits** — a balance separate from tracking credits ([`GET /v1/credits`](/developers/usage-and-credits#usage-credits)). Admins can move credits between the two in the app, 1:1.",
                "`creditsUsed` on each result says what that answer used.",
                "With `customer`, the credits are attributed to that customer in the [usage report](/developers/usage-and-credits#usage-report).",
                "Out of AI credits: the question is refused before anything is stored — JSON mode answers `402`, a stream is one `error` event with code `insufficient_credits`."
              ]
            },
            {
              "kind": "heading",
              "id": "ai-conversations",
              "title": "Conversations"
            },
            {
              "kind": "prose",
              "text": "For follow-up questions (“and the other Acme Trading shipments?”), keep the conversation: every message sees what was said before. `ask` is simply a new conversation with one message."
            },
            {
              "kind": "endpoint",
              "id": "ai-conversations-create",
              "method": "POST",
              "path": "/v1/ai/conversations",
              "summary": "Start a conversation",
              "description": [
                "The body is optional."
              ],
              "auth": "apiKey",
              "rateLimit": "ai",
              "since": "2026-10-22",
              "pathParams": [],
              "queryParams": [],
              "headers": [],
              "body": {
                "contentType": "application/json",
                "fields": [
                  {
                    "name": "title",
                    "type": "string",
                    "required": false,
                    "description": "A title; otherwise Navlo AI names it from the first exchange."
                  },
                  {
                    "name": "customer",
                    "type": "object",
                    "required": false,
                    "description": "Attribute the AI credits to one of your customers: `{ \"ref\", \"name\" }` or `{ \"id\" }` ([resolution rules](/developers/shipments#shipments-customer-input))."
                  }
                ]
              },
              "response": {
                "status": 201,
                "contentType": "application/json",
                "fields": [
                  {
                    "name": "id",
                    "type": "uuid",
                    "description": "Conversation id."
                  },
                  {
                    "name": "title",
                    "type": "string",
                    "description": "Title — Navlo AI names it from the first exchange unless you give one."
                  },
                  {
                    "name": "customer",
                    "type": "object",
                    "nullable": true,
                    "description": "The customer its credits are attributed to: `{ id, ref, name, countryCode }`."
                  },
                  {
                    "name": "createdAt",
                    "type": "timestamp",
                    "description": "Started (UTC)."
                  },
                  {
                    "name": "updatedAt",
                    "type": "timestamp",
                    "description": "Last activity (UTC)."
                  }
                ]
              },
              "requestExamples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl -X POST \"https://api.navlo.io/v1/ai/conversations\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"title\": \"Acme October shipments\",\n    \"customer\": {\n      \"ref\": \"C-1042\"\n    }\n  }'"
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const res = await fetch('https://api.navlo.io/v1/ai/conversations', {\n  method: 'POST',\n  headers: {\n    'X-API-Key': process.env.NAVLO_API_KEY,\n    'Content-Type': 'application/json',\n  },\n  body: JSON.stringify({ title: 'Acme October shipments', customer: { ref: 'C-1042' } }),\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\nconst conversation = await res.json()"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.post(\n    \"https://api.navlo.io/v1/ai/conversations\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    json={\n        \"title\": \"Acme October shipments\",\n        \"customer\": {\"ref\": \"C-1042\"},\n    },\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\nconversation = r.json()"
                }
              ],
              "responseExamples": [
                {
                  "status": 201,
                  "contentType": "application/json",
                  "body": "{\n  \"id\": \"9d3f7a2e-1c8b-4e6d-b5a9-3f0e7c2d1b84\",\n  \"title\": \"Acme October shipments\",\n  \"customer\": {\n    \"id\": \"c7d2a9e4-3f1b-4e8a-9b6c-1d5e7f3a2b90\",\n    \"ref\": \"C-1042\",\n    \"name\": \"Acme Trading Ltd.\",\n    \"countryCode\": \"TR\"\n  },\n  \"createdAt\": \"2026-10-22T09:10:03Z\",\n  \"updatedAt\": \"2026-10-22T09:10:03Z\"\n}"
                }
              ],
              "errors": [
                {
                  "status": 400,
                  "message": "Unknown customer id",
                  "when": "`customer.id` is not one of your customers."
                },
                {
                  "status": 400,
                  "message": "Request body is missing or is not valid JSON",
                  "when": "The body could not be parsed."
                },
                {
                  "status": 401,
                  "message": "Invalid or revoked API key",
                  "when": "The X-API-Key header is missing, wrong or revoked."
                },
                {
                  "status": 429,
                  "message": "Rate limit exceeded (10 requests/minute)",
                  "when": "Over the Navlo AI budget; wait Retry-After seconds."
                }
              ],
              "notes": []
            },
            {
              "kind": "endpoint",
              "id": "ai-messages-send",
              "method": "POST",
              "path": "/v1/ai/conversations/{id}/messages",
              "summary": "Send a message",
              "description": [
                "Asks the next question in a conversation. Streams exactly like [`ask`](#ai-ask); `\"stream\": false` returns the result object."
              ],
              "auth": "apiKey",
              "rateLimit": "ai",
              "since": "2026-10-22",
              "pathParams": [
                {
                  "name": "id",
                  "type": "uuid",
                  "required": true,
                  "description": "The conversation id."
                }
              ],
              "queryParams": [],
              "headers": [],
              "body": {
                "contentType": "application/json",
                "fields": [
                  {
                    "name": "content",
                    "type": "string",
                    "required": true,
                    "description": "The question, up to 10,000 characters."
                  },
                  {
                    "name": "stream",
                    "type": "boolean",
                    "required": false,
                    "description": "Server-sent events, or one JSON object.",
                    "defaultValue": "true"
                  }
                ]
              },
              "response": {
                "status": 200,
                "contentType": "text/event-stream",
                "description": "Events, or with `\"stream\": false` the result object.",
                "fields": [
                  {
                    "name": "conversationId",
                    "type": "uuid",
                    "description": "The conversation — continue it with [`POST /v1/ai/conversations/{id}/messages`](#ai-messages-send)."
                  },
                  {
                    "name": "messageId",
                    "type": "uuid",
                    "description": "The id the answer is stored under in the conversation."
                  },
                  {
                    "name": "answer",
                    "type": "string",
                    "description": "The complete answer as Markdown, without chart blocks. Links into the app are absolute (`https://app.navlo.io/shipment/<id>`)."
                  },
                  {
                    "name": "shipments",
                    "type": "array<object>",
                    "description": "Your shipments the answer is about, `[{ id, identifier }]`, in order of first mention (the `shipmentId` you asked about first) — link them in your UI."
                  },
                  {
                    "name": "charts",
                    "type": "array<object>",
                    "description": "Charts in the answer — [format](#ai-charts)."
                  },
                  {
                    "name": "files",
                    "type": "array<object>",
                    "description": "Documents Navlo AI generated — [format](#ai-files)."
                  },
                  {
                    "name": "creditsUsed",
                    "type": "number",
                    "description": "AI credits actually deducted for this answer (up to 4 decimals)."
                  }
                ]
              },
              "requestExamples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl -X POST \"https://api.navlo.io/v1/ai/conversations/9d3f7a2e-1c8b-4e6d-b5a9-3f0e7c2d1b84/messages\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"content\": \"Make an Excel status report of all active Acme Trading shipments.\",\n    \"stream\": false\n  }'"
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const res = await fetch('https://api.navlo.io/v1/ai/conversations/9d3f7a2e-1c8b-4e6d-b5a9-3f0e7c2d1b84/messages', {\n  method: 'POST',\n  headers: {\n    'X-API-Key': process.env.NAVLO_API_KEY,\n    'Content-Type': 'application/json',\n  },\n  body: JSON.stringify({\n    content: 'Make an Excel status report of all active Acme Trading shipments.',\n    stream: false,\n  }),\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\nconst result = await res.json()"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.post(\n    \"https://api.navlo.io/v1/ai/conversations/9d3f7a2e-1c8b-4e6d-b5a9-3f0e7c2d1b84/messages\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    json={\n        \"content\": \"Make an Excel status report of all active Acme Trading shipments.\",\n        \"stream\": False,\n    },\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\nresult = r.json()"
                }
              ],
              "responseExamples": [
                {
                  "status": 200,
                  "label": "\"stream\": false",
                  "contentType": "application/json",
                  "body": "{\n  \"conversationId\": \"9d3f7a2e-1c8b-4e6d-b5a9-3f0e7c2d1b84\",\n  \"messageId\": \"5e8b2d4f-7a1c-4e39-b6d0-2f9c4a7e1b53\",\n  \"answer\": \"Here is the status report for Acme Trading Ltd.’s 34 active shipments. 23 are in transit, 9 have arrived and 2 are still being discovered; 3 have an ETA that moved this week.\",\n  \"shipments\": [],\n  \"charts\": [\n    {\n      \"type\": \"bar\",\n      \"title\": \"Shipments by status\",\n      \"xLabel\": \"Status\",\n      \"yLabel\": \"Shipments\",\n      \"data\": [\n        {\n          \"label\": \"In transit\",\n          \"value\": 23\n        },\n        {\n          \"label\": \"At destination\",\n          \"value\": 9\n        },\n        {\n          \"label\": \"Discovering\",\n          \"value\": 2\n        }\n      ]\n    }\n  ],\n  \"files\": [\n    {\n      \"name\": \"shipment-status-report-20261022.xlsx\",\n      \"url\": \"https://api.navlo.io/api/ai/d/AbC123.xYz789\",\n      \"expiresAt\": \"2026-10-29T09:12:41.402Z\"\n    }\n  ],\n  \"creditsUsed\": 1\n}"
                }
              ],
              "errors": [
                {
                  "status": 404,
                  "message": "Conversation not found",
                  "when": "Unknown id, or not a conversation of the key’s creator."
                },
                {
                  "status": 400,
                  "message": "question: must not be blank",
                  "when": "Empty question."
                },
                {
                  "status": 400,
                  "message": "question: size must be between 0 and 10000",
                  "when": "Longer than 10,000 characters."
                },
                {
                  "status": 402,
                  "message": "You're out of AI credits. Navlo AI is billed in AI credits — Tracking credits can't pay for a chat turn — so transfer some across (they move 1:1) or top up to keep chatting. Shipments you already track keep updating either way.",
                  "when": "No AI credits left — refused before anything is stored. Streams send one `error` event instead."
                },
                {
                  "status": 422,
                  "message": "I'm specialized in logistics and shipping. Try asking me about: …",
                  "when": "JSON mode: not a logistics question. `code: rejected`."
                },
                {
                  "status": 429,
                  "message": "Navlo AI is already answering 2 questions for your organization. Send the next one when one of them finishes.",
                  "when": "Two answers are still running for your organization — streams too, before anything starts. Nothing is stored."
                },
                {
                  "status": 503,
                  "message": "The AI service is busy right now. Please try again in a minute.",
                  "when": "JSON mode: high load. `code: busy` — retry with backoff."
                },
                {
                  "status": 504,
                  "message": "Navlo AI did not finish within 5 minutes. If the answer arrives later, it is stored on the conversation.",
                  "when": "JSON mode: the 5-minute ceiling. `code: timeout`."
                },
                {
                  "status": 500,
                  "message": "Navlo AI could not finish this answer. Please try again.",
                  "when": "JSON mode: anything else. `code: internal`."
                },
                {
                  "status": 401,
                  "message": "Invalid or revoked API key",
                  "when": "The X-API-Key header is missing, wrong or revoked."
                },
                {
                  "status": 429,
                  "message": "Rate limit exceeded (10 requests/minute)",
                  "when": "Over the Navlo AI budget; wait Retry-After seconds."
                }
              ],
              "notes": []
            },
            {
              "kind": "endpoint",
              "id": "ai-conversations-list",
              "method": "GET",
              "path": "/v1/ai/conversations",
              "summary": "List conversations",
              "description": [
                "The key creator’s conversations — including the ones they started in the app, archived ones too — most recently active first."
              ],
              "auth": "apiKey",
              "rateLimit": "ai",
              "since": "2026-10-22",
              "pathParams": [],
              "queryParams": [
                {
                  "name": "page",
                  "type": "integer",
                  "required": false,
                  "description": "Zero-based page index.",
                  "defaultValue": "0"
                },
                {
                  "name": "size",
                  "type": "integer",
                  "required": false,
                  "description": "Page size, 1–100.",
                  "defaultValue": "20"
                }
              ],
              "headers": [],
              "response": {
                "status": 200,
                "contentType": "application/json",
                "fields": [
                  {
                    "name": "page",
                    "type": "integer",
                    "description": "Page index."
                  },
                  {
                    "name": "size",
                    "type": "integer",
                    "description": "Page size."
                  },
                  {
                    "name": "totalElements",
                    "type": "integer",
                    "description": "Conversations."
                  },
                  {
                    "name": "totalPages",
                    "type": "integer",
                    "description": "Pages at this size."
                  },
                  {
                    "name": "conversations",
                    "type": "array<object>",
                    "description": "Each: `id`, `title`, `customer`, `createdAt`, `updatedAt`."
                  }
                ]
              },
              "requestExamples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl \"https://api.navlo.io/v1/ai/conversations\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\""
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const res = await fetch('https://api.navlo.io/v1/ai/conversations', {\n  headers: { 'X-API-Key': process.env.NAVLO_API_KEY },\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\nconst page = await res.json()"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.get(\n    \"https://api.navlo.io/v1/ai/conversations\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\npage = r.json()"
                }
              ],
              "responseExamples": [
                {
                  "status": 200,
                  "contentType": "application/json",
                  "body": "{\n  \"page\": 0,\n  \"size\": 20,\n  \"totalElements\": 1,\n  \"totalPages\": 1,\n  \"conversations\": [\n    {\n      \"id\": \"9d3f7a2e-1c8b-4e6d-b5a9-3f0e7c2d1b84\",\n      \"title\": \"Acme October shipments\",\n      \"customer\": {\n        \"id\": \"c7d2a9e4-3f1b-4e8a-9b6c-1d5e7f3a2b90\",\n        \"ref\": \"C-1042\",\n        \"name\": \"Acme Trading Ltd.\",\n        \"countryCode\": \"TR\"\n      },\n      \"createdAt\": \"2026-10-22T09:10:03Z\",\n      \"updatedAt\": \"2026-10-22T09:12:41Z\"\n    }\n  ]\n}"
                }
              ],
              "errors": [
                {
                  "status": 401,
                  "message": "Invalid or revoked API key",
                  "when": "The X-API-Key header is missing, wrong or revoked."
                },
                {
                  "status": 429,
                  "message": "Rate limit exceeded (10 requests/minute)",
                  "when": "Over the Navlo AI budget; wait Retry-After seconds."
                }
              ],
              "notes": []
            },
            {
              "kind": "endpoint",
              "id": "ai-conversations-get",
              "method": "GET",
              "path": "/v1/ai/conversations/{id}",
              "summary": "Retrieve a conversation",
              "description": [
                "The conversation with every message, oldest first."
              ],
              "auth": "apiKey",
              "rateLimit": "ai",
              "since": "2026-10-22",
              "pathParams": [
                {
                  "name": "id",
                  "type": "uuid",
                  "required": true,
                  "description": "The conversation id."
                }
              ],
              "queryParams": [],
              "headers": [],
              "response": {
                "status": 200,
                "contentType": "application/json",
                "fields": [
                  {
                    "name": "id",
                    "type": "uuid",
                    "description": "Conversation id."
                  },
                  {
                    "name": "title",
                    "type": "string",
                    "description": "Title — Navlo AI names it from the first exchange unless you give one."
                  },
                  {
                    "name": "customer",
                    "type": "object",
                    "nullable": true,
                    "description": "The customer its credits are attributed to: `{ id, ref, name, countryCode }`."
                  },
                  {
                    "name": "createdAt",
                    "type": "timestamp",
                    "description": "Started (UTC)."
                  },
                  {
                    "name": "updatedAt",
                    "type": "timestamp",
                    "description": "Last activity (UTC)."
                  },
                  {
                    "name": "messages",
                    "type": "array<object>",
                    "description": "The messages, oldest first."
                  },
                  {
                    "name": "messages[].id",
                    "type": "uuid",
                    "description": "Message id."
                  },
                  {
                    "name": "messages[].role",
                    "type": "enum",
                    "description": "Who wrote it.",
                    "values": [
                      "user",
                      "assistant"
                    ]
                  },
                  {
                    "name": "messages[].content",
                    "type": "string",
                    "description": "The text (Markdown for assistant messages, without chart blocks)."
                  },
                  {
                    "name": "messages[].files",
                    "type": "array<object>",
                    "description": "Files generated in that answer — [format](#ai-files)."
                  },
                  {
                    "name": "messages[].charts",
                    "type": "array<object>",
                    "description": "Charts in that answer — [format](#ai-charts)."
                  },
                  {
                    "name": "messages[].createdAt",
                    "type": "timestamp",
                    "description": "Sent (UTC)."
                  }
                ]
              },
              "requestExamples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl \"https://api.navlo.io/v1/ai/conversations/9d3f7a2e-1c8b-4e6d-b5a9-3f0e7c2d1b84\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\""
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const res = await fetch('https://api.navlo.io/v1/ai/conversations/9d3f7a2e-1c8b-4e6d-b5a9-3f0e7c2d1b84', {\n  headers: { 'X-API-Key': process.env.NAVLO_API_KEY },\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\nconst conversation = await res.json()"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.get(\n    \"https://api.navlo.io/v1/ai/conversations/9d3f7a2e-1c8b-4e6d-b5a9-3f0e7c2d1b84\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\nconversation = r.json()"
                }
              ],
              "responseExamples": [
                {
                  "status": 200,
                  "contentType": "application/json",
                  "body": "{\n  \"id\": \"9d3f7a2e-1c8b-4e6d-b5a9-3f0e7c2d1b84\",\n  \"title\": \"Acme October shipments\",\n  \"customer\": {\n    \"id\": \"c7d2a9e4-3f1b-4e8a-9b6c-1d5e7f3a2b90\",\n    \"ref\": \"C-1042\",\n    \"name\": \"Acme Trading Ltd.\",\n    \"countryCode\": \"TR\"\n  },\n  \"createdAt\": \"2026-10-22T09:10:03Z\",\n  \"updatedAt\": \"2026-10-22T09:10:19Z\",\n  \"messages\": [\n    {\n      \"id\": \"3c8e1b7f-5a2d-4f96-a0c4-7e9b2d6f1a35\",\n      \"role\": \"user\",\n      \"content\": \"Where is MEDU1234562 and will it reach Ambarli on time?\",\n      \"files\": [],\n      \"charts\": [],\n      \"createdAt\": \"2026-10-22T09:10:03Z\"\n    },\n    {\n      \"id\": \"7a2f9c4e-1d6b-4b83-9e5a-0c7d3f8b2e61\",\n      \"role\": \"assistant\",\n      \"content\": \"**MEDU1234562** is on the MSC MARTINA south of Crete, due at Piraeus tomorrow (23 Oct) for transshipment onto the MSC ARIANE.\\n\\n- **ETA Ambarli:** 30 Oct 06:00 from MSC; Navlo predicts 31 Oct 02:00. The ETA has slipped 5 days since departure.\\n- **Risk: medium.** Piraeus is congested (1.8 days at anchorage against a 0.6-day norm), so the 27 Oct feeder connection may slip.\\n- **Free time:** 7 calendar days from arrival, ending 6 Nov.\\n\\nPlan delivery to Acme Trading Ltd. for 31 Oct at the earliest.\",\n      \"files\": [],\n      \"charts\": [],\n      \"createdAt\": \"2026-10-22T09:10:19Z\"\n    }\n  ]\n}"
                }
              ],
              "errors": [
                {
                  "status": 404,
                  "message": "Conversation not found",
                  "when": "Unknown id, or not a conversation of the key’s creator."
                },
                {
                  "status": 401,
                  "message": "Invalid or revoked API key",
                  "when": "The X-API-Key header is missing, wrong or revoked."
                },
                {
                  "status": 429,
                  "message": "Rate limit exceeded (10 requests/minute)",
                  "when": "Over the Navlo AI budget; wait Retry-After seconds."
                }
              ],
              "notes": []
            },
            {
              "kind": "endpoint",
              "id": "ai-conversations-delete",
              "method": "DELETE",
              "path": "/v1/ai/conversations/{id}",
              "summary": "Delete a conversation",
              "description": [
                "Removes it from the API and from the app’s Navlo AI list. Credits already spent stay in the usage report."
              ],
              "auth": "apiKey",
              "rateLimit": "ai",
              "since": "2026-10-22",
              "pathParams": [
                {
                  "name": "id",
                  "type": "uuid",
                  "required": true,
                  "description": "The conversation id."
                }
              ],
              "queryParams": [],
              "headers": [],
              "response": {
                "status": 204,
                "contentType": "",
                "description": "No body.",
                "fields": []
              },
              "requestExamples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl -X DELETE \"https://api.navlo.io/v1/ai/conversations/9d3f7a2e-1c8b-4e6d-b5a9-3f0e7c2d1b84\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\""
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const res = await fetch('https://api.navlo.io/v1/ai/conversations/9d3f7a2e-1c8b-4e6d-b5a9-3f0e7c2d1b84', {\n  method: 'DELETE',\n  headers: { 'X-API-Key': process.env.NAVLO_API_KEY },\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\n// 204 No Content: nothing to parse"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.delete(\n    \"https://api.navlo.io/v1/ai/conversations/9d3f7a2e-1c8b-4e6d-b5a9-3f0e7c2d1b84\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\n# 204 No Content: nothing to parse"
                }
              ],
              "responseExamples": [
                {
                  "status": 204,
                  "contentType": "",
                  "body": ""
                }
              ],
              "errors": [
                {
                  "status": 404,
                  "message": "Conversation not found",
                  "when": "Unknown id, or not a conversation of the key’s creator."
                },
                {
                  "status": 401,
                  "message": "Invalid or revoked API key",
                  "when": "The X-API-Key header is missing, wrong or revoked."
                },
                {
                  "status": 429,
                  "message": "Rate limit exceeded (10 requests/minute)",
                  "when": "Over the Navlo AI budget; wait Retry-After seconds."
                }
              ],
              "notes": []
            }
          ]
        }
      ]
    },
    {
      "id": "events-embed",
      "title": "Webhooks & embed",
      "pages": [
        {
          "id": "webhooks",
          "title": "Webhooks",
          "summary": "Navlo POSTs a signed JSON event to your HTTPS endpoint when something happens to one of your shipments.",
          "blocks": [
            {
              "kind": "prose",
              "text": "Webhooks push changes to you as they happen — milestones, ETA moves, risks, free-time warnings, route changes — so you don’t poll. Every event carries a snapshot of the shipment, a fixed `details` object per topic, and an HMAC signature so you can prove it came from Navlo."
            },
            {
              "kind": "list",
              "ordered": false,
              "items": [
                "Events fire for every shipment in your organization, however it was added — app, API, batch, import.",
                "Muting a shipment silences people, not webhooks: muted shipments still send events.",
                "Delivery is at least once, so one event can arrive more than once: deduplicate on `id`."
              ]
            },
            {
              "kind": "heading",
              "id": "webhooks-setup",
              "title": "Setting up an endpoint"
            },
            {
              "kind": "list",
              "ordered": true,
              "items": [
                "Expose an HTTPS URL on the public internet that accepts `POST` with a JSON body and answers `2xx` within 10 seconds. Navlo doesn’t follow redirects, so register the final URL.",
                "Register it — in the app under **Settings → API & Embedding → Webhooks**, or with [`POST /v1/webhooks`](#webhooks-create). Leave topics empty to receive every topic, including future ones.",
                "Store the signing secret (`whsec_…`). It is shown once, at creation and when you rotate it.",
                "[Verify the signature](#webhooks-signatures) of every request, then [send a test event](#webhooks-test) to see a real payload arrive."
              ]
            },
            {
              "kind": "prose",
              "text": "Organization admins manage endpoints. An organization can have up to 10, and every URL must be `https://`."
            },
            {
              "kind": "heading",
              "id": "webhooks-topics",
              "title": "Topics"
            },
            {
              "kind": "definitions",
              "items": [
                {
                  "term": "`shipment.status_changed`",
                  "description": "The shipment reached a new status (loaded, departed, arrived, delivered...), was seen leaving or reaching port on the vessel's live position, or is approaching its destination."
                },
                {
                  "term": "`shipment.eta_changed`",
                  "description": "The carrier's estimated arrival moved. Carries the previous and the new ETA."
                },
                {
                  "term": "`shipment.completed`",
                  "description": "The shipment finished: every container completed its journey, or the air cargo was delivered."
                },
                {
                  "term": "`shipment.risk_raised`",
                  "description": "A risk was raised: a container idle at a port, a rolled container, a transshipment delay, cargo not loaded or a booking the airline cancelled."
                },
                {
                  "term": "`shipment.dnd`",
                  "description": "Demurrage, detention and storage: free time about to end, charges started, empty return due or done, air cargo near or past its free storage."
                },
                {
                  "term": "`shipment.route_changed`",
                  "description": "The carrier changed the port of discharge. Carries the previous and the new destination."
                },
                {
                  "term": "`shipment.discovery_finished`",
                  "description": "The search for a new shipment ended: the carrier returned it (RESOLVED), or Navlo found no carrier data and stopped searching on its own (NOT_FOUND)."
                }
              ]
            },
            {
              "kind": "heading",
              "id": "webhooks-request",
              "title": "The request Navlo sends"
            },
            {
              "kind": "code",
              "samples": [
                {
                  "lang": "http",
                  "label": "HTTP",
                  "code": "POST /webhooks/navlo HTTP/1.1\nHost: erp.example.com\nContent-Type: application/json; charset=utf-8\nUser-Agent: Navlo-Webhooks/1.0\nX-Navlo-Topic: shipment.eta_changed\nX-Navlo-Event-Id: 3126abb4-12e8-4bff-b18d-d9227adc9a27\nX-Navlo-Timestamp: 1791969735\nX-Navlo-Delivery-Attempt: 1\nX-Navlo-Signature: sha256=c5d25c40c6f3d01c36accfb213241730e6c5bcb289fcd9307b0983b6593f8c26\n\n{\"id\":\"3126abb4-12e8-4bff-b18d-d9227adc9a27\",\"topic\":\"shipment.eta_changed\",\"occurredAt\":\"2026-10-22T13:47:22.503768Z\",\"shipment\":{\"id\":\"5e1c3a9b-0d2f-4f8e-9a61-3b7c2d4e5f60\",\"identifier\":\"MEDUSH123456\",\"mode\":\"OCEAN\",\"status\":\"active\",\"carrier\":\"MSC\",\"customer\":{\"id\":\"0c7d2f6e-3a41-4b0e-9a55-1f2b3c4d5e6f\",\"ref\":\"C-1042\",\"name\":\"Acme Trading Ltd.\",\"countryCode\":\"TR\"},\"origin\":{\"code\":\"CNSHA\",\"name\":\"Shanghai\"},\"destination\":{\"code\":\"TRAMR\",\"name\":\"Ambarli\"},\"eta\":\"2026-11-23T12:00:00Z\",\"vessel\":\"MSC ANNA\",\"voyage\":\"FA442W\"},\"details\":{\"previousEta\":\"2026-11-21T06:00:00Z\",\"newEta\":\"2026-11-23T12:00:00Z\",\"deltaHours\":54,\"containerNumber\":\"MSCU7382154\",\"awbNumber\":null}}"
                }
              ]
            },
            {
              "kind": "definitions",
              "items": [
                {
                  "term": "`X-Navlo-Topic`",
                  "description": "The event’s topic."
                },
                {
                  "term": "`X-Navlo-Event-Id`",
                  "description": "The event id — the same on every retry of the event."
                },
                {
                  "term": "`X-Navlo-Timestamp`",
                  "description": "Unix seconds when this attempt was signed (new on every attempt)."
                },
                {
                  "term": "`X-Navlo-Delivery-Attempt`",
                  "description": "1 for the first attempt, up to 5."
                },
                {
                  "term": "`X-Navlo-Signature`",
                  "description": "`sha256=` + hex HMAC-SHA256 of `\"<timestamp>.<raw body>\"`."
                },
                {
                  "term": "`User-Agent`",
                  "description": "`Navlo-Webhooks/1.0`"
                }
              ]
            },
            {
              "kind": "heading",
              "id": "webhooks-payload",
              "title": "Payload"
            },
            {
              "kind": "prose",
              "text": "Every event has the same envelope. The body is compact JSON (shown pretty-printed in these docs, and key order is not part of the contract). The OpenAPI document describes all seven events under its `webhooks` section, so code generators can build the types."
            },
            {
              "kind": "fields",
              "title": "Envelope",
              "fields": [
                {
                  "name": "id",
                  "type": "uuid",
                  "description": "Event id — the same on every retry. Deduplicate on it."
                },
                {
                  "name": "topic",
                  "type": "string",
                  "description": "One of the [topics](#webhooks-topics)."
                },
                {
                  "name": "occurredAt",
                  "type": "timestamp",
                  "description": "When Navlo raised the event (UTC) — the same for every endpoint that receives it. The carrier’s own event time is in `details`."
                },
                {
                  "name": "shipment",
                  "type": "object",
                  "description": "The shipment as it is now. With several containers, `origin`, `destination`, `eta`, `vessel` and `voyage` describe the first one still on its way."
                },
                {
                  "name": "shipment.id",
                  "type": "uuid",
                  "description": "Shipment id — read the full shipment with [`GET /v1/shipments/{id}`](/developers/shipments#shipments-get)."
                },
                {
                  "name": "shipment.identifier",
                  "type": "string",
                  "description": "The tracked number, as stored."
                },
                {
                  "name": "shipment.mode",
                  "type": "enum",
                  "description": "Transport mode.",
                  "values": [
                    "OCEAN",
                    "AIR"
                  ]
                },
                {
                  "name": "shipment.status",
                  "type": "enum",
                  "description": "Lifecycle status after the change. `tracking` — air only: the waybill was accepted and Navlo is fetching the airline's first data. It becomes `active` when that data arrives (or `discovering` if no airline has it yet). A new air shipment's create response usually says `tracking`. List, export and report filters treat it as `active`.",
                  "values": [
                    "discovering",
                    "resolving",
                    "active",
                    "tracking",
                    "completed",
                    "stopped"
                  ]
                },
                {
                  "name": "shipment.carrier",
                  "type": "string",
                  "nullable": true,
                  "description": "Carrier code — the resolved carrier, else the predicted one, else (air) the waybill’s airline."
                },
                {
                  "name": "shipment.customer",
                  "type": "object",
                  "nullable": true,
                  "description": "The shipment’s customer: `{ id, ref, name, countryCode }`."
                },
                {
                  "name": "shipment.origin",
                  "type": "object",
                  "nullable": true,
                  "description": "Port of loading (ocean) or origin airport (air): `{ code, name }`."
                },
                {
                  "name": "shipment.destination",
                  "type": "object",
                  "nullable": true,
                  "description": "Port of discharge (ocean) or destination airport (air): `{ code, name }`."
                },
                {
                  "name": "shipment.eta",
                  "type": "timestamp",
                  "nullable": true,
                  "description": "The carrier’s ETA at the destination — carrier local time with a `Z` suffix."
                },
                {
                  "name": "shipment.vessel",
                  "type": "string",
                  "nullable": true,
                  "description": "The vessel the cargo is on. Null for air."
                },
                {
                  "name": "shipment.voyage",
                  "type": "string",
                  "nullable": true,
                  "description": "That vessel’s voyage number. Null for air."
                },
                {
                  "name": "details",
                  "type": "object",
                  "description": "What happened — a fixed shape per topic, documented below. Every key is present; a fact the event doesn’t carry is null."
                },
                {
                  "name": "data",
                  "type": "object",
                  "required": false,
                  "description": "**Deprecated, removed on 16 November 2026.** The old block of shipment facts (container, B/L, ports, vessel, dates). Read `shipment` and `details` instead."
                },
                {
                  "name": "test",
                  "type": "boolean",
                  "required": false,
                  "description": "Present and `true` only on [test events](#webhooks-test)."
                }
              ]
            },
            {
              "kind": "callout",
              "tone": "warning",
              "title": "The `data` block is going away",
              "text": "Until 16 November 2026 shipment events also carry the old `data` block, so integrations built on it keep working while they move to `shipment` and `details`. From that day it is no longer sent. Test events never carry it."
            },
            {
              "kind": "heading",
              "id": "webhooks-status-changed",
              "title": "shipment.status_changed"
            },
            {
              "kind": "prose",
              "text": "A container or air waybill reached a new milestone — or Navlo saw the vessel leave or reach port on its live position, or the shipment is approaching its destination. Multi-container shipments may report several containers moving together in one event."
            },
            {
              "kind": "fields",
              "fields": [
                {
                  "name": "details.status",
                  "type": "enum",
                  "description": "The shipment’s lifecycle status after the change — the same value as `shipment.status`.",
                  "values": [
                    "discovering",
                    "resolving",
                    "active",
                    "tracking",
                    "completed",
                    "stopped"
                  ]
                },
                {
                  "name": "details.milestone",
                  "type": "object",
                  "nullable": true,
                  "description": "The milestone reached: `code` and `name` (e.g. `DEPARTED` / \"Departed\"). Navlo’s own announcements use `APPROACHING_DESTINATION`, `DEPARTURE_DETECTED` and `ARRIVAL_DETECTED` (the last two from the vessel’s live position). Air codes can differ from ocean ones (e.g. `DEPARTED_`) — match on `name` for one vocabulary. `code` can be null when Navlo can’t map the name."
                },
                {
                  "name": "details.location",
                  "type": "object",
                  "nullable": true,
                  "description": "Where: `code` (UN/LOCODE or IATA) and `name`. Air: the airport the cargo is at, named when it is the origin or destination. Live-position detections carry only the port name."
                },
                {
                  "name": "details.eventAt",
                  "type": "timestamp",
                  "nullable": true,
                  "description": "When it happened — carrier local time, like event timestamps. Null for the approaching announcement."
                },
                {
                  "name": "details.containerNumber",
                  "type": "string",
                  "nullable": true,
                  "description": "OCEAN: the container."
                },
                {
                  "name": "details.awbNumber",
                  "type": "string",
                  "nullable": true,
                  "description": "AIR: the waybill, dashed (`235-12345675`)."
                }
              ]
            },
            {
              "kind": "code",
              "samples": [
                {
                  "lang": "json",
                  "label": "Ocean",
                  "code": "{\n  \"id\": \"b218dce9-0e1a-442c-b3bd-f42f67001b41\",\n  \"topic\": \"shipment.status_changed\",\n  \"occurredAt\": \"2026-10-22T13:47:22.373797Z\",\n  \"shipment\": {\n    \"id\": \"5e1c3a9b-0d2f-4f8e-9a61-3b7c2d4e5f60\",\n    \"identifier\": \"MEDUSH123456\",\n    \"mode\": \"OCEAN\",\n    \"status\": \"active\",\n    \"carrier\": \"MSC\",\n    \"customer\": {\n      \"id\": \"0c7d2f6e-3a41-4b0e-9a55-1f2b3c4d5e6f\",\n      \"ref\": \"C-1042\",\n      \"name\": \"Acme Trading Ltd.\",\n      \"countryCode\": \"TR\"\n    },\n    \"origin\": {\n      \"code\": \"CNSHA\",\n      \"name\": \"Shanghai\"\n    },\n    \"destination\": {\n      \"code\": \"TRAMR\",\n      \"name\": \"Ambarli\"\n    },\n    \"eta\": \"2026-11-21T06:00:00Z\",\n    \"vessel\": \"MSC ANNA\",\n    \"voyage\": \"FA442W\"\n  },\n  \"details\": {\n    \"status\": \"active\",\n    \"milestone\": {\n      \"code\": \"DEPARTED\",\n      \"name\": \"Departed\"\n    },\n    \"location\": {\n      \"code\": \"CNSHA\",\n      \"name\": \"Shanghai\"\n    },\n    \"eventAt\": \"2026-10-20T14:30:00Z\",\n    \"containerNumber\": \"MSCU7382154\",\n    \"awbNumber\": null\n  }\n}"
                },
                {
                  "lang": "json",
                  "label": "Air",
                  "code": "{\n  \"id\": \"57c4b6f6-66b2-4ea3-8b7a-edb5cb762fef\",\n  \"topic\": \"shipment.status_changed\",\n  \"occurredAt\": \"2026-10-22T13:47:22.499925Z\",\n  \"shipment\": {\n    \"id\": \"9b2f6c1d-7e3a-4c58-b0d4-2a6e8f1c3b75\",\n    \"identifier\": \"23512345675\",\n    \"mode\": \"AIR\",\n    \"status\": \"active\",\n    \"carrier\": \"TURKISH_AIRLINES\",\n    \"customer\": null,\n    \"origin\": {\n      \"code\": \"IST\",\n      \"name\": \"Istanbul Airport\"\n    },\n    \"destination\": {\n      \"code\": \"JFK\",\n      \"name\": \"John F. Kennedy International Airport\"\n    },\n    \"eta\": \"2026-10-23T06:40:00Z\",\n    \"vessel\": null,\n    \"voyage\": null\n  },\n  \"details\": {\n    \"status\": \"active\",\n    \"milestone\": {\n      \"code\": \"DEPARTED_\",\n      \"name\": \"Departed\"\n    },\n    \"location\": {\n      \"code\": \"IST\",\n      \"name\": \"Istanbul Airport\"\n    },\n    \"eventAt\": \"2026-10-22T23:55:00Z\",\n    \"containerNumber\": null,\n    \"awbNumber\": \"235-12345675\"\n  }\n}"
                }
              ]
            },
            {
              "kind": "heading",
              "id": "webhooks-eta-changed",
              "title": "shipment.eta_changed"
            },
            {
              "kind": "prose",
              "text": "The carrier’s ETA moved. Ocean events fire when the ETA moves at least 6 hours onto another day; air events fire on every announced change, including moves within the same day."
            },
            {
              "kind": "fields",
              "fields": [
                {
                  "name": "details.previousEta",
                  "type": "timestamp",
                  "description": "ETA before the change."
                },
                {
                  "name": "details.newEta",
                  "type": "timestamp",
                  "description": "ETA after the change."
                },
                {
                  "name": "details.deltaHours",
                  "type": "number",
                  "description": "Signed hours with one decimal; positive means later, negative earlier."
                },
                {
                  "name": "details.containerNumber",
                  "type": "string",
                  "nullable": true,
                  "description": "OCEAN: the container."
                },
                {
                  "name": "details.awbNumber",
                  "type": "string",
                  "nullable": true,
                  "description": "AIR: the waybill."
                }
              ]
            },
            {
              "kind": "code",
              "samples": [
                {
                  "lang": "json",
                  "label": "Ocean",
                  "code": "{\n  \"id\": \"3126abb4-12e8-4bff-b18d-d9227adc9a27\",\n  \"topic\": \"shipment.eta_changed\",\n  \"occurredAt\": \"2026-10-22T13:47:22.503768Z\",\n  \"shipment\": {\n    \"id\": \"5e1c3a9b-0d2f-4f8e-9a61-3b7c2d4e5f60\",\n    \"identifier\": \"MEDUSH123456\",\n    \"mode\": \"OCEAN\",\n    \"status\": \"active\",\n    \"carrier\": \"MSC\",\n    \"customer\": {\n      \"id\": \"0c7d2f6e-3a41-4b0e-9a55-1f2b3c4d5e6f\",\n      \"ref\": \"C-1042\",\n      \"name\": \"Acme Trading Ltd.\",\n      \"countryCode\": \"TR\"\n    },\n    \"origin\": {\n      \"code\": \"CNSHA\",\n      \"name\": \"Shanghai\"\n    },\n    \"destination\": {\n      \"code\": \"TRAMR\",\n      \"name\": \"Ambarli\"\n    },\n    \"eta\": \"2026-11-23T12:00:00Z\",\n    \"vessel\": \"MSC ANNA\",\n    \"voyage\": \"FA442W\"\n  },\n  \"details\": {\n    \"previousEta\": \"2026-11-21T06:00:00Z\",\n    \"newEta\": \"2026-11-23T12:00:00Z\",\n    \"deltaHours\": 54,\n    \"containerNumber\": \"MSCU7382154\",\n    \"awbNumber\": null\n  }\n}"
                },
                {
                  "lang": "json",
                  "label": "Air",
                  "code": "{\n  \"id\": \"653c84e3-178c-4426-a231-fee68962a6de\",\n  \"topic\": \"shipment.eta_changed\",\n  \"occurredAt\": \"2026-10-22T13:47:22.505656Z\",\n  \"shipment\": {\n    \"id\": \"9b2f6c1d-7e3a-4c58-b0d4-2a6e8f1c3b75\",\n    \"identifier\": \"23512345675\",\n    \"mode\": \"AIR\",\n    \"status\": \"active\",\n    \"carrier\": \"TURKISH_AIRLINES\",\n    \"customer\": null,\n    \"origin\": {\n      \"code\": \"IST\",\n      \"name\": \"Istanbul Airport\"\n    },\n    \"destination\": {\n      \"code\": \"JFK\",\n      \"name\": \"John F. Kennedy International Airport\"\n    },\n    \"eta\": \"2026-10-23T09:10:00Z\",\n    \"vessel\": null,\n    \"voyage\": null\n  },\n  \"details\": {\n    \"previousEta\": \"2026-10-23T06:40:00Z\",\n    \"newEta\": \"2026-10-23T09:10:00Z\",\n    \"deltaHours\": 2.5,\n    \"containerNumber\": null,\n    \"awbNumber\": \"235-12345675\"\n  }\n}"
                }
              ]
            },
            {
              "kind": "heading",
              "id": "webhooks-completed",
              "title": "shipment.completed"
            },
            {
              "kind": "prose",
              "text": "The shipment finished — ocean once its last container is done, air when the cargo is delivered. Sent once per shipment."
            },
            {
              "kind": "fields",
              "fields": [
                {
                  "name": "details.completedAt",
                  "type": "timestamp",
                  "description": "When it finished: the delivery date, else the actual arrival, else when Navlo raised the event."
                },
                {
                  "name": "details.containerNumber",
                  "type": "string",
                  "nullable": true,
                  "description": "OCEAN: the last container to finish."
                },
                {
                  "name": "details.awbNumber",
                  "type": "string",
                  "nullable": true,
                  "description": "AIR: the waybill."
                }
              ]
            },
            {
              "kind": "code",
              "samples": [
                {
                  "lang": "json",
                  "label": "Ocean",
                  "code": "{\n  \"id\": \"f10108a9-720c-46d0-9923-462a17ba781b\",\n  \"topic\": \"shipment.completed\",\n  \"occurredAt\": \"2026-10-22T13:47:22.507018Z\",\n  \"shipment\": {\n    \"id\": \"5e1c3a9b-0d2f-4f8e-9a61-3b7c2d4e5f60\",\n    \"identifier\": \"MEDUSH123456\",\n    \"mode\": \"OCEAN\",\n    \"status\": \"completed\",\n    \"carrier\": \"MSC\",\n    \"customer\": {\n      \"id\": \"0c7d2f6e-3a41-4b0e-9a55-1f2b3c4d5e6f\",\n      \"ref\": \"C-1042\",\n      \"name\": \"Acme Trading Ltd.\",\n      \"countryCode\": \"TR\"\n    },\n    \"origin\": {\n      \"code\": \"CNSHA\",\n      \"name\": \"Shanghai\"\n    },\n    \"destination\": {\n      \"code\": \"TRAMR\",\n      \"name\": \"Ambarli\"\n    },\n    \"eta\": \"2026-11-23T12:00:00Z\",\n    \"vessel\": \"MSC ANNA\",\n    \"voyage\": \"FA442W\"\n  },\n  \"details\": {\n    \"completedAt\": \"2026-11-26T10:20:00Z\",\n    \"containerNumber\": \"MSCU7382154\",\n    \"awbNumber\": null\n  }\n}"
                },
                {
                  "lang": "json",
                  "label": "Air",
                  "code": "{\n  \"id\": \"4c9e2a7f-3b18-4d65-9f0a-7e2c5b8d1a36\",\n  \"topic\": \"shipment.completed\",\n  \"occurredAt\": \"2026-10-23T07:05:13.880412Z\",\n  \"shipment\": {\n    \"id\": \"9b2f6c1d-7e3a-4c58-b0d4-2a6e8f1c3b75\",\n    \"identifier\": \"23512345675\",\n    \"mode\": \"AIR\",\n    \"status\": \"completed\",\n    \"carrier\": \"TURKISH_AIRLINES\",\n    \"customer\": null,\n    \"origin\": {\n      \"code\": \"IST\",\n      \"name\": \"Istanbul Airport\"\n    },\n    \"destination\": {\n      \"code\": \"JFK\",\n      \"name\": \"John F. Kennedy International Airport\"\n    },\n    \"eta\": \"2026-10-23T09:10:00Z\",\n    \"vessel\": null,\n    \"voyage\": null\n  },\n  \"details\": {\n    \"completedAt\": \"2026-10-23T06:52:00Z\",\n    \"containerNumber\": null,\n    \"awbNumber\": \"235-12345675\"\n  }\n}"
                }
              ]
            },
            {
              "kind": "callout",
              "tone": "info",
              "text": "Shipments you complete yourself with [`POST …/complete`](/developers/shipment-actions#actions-complete) send no event — your system made the change."
            },
            {
              "kind": "heading",
              "id": "webhooks-risk-raised",
              "title": "shipment.risk_raised"
            },
            {
              "kind": "fields",
              "fields": [
                {
                  "name": "details.kind",
                  "type": "enum",
                  "description": "`RISK_ALERT` — Navlo’s risk monitor (e.g. a container idle for days). `ROLLOVER` — cargo rolled to a later vessel. `TRANSSHIPMENT_DELAY` — stuck at a transshipment port. `CARGO_NOT_LOADED` — air cargo missed its flight. `BOOKING_CANCELLED` — the airline cancelled the booking.",
                  "values": [
                    "RISK_ALERT",
                    "ROLLOVER",
                    "TRANSSHIPMENT_DELAY",
                    "CARGO_NOT_LOADED",
                    "BOOKING_CANCELLED"
                  ]
                },
                {
                  "name": "details.level",
                  "type": "enum",
                  "nullable": true,
                  "description": "How serious, for the kinds that grade it (the idle alert); null otherwise.",
                  "values": [
                    "MEDIUM",
                    "HIGH",
                    "CRITICAL"
                  ]
                },
                {
                  "name": "details.summary",
                  "type": "string",
                  "nullable": true,
                  "description": "One sentence for people; null for a cancelled booking."
                },
                {
                  "name": "details.containerNumber",
                  "type": "string",
                  "nullable": true,
                  "description": "OCEAN: the container."
                },
                {
                  "name": "details.awbNumber",
                  "type": "string",
                  "nullable": true,
                  "description": "AIR: the waybill."
                }
              ]
            },
            {
              "kind": "code",
              "samples": [
                {
                  "lang": "json",
                  "label": "Ocean: idle container",
                  "code": "{\n  \"id\": \"5bb76597-193a-4e8b-8c4a-678dbd42e707\",\n  \"topic\": \"shipment.risk_raised\",\n  \"occurredAt\": \"2026-10-22T13:47:22.508985Z\",\n  \"shipment\": {\n    \"id\": \"5e1c3a9b-0d2f-4f8e-9a61-3b7c2d4e5f60\",\n    \"identifier\": \"MEDUSH123456\",\n    \"mode\": \"OCEAN\",\n    \"status\": \"active\",\n    \"carrier\": \"MSC\",\n    \"customer\": {\n      \"id\": \"0c7d2f6e-3a41-4b0e-9a55-1f2b3c4d5e6f\",\n      \"ref\": \"C-1042\",\n      \"name\": \"Acme Trading Ltd.\",\n      \"countryCode\": \"TR\"\n    },\n    \"origin\": {\n      \"code\": \"CNSHA\",\n      \"name\": \"Shanghai\"\n    },\n    \"destination\": {\n      \"code\": \"TRAMR\",\n      \"name\": \"Ambarli\"\n    },\n    \"eta\": \"2026-11-23T12:00:00Z\",\n    \"vessel\": \"MSC ANNA\",\n    \"voyage\": \"FA442W\"\n  },\n  \"details\": {\n    \"kind\": \"RISK_ALERT\",\n    \"level\": \"HIGH\",\n    \"summary\": \"MSCU7382154 has not moved for 6 days at Port Klang.\",\n    \"containerNumber\": \"MSCU7382154\",\n    \"awbNumber\": null\n  }\n}"
                },
                {
                  "lang": "json",
                  "label": "Air: booking cancelled",
                  "code": "{\n  \"id\": \"af302ccc-ffc4-47c6-b1d2-d7e8492be833\",\n  \"topic\": \"shipment.risk_raised\",\n  \"occurredAt\": \"2026-10-22T13:47:22.510414Z\",\n  \"shipment\": {\n    \"id\": \"9b2f6c1d-7e3a-4c58-b0d4-2a6e8f1c3b75\",\n    \"identifier\": \"23512345675\",\n    \"mode\": \"AIR\",\n    \"status\": \"active\",\n    \"carrier\": \"TURKISH_AIRLINES\",\n    \"customer\": null,\n    \"origin\": {\n      \"code\": \"IST\",\n      \"name\": \"Istanbul Airport\"\n    },\n    \"destination\": {\n      \"code\": \"JFK\",\n      \"name\": \"John F. Kennedy International Airport\"\n    },\n    \"eta\": \"2026-10-23T09:10:00Z\",\n    \"vessel\": null,\n    \"voyage\": null\n  },\n  \"details\": {\n    \"kind\": \"BOOKING_CANCELLED\",\n    \"level\": null,\n    \"summary\": null,\n    \"containerNumber\": null,\n    \"awbNumber\": \"235-12345675\"\n  }\n}"
                }
              ]
            },
            {
              "kind": "heading",
              "id": "webhooks-dnd",
              "title": "shipment.dnd"
            },
            {
              "kind": "prose",
              "text": "Free time is running out, charges started, or the empty is due or returned. Warnings start 48 hours before free time ends and repeat daily."
            },
            {
              "kind": "fields",
              "fields": [
                {
                  "name": "details.kind",
                  "type": "enum",
                  "description": "What happened.",
                  "values": [
                    "FREE_TIME_WARNING",
                    "DEMURRAGE_STARTED",
                    "DETENTION_STARTED",
                    "EMPTY_RETURN_DUE",
                    "EMPTY_RETURNED",
                    "AIR_STORAGE_RISK"
                  ]
                },
                {
                  "name": "details.freeTimeEndsAt",
                  "type": "timestamp",
                  "nullable": true,
                  "description": "When free time ends (or ended); for `DETENTION_STARTED` when detention started, for `EMPTY_RETURN_DUE` the due date; null for `EMPTY_RETURNED`."
                },
                {
                  "name": "details.daysLeft",
                  "type": "integer",
                  "nullable": true,
                  "description": "Whole days until `freeTimeEndsAt`, never below 0 — `0` once demurrage or storage is accruing. Null only for `EMPTY_RETURNED`."
                },
                {
                  "name": "details.containerNumber",
                  "type": "string",
                  "nullable": true,
                  "description": "OCEAN: the container."
                },
                {
                  "name": "details.awbNumber",
                  "type": "string",
                  "nullable": true,
                  "description": "AIR: the waybill."
                }
              ]
            },
            {
              "kind": "code",
              "samples": [
                {
                  "lang": "json",
                  "label": "Ocean: free-time warning",
                  "code": "{\n  \"id\": \"e15f5e4a-1d3e-42cf-9884-156ee527bb31\",\n  \"topic\": \"shipment.dnd\",\n  \"occurredAt\": \"2026-10-22T13:47:22.510890Z\",\n  \"shipment\": {\n    \"id\": \"5e1c3a9b-0d2f-4f8e-9a61-3b7c2d4e5f60\",\n    \"identifier\": \"MEDUSH123456\",\n    \"mode\": \"OCEAN\",\n    \"status\": \"active\",\n    \"carrier\": \"MSC\",\n    \"customer\": {\n      \"id\": \"0c7d2f6e-3a41-4b0e-9a55-1f2b3c4d5e6f\",\n      \"ref\": \"C-1042\",\n      \"name\": \"Acme Trading Ltd.\",\n      \"countryCode\": \"TR\"\n    },\n    \"origin\": {\n      \"code\": \"CNSHA\",\n      \"name\": \"Shanghai\"\n    },\n    \"destination\": {\n      \"code\": \"TRAMR\",\n      \"name\": \"Ambarli\"\n    },\n    \"eta\": \"2026-11-23T12:00:00Z\",\n    \"vessel\": \"MSC ANNA\",\n    \"voyage\": \"FA442W\"\n  },\n  \"details\": {\n    \"kind\": \"FREE_TIME_WARNING\",\n    \"freeTimeEndsAt\": \"2026-10-24T19:00:00Z\",\n    \"daysLeft\": 2,\n    \"containerNumber\": \"MSCU7382154\",\n    \"awbNumber\": null\n  }\n}"
                },
                {
                  "lang": "json",
                  "label": "Air: storage",
                  "code": "{\n  \"id\": \"8ec5b0dd-00d2-4f4d-b221-05e453776aef\",\n  \"topic\": \"shipment.dnd\",\n  \"occurredAt\": \"2026-10-22T13:47:22.513501Z\",\n  \"shipment\": {\n    \"id\": \"9b2f6c1d-7e3a-4c58-b0d4-2a6e8f1c3b75\",\n    \"identifier\": \"23512345675\",\n    \"mode\": \"AIR\",\n    \"status\": \"active\",\n    \"carrier\": \"TURKISH_AIRLINES\",\n    \"customer\": null,\n    \"origin\": {\n      \"code\": \"IST\",\n      \"name\": \"Istanbul Airport\"\n    },\n    \"destination\": {\n      \"code\": \"JFK\",\n      \"name\": \"John F. Kennedy International Airport\"\n    },\n    \"eta\": \"2026-10-23T09:10:00Z\",\n    \"vessel\": null,\n    \"voyage\": null\n  },\n  \"details\": {\n    \"kind\": \"AIR_STORAGE_RISK\",\n    \"freeTimeEndsAt\": \"2026-10-23T09:47:00Z\",\n    \"daysLeft\": 0,\n    \"containerNumber\": null,\n    \"awbNumber\": \"235-12345675\"\n  }\n}"
                }
              ]
            },
            {
              "kind": "heading",
              "id": "webhooks-route-changed",
              "title": "shipment.route_changed"
            },
            {
              "kind": "fields",
              "fields": [
                {
                  "name": "details.previousDestination",
                  "type": "object",
                  "nullable": true,
                  "description": "Port of discharge before: `code`, `name`."
                },
                {
                  "name": "details.newDestination",
                  "type": "object",
                  "nullable": true,
                  "description": "Port of discharge now: `code`, `name`."
                }
              ]
            },
            {
              "kind": "code",
              "samples": [
                {
                  "lang": "json",
                  "label": "Port of discharge changed",
                  "code": "{\n  \"id\": \"2b62a80e-5e5f-483d-9d3f-2f9875f1cf71\",\n  \"topic\": \"shipment.route_changed\",\n  \"occurredAt\": \"2026-10-22T13:47:22.514065Z\",\n  \"shipment\": {\n    \"id\": \"5e1c3a9b-0d2f-4f8e-9a61-3b7c2d4e5f60\",\n    \"identifier\": \"MEDUSH123456\",\n    \"mode\": \"OCEAN\",\n    \"status\": \"active\",\n    \"carrier\": \"MSC\",\n    \"customer\": {\n      \"id\": \"0c7d2f6e-3a41-4b0e-9a55-1f2b3c4d5e6f\",\n      \"ref\": \"C-1042\",\n      \"name\": \"Acme Trading Ltd.\",\n      \"countryCode\": \"TR\"\n    },\n    \"origin\": {\n      \"code\": \"CNSHA\",\n      \"name\": \"Shanghai\"\n    },\n    \"destination\": {\n      \"code\": \"TRMER\",\n      \"name\": \"Mersin\"\n    },\n    \"eta\": \"2026-11-24T08:00:00Z\",\n    \"vessel\": \"MSC ANNA\",\n    \"voyage\": \"FA442W\"\n  },\n  \"details\": {\n    \"previousDestination\": {\n      \"code\": \"TRAMR\",\n      \"name\": \"Ambarli\"\n    },\n    \"newDestination\": {\n      \"code\": \"TRMER\",\n      \"name\": \"Mersin\"\n    }\n  }\n}"
                }
              ]
            },
            {
              "kind": "heading",
              "id": "webhooks-discovery-finished",
              "title": "shipment.discovery_finished"
            },
            {
              "kind": "prose",
              "text": "The search for a new shipment ended. Subscribe to it when you create shipments through the API and need to know how the identifier resolved. While Navlo is still retrying, no event is sent."
            },
            {
              "kind": "definitions",
              "items": [
                {
                  "term": "`RESOLVED`",
                  "description": "The carrier returned the shipment; it now has containers or air waybills."
                },
                {
                  "term": "`NOT_FOUND`",
                  "description": "Navlo got no usable carrier data and stopped searching on its own. `status` says how it rests: `stopped` — Navlo stopped looking; `discovering` — Navlo is still looking. If it’s found later, a `RESOLVED` event follows."
                }
              ]
            },
            {
              "kind": "fields",
              "fields": [
                {
                  "name": "details.outcome",
                  "type": "enum",
                  "description": "How the search ended.",
                  "values": [
                    "RESOLVED",
                    "NOT_FOUND"
                  ]
                },
                {
                  "name": "details.status",
                  "type": "enum",
                  "description": "The shipment’s status now.",
                  "values": [
                    "discovering",
                    "resolving",
                    "active",
                    "tracking",
                    "completed",
                    "stopped"
                  ]
                },
                {
                  "name": "details.carrier",
                  "type": "string",
                  "nullable": true,
                  "description": "The carrier found; null for `NOT_FOUND`."
                }
              ]
            },
            {
              "kind": "code",
              "samples": [
                {
                  "lang": "json",
                  "label": "RESOLVED",
                  "code": "{\n  \"id\": \"e3da450d-85fa-48e9-abef-d8469dc25209\",\n  \"topic\": \"shipment.discovery_finished\",\n  \"occurredAt\": \"2026-10-22T13:47:22.516212Z\",\n  \"shipment\": {\n    \"id\": \"5e1c3a9b-0d2f-4f8e-9a61-3b7c2d4e5f60\",\n    \"identifier\": \"MEDUSH123456\",\n    \"mode\": \"OCEAN\",\n    \"status\": \"active\",\n    \"carrier\": \"MSC\",\n    \"customer\": {\n      \"id\": \"0c7d2f6e-3a41-4b0e-9a55-1f2b3c4d5e6f\",\n      \"ref\": \"C-1042\",\n      \"name\": \"Acme Trading Ltd.\",\n      \"countryCode\": \"TR\"\n    },\n    \"origin\": {\n      \"code\": \"CNSHA\",\n      \"name\": \"Shanghai\"\n    },\n    \"destination\": {\n      \"code\": \"TRAMR\",\n      \"name\": \"Ambarli\"\n    },\n    \"eta\": \"2026-11-21T06:00:00Z\",\n    \"vessel\": \"MSC ANNA\",\n    \"voyage\": \"FA442W\"\n  },\n  \"details\": {\n    \"outcome\": \"RESOLVED\",\n    \"status\": \"active\",\n    \"carrier\": \"MSC\"\n  }\n}"
                },
                {
                  "lang": "json",
                  "label": "NOT_FOUND",
                  "code": "{\n  \"id\": \"f4a8c2e6-1d9b-4b73-8e5a-3c0f7d2b9e61\",\n  \"topic\": \"shipment.discovery_finished\",\n  \"occurredAt\": \"2026-10-22T15:02:41.118037Z\",\n  \"shipment\": {\n    \"id\": \"a1d5c8e2-6f3b-4e97-8c20-4b9e7d1f3a65\",\n    \"identifier\": \"MEDUSH480177\",\n    \"mode\": \"OCEAN\",\n    \"status\": \"stopped\",\n    \"carrier\": null,\n    \"customer\": {\n      \"id\": \"0c7d2f6e-3a41-4b0e-9a55-1f2b3c4d5e6f\",\n      \"ref\": \"C-1042\",\n      \"name\": \"Acme Trading Ltd.\",\n      \"countryCode\": \"TR\"\n    },\n    \"origin\": null,\n    \"destination\": null,\n    \"eta\": null,\n    \"vessel\": null,\n    \"voyage\": null\n  },\n  \"details\": {\n    \"outcome\": \"NOT_FOUND\",\n    \"status\": \"stopped\",\n    \"carrier\": null\n  }\n}"
                }
              ]
            },
            {
              "kind": "prose",
              "text": "Delivery is at-least-once — deduplicate on `id`."
            },
            {
              "kind": "heading",
              "id": "webhooks-signatures",
              "title": "Verifying signatures"
            },
            {
              "kind": "list",
              "ordered": true,
              "items": [
                "Read the raw request body as bytes — before any JSON parsing.",
                "Compute HMAC-SHA256 over `\"<X-Navlo-Timestamp>.<raw body>\"`, keyed with your endpoint’s whole secret, `whsec_` prefix included.",
                "Compare `\"sha256=\" + hex digest` with `X-Navlo-Signature` in constant time.",
                "Reject timestamps more than 5 minutes from your clock — that stops a captured request being replayed."
              ]
            },
            {
              "kind": "code",
              "title": "Verify and acknowledge",
              "samples": [
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "import crypto from 'node:crypto'\nimport express from 'express'\n\nconst app = express()\nconst SECRET = process.env.NAVLO_WEBHOOK_SECRET // the whole \"whsec_…\" string, exactly as shown\nconst TOLERANCE_SECONDS = 300\n\n// express.raw keeps the exact bytes Navlo signed — don't verify a re-serialised req.body.\napp.post('/webhooks/navlo', express.raw({ type: 'application/json' }), (req, res) => {\n  const timestamp = req.get('X-Navlo-Timestamp') ?? ''\n  const signature = req.get('X-Navlo-Signature') ?? ''\n  const expected =\n    'sha256=' + crypto.createHmac('sha256', SECRET).update(`${timestamp}.`).update(req.body).digest('hex')\n\n  const valid =\n    signature.length === expected.length && crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))\n  const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) <= TOLERANCE_SECONDS\n  if (!valid || !fresh) return res.sendStatus(401)\n\n  const event = JSON.parse(req.body.toString('utf8'))\n  res.sendStatus(200) // acknowledge within 10 seconds…\n  queue.add(event) // …then process asynchronously, skipping event.id values you have already handled\n})\n\napp.listen(3000)"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import hashlib\nimport hmac\nimport json\nimport os\nimport time\n\nfrom flask import Flask, abort, request\n\napp = Flask(__name__)\nSECRET = os.environ[\"NAVLO_WEBHOOK_SECRET\"].encode()  # the whole \"whsec_…\" string\nTOLERANCE_SECONDS = 300\n\n\n@app.post(\"/webhooks/navlo\")\ndef navlo_webhook():\n    timestamp = request.headers.get(\"X-Navlo-Timestamp\", \"\")\n    signature = request.headers.get(\"X-Navlo-Signature\", \"\")\n    body = request.get_data()  # raw bytes: verify before parsing\n\n    expected = \"sha256=\" + hmac.new(SECRET, timestamp.encode() + b\".\" + body, hashlib.sha256).hexdigest()\n    if not hmac.compare_digest(signature, expected):\n        abort(401)\n    if not timestamp.isdigit() or abs(time.time() - int(timestamp)) > TOLERANCE_SECONDS:\n        abort(401)\n\n    event = json.loads(body)\n    enqueue(event)  # process asynchronously; skip event[\"id\"] values you have already handled\n    return \"\", 200"
                },
                {
                  "lang": "php",
                  "label": "PHP",
                  "code": "<?php\n// The whole \"whsec_…\" string, exactly as shown when the endpoint was created.\n$secret = getenv('NAVLO_WEBHOOK_SECRET');\n$tolerance = 300;\n\n$body = file_get_contents('php://input'); // raw bytes: verify before json_decode\n$timestamp = $_SERVER['HTTP_X_NAVLO_TIMESTAMP'] ?? '';\n$signature = $_SERVER['HTTP_X_NAVLO_SIGNATURE'] ?? '';\n\n$expected = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $body, $secret);\nif (!hash_equals($expected, $signature) || !ctype_digit($timestamp) || abs(time() - (int) $timestamp) > $tolerance) {\n    http_response_code(401);\n    exit;\n}\n\n$event = json_decode($body, true);\nhttp_response_code(200);\n// Hand $event to a queue; skip $event['id'] values you have already handled."
                },
                {
                  "lang": "csharp",
                  "label": "C#",
                  "code": "using System.Security.Cryptography;\nusing System.Text;\nusing System.Text.Json;\n\nvar builder = WebApplication.CreateBuilder(args);\nvar app = builder.Build();\nvar secret = Environment.GetEnvironmentVariable(\"NAVLO_WEBHOOK_SECRET\")!; // the whole \"whsec_…\" string\nconst long ToleranceSeconds = 300;\n\napp.MapPost(\"/webhooks/navlo\", async (HttpRequest request) =>\n{\n    using var reader = new StreamReader(request.Body, Encoding.UTF8);\n    var body = await reader.ReadToEndAsync(); // raw body: verify before deserialising\n    var timestamp = request.Headers[\"X-Navlo-Timestamp\"].ToString();\n    var signature = request.Headers[\"X-Navlo-Signature\"].ToString();\n\n    using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret));\n    var hash = hmac.ComputeHash(Encoding.UTF8.GetBytes($\"{timestamp}.{body}\"));\n    var expected = \"sha256=\" + Convert.ToHexString(hash).ToLowerInvariant();\n\n    var valid = CryptographicOperations.FixedTimeEquals(\n        Encoding.UTF8.GetBytes(expected), Encoding.UTF8.GetBytes(signature));\n    var fresh = long.TryParse(timestamp, out var ts)\n        && Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - ts) <= ToleranceSeconds;\n    if (!valid || !fresh) return Results.Unauthorized();\n\n    using var navloEvent = JsonDocument.Parse(body);\n    // Hand it to a queue; skip ids you have already handled.\n    return Results.Ok();\n});\n\napp.Run();"
                }
              ]
            },
            {
              "kind": "prose",
              "text": "Check your implementation against this test vector before going live:"
            },
            {
              "kind": "code",
              "samples": [
                {
                  "lang": "text",
                  "label": "Test vector",
                  "code": "secret             whsec_7d1f9a3c5e8b2d4f6a0c1e3b5d7f9a2c4e6b8d0f1a3c5e7b9d2f4a6c8e0b1d3f\nX-Navlo-Timestamp  1791969735\nraw body           {\"id\":\"4f1c0a6b-2d83-4e57-9c11-7a5b3e08d642\",\"topic\":\"shipment.eta_changed\"}\n\nX-Navlo-Signature  sha256=bc366d951a2acc630c9e028db4f2a71499301dd110bbdbd706e8afab0fb3c0d6"
                }
              ]
            },
            {
              "kind": "callout",
              "tone": "warning",
              "text": "Frameworks that parse JSON before your handler runs (Express `json()`, ASP.NET model binding) change the bytes — whitespace, key order, unicode escapes — and the signature will not match. Verify the raw body."
            },
            {
              "kind": "heading",
              "id": "webhooks-retries",
              "title": "Retries and failures"
            },
            {
              "kind": "definitions",
              "items": [
                {
                  "term": "Success",
                  "description": "Any `2xx` within 10 seconds. Answer first, then do the work."
                },
                {
                  "term": "Redirects",
                  "description": "A `3xx` is a failed attempt — redirects are not followed. Point the webhook at the final URL."
                },
                {
                  "term": "Retries",
                  "description": "5 attempts in total: right away, then after 1, 5, 20 and 60 minutes."
                },
                {
                  "term": "Order",
                  "description": "Oldest first per endpoint, but retries can reorder events — trust `occurredAt` and the shipment’s current state."
                },
                {
                  "term": "Auto-disable",
                  "description": "After 20 failed attempts in a row the endpoint is switched off and `disabledReason` says why. Failed test deliveries count too."
                },
                {
                  "term": "Re-enable",
                  "description": "`PATCH` with `\"active\": true` (or the app) — this clears the failure streak."
                },
                {
                  "term": "History",
                  "description": "Every attempt is listed in [deliveries](#webhooks-deliveries) for 30 days."
                }
              ]
            },
            {
              "kind": "prose",
              "text": "Events raised while an endpoint is disabled are not replayed when you re-enable it. To catch up, sync with [`updatedSince`](/developers/shipments#shipments-sync) from the time it was disabled. Redirects are followed, but don’t rely on them: give Navlo the final URL."
            },
            {
              "kind": "heading",
              "id": "webhooks-test",
              "title": "Test events"
            },
            {
              "kind": "prose",
              "text": "Send a realistic sample event to an endpoint at any time — from the app’s **Send test event** button or [`POST /v1/webhooks/{id}/test`](#webhooks-send-test). It goes to that endpoint whatever its topics, through normal delivery — signature, retries and the failure streak included — within a minute. It carries `\"test\": true` and a fixed sample shipment (id `5e1c3a9b-0d2f-4f8e-9a61-3b7c2d4e5f60`), so don’t look that shipment up; its dates are relative to the moment you send it."
            },
            {
              "kind": "code",
              "samples": [
                {
                  "lang": "json",
                  "label": "Test event",
                  "code": "{\n  \"id\": \"33729788-59e4-4e9e-8e11-ef83b47ce78b\",\n  \"topic\": \"shipment.status_changed\",\n  \"occurredAt\": \"2026-10-22T13:47:22.703799Z\",\n  \"shipment\": {\n    \"id\": \"5e1c3a9b-0d2f-4f8e-9a61-3b7c2d4e5f60\",\n    \"identifier\": \"MSCU7382154\",\n    \"mode\": \"OCEAN\",\n    \"status\": \"active\",\n    \"carrier\": \"MSC\",\n    \"customer\": {\n      \"id\": \"0c7d2f6e-3a41-4b0e-9a55-1f2b3c4d5e6f\",\n      \"ref\": \"C-1042\",\n      \"name\": \"Acme Trading Ltd.\",\n      \"countryCode\": \"TR\"\n    },\n    \"origin\": {\n      \"code\": \"CNSHA\",\n      \"name\": \"Shanghai\"\n    },\n    \"destination\": {\n      \"code\": \"TRAMR\",\n      \"name\": \"Ambarli\"\n    },\n    \"eta\": \"2026-11-18T13:47:00Z\",\n    \"vessel\": \"MSC ANNA\",\n    \"voyage\": \"FA442W\"\n  },\n  \"details\": {\n    \"status\": \"active\",\n    \"milestone\": {\n      \"code\": \"DEPARTED\",\n      \"name\": \"Departed\"\n    },\n    \"location\": {\n      \"code\": \"CNSHA\",\n      \"name\": \"Shanghai\"\n    },\n    \"eventAt\": \"2026-10-22T11:47:00Z\",\n    \"containerNumber\": \"MSCU7382154\",\n    \"awbNumber\": null\n  },\n  \"test\": true\n}"
                }
              ]
            },
            {
              "kind": "heading",
              "id": "webhooks-management",
              "title": "Managing endpoints over the API"
            },
            {
              "kind": "prose",
              "text": "The same endpoints the app’s Webhooks screen manages. Creating, updating, rotating, testing and deleting need the key’s creator to be an organization admin."
            },
            {
              "kind": "endpoint",
              "id": "webhooks-list",
              "method": "GET",
              "path": "/v1/webhooks",
              "summary": "List webhook endpoints",
              "description": [],
              "auth": "apiKey",
              "rateLimit": "general",
              "since": "2026-10-22",
              "pathParams": [],
              "queryParams": [],
              "headers": [],
              "response": {
                "status": 200,
                "contentType": "application/json",
                "description": "An array of endpoints, disabled ones included.",
                "fields": [
                  {
                    "name": "[].id",
                    "type": "uuid",
                    "description": "Endpoint id."
                  },
                  {
                    "name": "[].name",
                    "type": "string",
                    "description": "Your label for it."
                  },
                  {
                    "name": "[].url",
                    "type": "string",
                    "description": "Where events are POSTed."
                  },
                  {
                    "name": "[].topics",
                    "type": "array<string>",
                    "description": "Subscribed topics; `[]` means every topic, including topics added later."
                  },
                  {
                    "name": "[].active",
                    "type": "boolean",
                    "description": "`false` when you disabled it or Navlo did after repeated failures."
                  },
                  {
                    "name": "[].disabledReason",
                    "type": "string",
                    "nullable": true,
                    "description": "Why Navlo disabled it, e.g. \"Automatically disabled after 20 consecutive failed deliveries. Last error: HTTP 503: …\"."
                  },
                  {
                    "name": "[].consecutiveFailures",
                    "type": "integer",
                    "description": "Failed deliveries since the last success; reset by a success and by re-enabling."
                  },
                  {
                    "name": "[].lastSuccessAt",
                    "type": "timestamp",
                    "nullable": true,
                    "description": "Last successful delivery (UTC)."
                  },
                  {
                    "name": "[].lastFailureAt",
                    "type": "timestamp",
                    "nullable": true,
                    "description": "Last failed attempt (UTC)."
                  },
                  {
                    "name": "[].createdAt",
                    "type": "timestamp",
                    "description": "Created (UTC)."
                  }
                ]
              },
              "requestExamples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl \"https://api.navlo.io/v1/webhooks\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\""
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const res = await fetch('https://api.navlo.io/v1/webhooks', {\n  headers: { 'X-API-Key': process.env.NAVLO_API_KEY },\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\nconst webhooks = await res.json()"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.get(\n    \"https://api.navlo.io/v1/webhooks\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\nwebhooks = r.json()"
                }
              ],
              "responseExamples": [
                {
                  "status": 200,
                  "contentType": "application/json",
                  "body": "[\n  {\n    \"id\": \"2b7e9c41-6d3a-4f8e-a5c1-9e0d7b3f2a68\",\n    \"name\": \"ERP shipment updates\",\n    \"url\": \"https://erp.example.com/webhooks/navlo\",\n    \"topics\": [],\n    \"active\": true,\n    \"disabledReason\": null,\n    \"consecutiveFailures\": 0,\n    \"lastSuccessAt\": \"2026-10-22T07:14:44Z\",\n    \"lastFailureAt\": \"2026-10-19T02:10:03Z\",\n    \"createdAt\": \"2026-09-24T07:50:12Z\"\n  }\n]"
                }
              ],
              "errors": [
                {
                  "status": 401,
                  "message": "Invalid or revoked API key",
                  "when": "The X-API-Key header is missing, wrong or revoked."
                },
                {
                  "status": 429,
                  "message": "Rate limit exceeded (60 requests/minute)",
                  "when": "Over the per-key budget; wait Retry-After seconds."
                }
              ],
              "notes": []
            },
            {
              "kind": "endpoint",
              "id": "webhooks-get",
              "method": "GET",
              "path": "/v1/webhooks/{id}",
              "summary": "Retrieve a webhook endpoint",
              "description": [],
              "auth": "apiKey",
              "rateLimit": "general",
              "since": "2026-10-22",
              "pathParams": [
                {
                  "name": "id",
                  "type": "uuid",
                  "required": true,
                  "description": "The endpoint id."
                }
              ],
              "queryParams": [],
              "headers": [],
              "response": {
                "status": 200,
                "contentType": "application/json",
                "fields": [
                  {
                    "name": "id",
                    "type": "uuid",
                    "description": "Endpoint id."
                  },
                  {
                    "name": "name",
                    "type": "string",
                    "description": "Your label for it."
                  },
                  {
                    "name": "url",
                    "type": "string",
                    "description": "Where events are POSTed."
                  },
                  {
                    "name": "topics",
                    "type": "array<string>",
                    "description": "Subscribed topics; `[]` means every topic, including topics added later."
                  },
                  {
                    "name": "active",
                    "type": "boolean",
                    "description": "`false` when you disabled it or Navlo did after repeated failures."
                  },
                  {
                    "name": "disabledReason",
                    "type": "string",
                    "nullable": true,
                    "description": "Why Navlo disabled it, e.g. \"Automatically disabled after 20 consecutive failed deliveries. Last error: HTTP 503: …\"."
                  },
                  {
                    "name": "consecutiveFailures",
                    "type": "integer",
                    "description": "Failed deliveries since the last success; reset by a success and by re-enabling."
                  },
                  {
                    "name": "lastSuccessAt",
                    "type": "timestamp",
                    "nullable": true,
                    "description": "Last successful delivery (UTC)."
                  },
                  {
                    "name": "lastFailureAt",
                    "type": "timestamp",
                    "nullable": true,
                    "description": "Last failed attempt (UTC)."
                  },
                  {
                    "name": "createdAt",
                    "type": "timestamp",
                    "description": "Created (UTC)."
                  }
                ]
              },
              "requestExamples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl \"https://api.navlo.io/v1/webhooks/2b7e9c41-6d3a-4f8e-a5c1-9e0d7b3f2a68\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\""
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const res = await fetch('https://api.navlo.io/v1/webhooks/2b7e9c41-6d3a-4f8e-a5c1-9e0d7b3f2a68', {\n  headers: { 'X-API-Key': process.env.NAVLO_API_KEY },\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\nconst webhook = await res.json()"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.get(\n    \"https://api.navlo.io/v1/webhooks/2b7e9c41-6d3a-4f8e-a5c1-9e0d7b3f2a68\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\nwebhook = r.json()"
                }
              ],
              "responseExamples": [
                {
                  "status": 200,
                  "contentType": "application/json",
                  "body": "{\n  \"id\": \"2b7e9c41-6d3a-4f8e-a5c1-9e0d7b3f2a68\",\n  \"name\": \"ERP shipment updates\",\n  \"url\": \"https://erp.example.com/webhooks/navlo\",\n  \"topics\": [],\n  \"active\": true,\n  \"disabledReason\": null,\n  \"consecutiveFailures\": 0,\n  \"lastSuccessAt\": \"2026-10-22T07:14:44Z\",\n  \"lastFailureAt\": \"2026-10-19T02:10:03Z\",\n  \"createdAt\": \"2026-09-24T07:50:12Z\"\n}"
                }
              ],
              "errors": [
                {
                  "status": 404,
                  "message": "Webhook not found",
                  "when": "Unknown id, or another organization’s endpoint."
                },
                {
                  "status": 401,
                  "message": "Invalid or revoked API key",
                  "when": "The X-API-Key header is missing, wrong or revoked."
                },
                {
                  "status": 429,
                  "message": "Rate limit exceeded (60 requests/minute)",
                  "when": "Over the per-key budget; wait Retry-After seconds."
                }
              ],
              "notes": []
            },
            {
              "kind": "endpoint",
              "id": "webhooks-create",
              "method": "POST",
              "path": "/v1/webhooks",
              "summary": "Create a webhook endpoint",
              "description": [],
              "auth": "apiKey",
              "rateLimit": "general",
              "since": "2026-10-22",
              "pathParams": [],
              "queryParams": [],
              "headers": [],
              "body": {
                "contentType": "application/json",
                "fields": [
                  {
                    "name": "name",
                    "type": "string",
                    "required": true,
                    "description": "Your label, up to 120 characters (longer names are cut)."
                  },
                  {
                    "name": "url",
                    "type": "string",
                    "required": true,
                    "description": "HTTPS URL, without credentials in it."
                  },
                  {
                    "name": "topics",
                    "type": "array<string>",
                    "required": false,
                    "description": "Topics to receive. Omit or send `[]` for every topic, including future ones.",
                    "values": [
                      "shipment.status_changed",
                      "shipment.eta_changed",
                      "shipment.completed",
                      "shipment.risk_raised",
                      "shipment.dnd",
                      "shipment.route_changed",
                      "shipment.discovery_finished"
                    ]
                  }
                ]
              },
              "response": {
                "status": 201,
                "contentType": "application/json",
                "fields": [
                  {
                    "name": "id",
                    "type": "uuid",
                    "description": "Endpoint id."
                  },
                  {
                    "name": "name",
                    "type": "string",
                    "description": "Your label for it."
                  },
                  {
                    "name": "url",
                    "type": "string",
                    "description": "Where events are POSTed."
                  },
                  {
                    "name": "topics",
                    "type": "array<string>",
                    "description": "Subscribed topics; `[]` means every topic, including topics added later."
                  },
                  {
                    "name": "active",
                    "type": "boolean",
                    "description": "`false` when you disabled it or Navlo did after repeated failures."
                  },
                  {
                    "name": "disabledReason",
                    "type": "string",
                    "nullable": true,
                    "description": "Why Navlo disabled it, e.g. \"Automatically disabled after 20 consecutive failed deliveries. Last error: HTTP 503: …\"."
                  },
                  {
                    "name": "consecutiveFailures",
                    "type": "integer",
                    "description": "Failed deliveries since the last success; reset by a success and by re-enabling."
                  },
                  {
                    "name": "lastSuccessAt",
                    "type": "timestamp",
                    "nullable": true,
                    "description": "Last successful delivery (UTC)."
                  },
                  {
                    "name": "lastFailureAt",
                    "type": "timestamp",
                    "nullable": true,
                    "description": "Last failed attempt (UTC)."
                  },
                  {
                    "name": "createdAt",
                    "type": "timestamp",
                    "description": "Created (UTC)."
                  },
                  {
                    "name": "secret",
                    "type": "string",
                    "description": "The signing secret, `whsec_` + 64 hex characters. **Shown only in this response** — store it now."
                  }
                ]
              },
              "requestExamples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl -X POST \"https://api.navlo.io/v1/webhooks\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"name\": \"ERP shipment updates\",\n    \"url\": \"https://erp.example.com/webhooks/navlo\",\n    \"topics\": [\n      \"shipment.status_changed\",\n      \"shipment.eta_changed\"\n    ]\n  }'"
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const res = await fetch('https://api.navlo.io/v1/webhooks', {\n  method: 'POST',\n  headers: {\n    'X-API-Key': process.env.NAVLO_API_KEY,\n    'Content-Type': 'application/json',\n  },\n  body: JSON.stringify({\n    name: 'ERP shipment updates',\n    url: 'https://erp.example.com/webhooks/navlo',\n    topics: ['shipment.status_changed', 'shipment.eta_changed'],\n  }),\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\nconst webhook = await res.json()"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.post(\n    \"https://api.navlo.io/v1/webhooks\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    json={\n        \"name\": \"ERP shipment updates\",\n        \"url\": \"https://erp.example.com/webhooks/navlo\",\n        \"topics\": [\"shipment.status_changed\", \"shipment.eta_changed\"],\n    },\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\nwebhook = r.json()"
                }
              ],
              "responseExamples": [
                {
                  "status": 201,
                  "contentType": "application/json",
                  "body": "{\n  \"id\": \"2b7e9c41-6d3a-4f8e-a5c1-9e0d7b3f2a68\",\n  \"name\": \"ERP shipment updates\",\n  \"url\": \"https://erp.example.com/webhooks/navlo\",\n  \"topics\": [\n    \"shipment.status_changed\",\n    \"shipment.eta_changed\"\n  ],\n  \"active\": true,\n  \"disabledReason\": null,\n  \"consecutiveFailures\": 0,\n  \"lastSuccessAt\": null,\n  \"lastFailureAt\": null,\n  \"createdAt\": \"2026-10-22T08:15:00Z\",\n  \"secret\": \"whsec_7d1f9a3c5e8b2d4f6a0c1e3b5d7f9a2c4e6b8d0f1a3c5e7b9d2f4a6c8e0b1d3f\"\n}"
                }
              ],
              "errors": [
                {
                  "status": 400,
                  "message": "Webhook name is required",
                  "when": "`name` missing or blank."
                },
                {
                  "status": 400,
                  "message": "Webhook URL is required",
                  "when": "`url` missing."
                },
                {
                  "status": 400,
                  "message": "Webhook URL must use https",
                  "when": "An `http://` URL."
                },
                {
                  "status": 400,
                  "message": "Webhook URL is not a valid URL",
                  "when": "Not a URL."
                },
                {
                  "status": 400,
                  "message": "Webhook URL must not embed credentials",
                  "when": "`https://user:pass@…` URLs."
                },
                {
                  "status": 400,
                  "message": "Webhook URL must point to a public internet address",
                  "when": "A private, local or internal host or address."
                },
                {
                  "status": 400,
                  "message": "Unknown webhook topic: shipment.created",
                  "when": "A topic outside the list."
                },
                {
                  "status": 400,
                  "message": "Maximum 10 webhooks per organization",
                  "when": "Already 10 endpoints (disabled ones count)."
                },
                {
                  "status": 403,
                  "message": "Only organization admins can manage webhooks",
                  "when": "The key’s creator is not an organization admin."
                },
                {
                  "status": 400,
                  "message": "Request body is missing or is not valid JSON",
                  "when": "The body could not be parsed."
                },
                {
                  "status": 401,
                  "message": "Invalid or revoked API key",
                  "when": "The X-API-Key header is missing, wrong or revoked."
                },
                {
                  "status": 429,
                  "message": "Rate limit exceeded (60 requests/minute)",
                  "when": "Over the per-key budget; wait Retry-After seconds."
                }
              ],
              "notes": []
            },
            {
              "kind": "endpoint",
              "id": "webhooks-update",
              "method": "PATCH",
              "path": "/v1/webhooks/{id}",
              "summary": "Update a webhook endpoint",
              "description": [
                "Only the keys you send change. Re-enabling (`\"active\": true`) also clears the failure streak and `disabledReason`."
              ],
              "auth": "apiKey",
              "rateLimit": "general",
              "since": "2026-10-22",
              "pathParams": [
                {
                  "name": "id",
                  "type": "uuid",
                  "required": true,
                  "description": "The endpoint id."
                }
              ],
              "queryParams": [],
              "headers": [],
              "body": {
                "contentType": "application/json",
                "fields": [
                  {
                    "name": "name",
                    "type": "string",
                    "required": false,
                    "description": "New label."
                  },
                  {
                    "name": "url",
                    "type": "string",
                    "required": false,
                    "description": "New HTTPS URL."
                  },
                  {
                    "name": "topics",
                    "type": "array<string>",
                    "required": false,
                    "description": "New topic list; `[]` for every topic."
                  },
                  {
                    "name": "active",
                    "type": "boolean",
                    "required": false,
                    "description": "`false` pauses deliveries; `true` resumes them."
                  }
                ]
              },
              "response": {
                "status": 200,
                "contentType": "application/json",
                "fields": [
                  {
                    "name": "id",
                    "type": "uuid",
                    "description": "Endpoint id."
                  },
                  {
                    "name": "name",
                    "type": "string",
                    "description": "Your label for it."
                  },
                  {
                    "name": "url",
                    "type": "string",
                    "description": "Where events are POSTed."
                  },
                  {
                    "name": "topics",
                    "type": "array<string>",
                    "description": "Subscribed topics; `[]` means every topic, including topics added later."
                  },
                  {
                    "name": "active",
                    "type": "boolean",
                    "description": "`false` when you disabled it or Navlo did after repeated failures."
                  },
                  {
                    "name": "disabledReason",
                    "type": "string",
                    "nullable": true,
                    "description": "Why Navlo disabled it, e.g. \"Automatically disabled after 20 consecutive failed deliveries. Last error: HTTP 503: …\"."
                  },
                  {
                    "name": "consecutiveFailures",
                    "type": "integer",
                    "description": "Failed deliveries since the last success; reset by a success and by re-enabling."
                  },
                  {
                    "name": "lastSuccessAt",
                    "type": "timestamp",
                    "nullable": true,
                    "description": "Last successful delivery (UTC)."
                  },
                  {
                    "name": "lastFailureAt",
                    "type": "timestamp",
                    "nullable": true,
                    "description": "Last failed attempt (UTC)."
                  },
                  {
                    "name": "createdAt",
                    "type": "timestamp",
                    "description": "Created (UTC)."
                  }
                ]
              },
              "requestExamples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl -X PATCH \"https://api.navlo.io/v1/webhooks/2b7e9c41-6d3a-4f8e-a5c1-9e0d7b3f2a68\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"active\": true\n  }'"
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const res = await fetch('https://api.navlo.io/v1/webhooks/2b7e9c41-6d3a-4f8e-a5c1-9e0d7b3f2a68', {\n  method: 'PATCH',\n  headers: {\n    'X-API-Key': process.env.NAVLO_API_KEY,\n    'Content-Type': 'application/json',\n  },\n  body: JSON.stringify({ active: true }),\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\nconst webhook = await res.json()"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.patch(\n    \"https://api.navlo.io/v1/webhooks/2b7e9c41-6d3a-4f8e-a5c1-9e0d7b3f2a68\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    json={\"active\": True},\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\nwebhook = r.json()"
                }
              ],
              "responseExamples": [
                {
                  "status": 200,
                  "contentType": "application/json",
                  "body": "{\n  \"id\": \"2b7e9c41-6d3a-4f8e-a5c1-9e0d7b3f2a68\",\n  \"name\": \"ERP shipment updates\",\n  \"url\": \"https://erp.example.com/webhooks/navlo\",\n  \"topics\": [],\n  \"active\": true,\n  \"disabledReason\": null,\n  \"consecutiveFailures\": 0,\n  \"lastSuccessAt\": \"2026-10-22T07:14:44Z\",\n  \"lastFailureAt\": \"2026-10-19T02:10:03Z\",\n  \"createdAt\": \"2026-09-24T07:50:12Z\"\n}"
                }
              ],
              "errors": [
                {
                  "status": 404,
                  "message": "Webhook not found",
                  "when": "Unknown id, or another organization’s endpoint."
                },
                {
                  "status": 400,
                  "message": "Webhook URL must use https",
                  "when": "An `http://` URL."
                },
                {
                  "status": 400,
                  "message": "Webhook URL is not a valid URL",
                  "when": "Not a URL."
                },
                {
                  "status": 400,
                  "message": "Webhook URL must not embed credentials",
                  "when": "`https://user:pass@…` URLs."
                },
                {
                  "status": 400,
                  "message": "Webhook URL must point to a public internet address",
                  "when": "A private, local or internal host or address."
                },
                {
                  "status": 400,
                  "message": "Unknown webhook topic: shipment.created",
                  "when": "A topic outside the list."
                },
                {
                  "status": 403,
                  "message": "Only organization admins can manage webhooks",
                  "when": "The key’s creator is not an organization admin."
                },
                {
                  "status": 400,
                  "message": "Request body is missing or is not valid JSON",
                  "when": "The body could not be parsed."
                },
                {
                  "status": 401,
                  "message": "Invalid or revoked API key",
                  "when": "The X-API-Key header is missing, wrong or revoked."
                },
                {
                  "status": 429,
                  "message": "Rate limit exceeded (60 requests/minute)",
                  "when": "Over the per-key budget; wait Retry-After seconds."
                }
              ],
              "notes": []
            },
            {
              "kind": "endpoint",
              "id": "webhooks-delete",
              "method": "DELETE",
              "path": "/v1/webhooks/{id}",
              "summary": "Delete a webhook endpoint",
              "description": [
                "Stops deliveries at once, including queued retries."
              ],
              "auth": "apiKey",
              "rateLimit": "general",
              "since": "2026-10-22",
              "pathParams": [
                {
                  "name": "id",
                  "type": "uuid",
                  "required": true,
                  "description": "The endpoint id."
                }
              ],
              "queryParams": [],
              "headers": [],
              "response": {
                "status": 204,
                "contentType": "",
                "description": "No body.",
                "fields": []
              },
              "requestExamples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl -X DELETE \"https://api.navlo.io/v1/webhooks/2b7e9c41-6d3a-4f8e-a5c1-9e0d7b3f2a68\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\""
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const res = await fetch('https://api.navlo.io/v1/webhooks/2b7e9c41-6d3a-4f8e-a5c1-9e0d7b3f2a68', {\n  method: 'DELETE',\n  headers: { 'X-API-Key': process.env.NAVLO_API_KEY },\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\n// 204 No Content: nothing to parse"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.delete(\n    \"https://api.navlo.io/v1/webhooks/2b7e9c41-6d3a-4f8e-a5c1-9e0d7b3f2a68\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\n# 204 No Content: nothing to parse"
                }
              ],
              "responseExamples": [
                {
                  "status": 204,
                  "contentType": "",
                  "body": ""
                }
              ],
              "errors": [
                {
                  "status": 404,
                  "message": "Webhook not found",
                  "when": "Unknown id, or another organization’s endpoint."
                },
                {
                  "status": 403,
                  "message": "Only organization admins can manage webhooks",
                  "when": "The key’s creator is not an organization admin."
                },
                {
                  "status": 401,
                  "message": "Invalid or revoked API key",
                  "when": "The X-API-Key header is missing, wrong or revoked."
                },
                {
                  "status": 429,
                  "message": "Rate limit exceeded (60 requests/minute)",
                  "when": "Over the per-key budget; wait Retry-After seconds."
                }
              ],
              "notes": []
            },
            {
              "kind": "endpoint",
              "id": "webhooks-rotate-secret",
              "method": "POST",
              "path": "/v1/webhooks/{id}/rotate-secret",
              "summary": "Rotate the signing secret",
              "description": [
                "Issues a new secret and invalidates the old one immediately — queued retries are signed with the new one. Deploy it to your receiver promptly; deliveries signed with the new secret fail verification until you do, and are retried."
              ],
              "auth": "apiKey",
              "rateLimit": "general",
              "since": "2026-10-22",
              "pathParams": [
                {
                  "name": "id",
                  "type": "uuid",
                  "required": true,
                  "description": "The endpoint id."
                }
              ],
              "queryParams": [],
              "headers": [],
              "response": {
                "status": 200,
                "contentType": "application/json",
                "fields": [
                  {
                    "name": "secret",
                    "type": "string",
                    "description": "The new secret, shown only here."
                  }
                ]
              },
              "requestExamples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl -X POST \"https://api.navlo.io/v1/webhooks/2b7e9c41-6d3a-4f8e-a5c1-9e0d7b3f2a68/rotate-secret\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\""
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const res = await fetch('https://api.navlo.io/v1/webhooks/2b7e9c41-6d3a-4f8e-a5c1-9e0d7b3f2a68/rotate-secret', {\n  method: 'POST',\n  headers: { 'X-API-Key': process.env.NAVLO_API_KEY },\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\nconst rotated = await res.json()"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.post(\n    \"https://api.navlo.io/v1/webhooks/2b7e9c41-6d3a-4f8e-a5c1-9e0d7b3f2a68/rotate-secret\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\nrotated = r.json()"
                }
              ],
              "responseExamples": [
                {
                  "status": 200,
                  "contentType": "application/json",
                  "body": "{\n  \"secret\": \"whsec_3a9e1c7f5b2d8e4a6c0f9b3d1e7a5c2f8b4d6e0a9c3f7b1d5e8a2c6f0b4d9e3a\"\n}"
                }
              ],
              "errors": [
                {
                  "status": 404,
                  "message": "Webhook not found",
                  "when": "Unknown id, or another organization’s endpoint."
                },
                {
                  "status": 403,
                  "message": "Only organization admins can manage webhooks",
                  "when": "The key’s creator is not an organization admin."
                },
                {
                  "status": 401,
                  "message": "Invalid or revoked API key",
                  "when": "The X-API-Key header is missing, wrong or revoked."
                },
                {
                  "status": 429,
                  "message": "Rate limit exceeded (60 requests/minute)",
                  "when": "Over the per-key budget; wait Retry-After seconds."
                }
              ],
              "notes": []
            },
            {
              "kind": "endpoint",
              "id": "webhooks-deliveries",
              "method": "GET",
              "path": "/v1/webhooks/{id}/deliveries",
              "summary": "List deliveries",
              "description": [
                "Every event sent to the endpoint in the last 30 days, newest first, with the outcome of its latest attempt."
              ],
              "auth": "apiKey",
              "rateLimit": "general",
              "since": "2026-10-22",
              "pathParams": [
                {
                  "name": "id",
                  "type": "uuid",
                  "required": true,
                  "description": "The endpoint id."
                }
              ],
              "queryParams": [
                {
                  "name": "page",
                  "type": "integer",
                  "required": false,
                  "description": "Zero-based page index.",
                  "defaultValue": "0"
                },
                {
                  "name": "size",
                  "type": "integer",
                  "required": false,
                  "description": "Page size, 1–100.",
                  "defaultValue": "20"
                }
              ],
              "headers": [],
              "response": {
                "status": 200,
                "contentType": "application/json",
                "fields": [
                  {
                    "name": "page",
                    "type": "integer",
                    "description": "Page index."
                  },
                  {
                    "name": "size",
                    "type": "integer",
                    "description": "Page size."
                  },
                  {
                    "name": "totalElements",
                    "type": "integer",
                    "description": "Deliveries in the last 30 days."
                  },
                  {
                    "name": "totalPages",
                    "type": "integer",
                    "description": "Pages at this size."
                  },
                  {
                    "name": "deliveries",
                    "type": "array<object>",
                    "description": "The deliveries."
                  },
                  {
                    "name": "deliveries[].id",
                    "type": "uuid",
                    "description": "Delivery id."
                  },
                  {
                    "name": "deliveries[].eventId",
                    "type": "uuid",
                    "description": "The event id (`X-Navlo-Event-Id`)."
                  },
                  {
                    "name": "deliveries[].topic",
                    "type": "string",
                    "description": "The topic."
                  },
                  {
                    "name": "deliveries[].shipmentId",
                    "type": "uuid",
                    "nullable": true,
                    "description": "The shipment the event is about; null for a test event."
                  },
                  {
                    "name": "deliveries[].status",
                    "type": "enum",
                    "description": "`pending` — not tried yet. `retrying` — failed, will retry. `delivered`. `failed` — gave up after 5 attempts, or the endpoint was switched off.",
                    "values": [
                      "pending",
                      "retrying",
                      "delivered",
                      "failed"
                    ]
                  },
                  {
                    "name": "deliveries[].attempts",
                    "type": "integer",
                    "description": "Attempts so far (1–5)."
                  },
                  {
                    "name": "deliveries[].responseStatus",
                    "type": "integer",
                    "nullable": true,
                    "description": "Your endpoint’s HTTP status on the last attempt."
                  },
                  {
                    "name": "deliveries[].error",
                    "type": "string",
                    "nullable": true,
                    "description": "What went wrong: `HTTP 503: <first 500 characters of your response>` or the network error."
                  },
                  {
                    "name": "deliveries[].createdAt",
                    "type": "timestamp",
                    "description": "When the event was queued (UTC)."
                  },
                  {
                    "name": "deliveries[].lastAttemptAt",
                    "type": "timestamp",
                    "nullable": true,
                    "description": "When Navlo last tried it, or gave up on it (UTC); null before the first attempt."
                  }
                ]
              },
              "requestExamples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl \"https://api.navlo.io/v1/webhooks/2b7e9c41-6d3a-4f8e-a5c1-9e0d7b3f2a68/deliveries?size=2\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\""
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const params = new URLSearchParams({ size: '2' })\n\nconst res = await fetch(`https://api.navlo.io/v1/webhooks/2b7e9c41-6d3a-4f8e-a5c1-9e0d7b3f2a68/deliveries?${params}`, {\n  headers: { 'X-API-Key': process.env.NAVLO_API_KEY },\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\nconst page = await res.json()"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.get(\n    \"https://api.navlo.io/v1/webhooks/2b7e9c41-6d3a-4f8e-a5c1-9e0d7b3f2a68/deliveries\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    params={\"size\": \"2\"},\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\npage = r.json()"
                }
              ],
              "responseExamples": [
                {
                  "status": 200,
                  "contentType": "application/json",
                  "body": "{\n  \"page\": 0,\n  \"size\": 2,\n  \"totalElements\": 418,\n  \"totalPages\": 209,\n  \"deliveries\": [\n    {\n      \"id\": \"0e6a3d9f-8b2c-4a71-9f5e-c4d1b7a3e820\",\n      \"eventId\": \"0d6b3e9f-7a1c-4f25-8b4d-e2c9a5f7b130\",\n      \"topic\": \"shipment.risk_raised\",\n      \"shipmentId\": \"6b1f0c9a-4d2e-4f7b-9a3c-8e5d21f0a4b7\",\n      \"status\": \"delivered\",\n      \"attempts\": 1,\n      \"responseStatus\": 200,\n      \"error\": null,\n      \"createdAt\": \"2026-10-21T09:26:58Z\",\n      \"lastAttemptAt\": \"2026-10-21T06:01:02Z\"\n    },\n    {\n      \"id\": \"b2f8d4a6-3c1e-4b97-8d05-e6a2c9f1b743\",\n      \"eventId\": \"9b4e7a2d-6c8f-4d13-a0e5-1f3c8b6d9a27\",\n      \"topic\": \"shipment.dnd\",\n      \"shipmentId\": \"a7d3e9b1-5c2f-4e84-b6a0-3f9c1d7e2b58\",\n      \"status\": \"delivered\",\n      \"attempts\": 2,\n      \"responseStatus\": 200,\n      \"error\": null,\n      \"createdAt\": \"2026-10-19T15:03:12Z\",\n      \"lastAttemptAt\": \"2026-10-19T06:01:31Z\"\n    }\n  ]\n}"
                }
              ],
              "errors": [
                {
                  "status": 404,
                  "message": "Webhook not found",
                  "when": "Unknown id, or another organization’s endpoint."
                },
                {
                  "status": 401,
                  "message": "Invalid or revoked API key",
                  "when": "The X-API-Key header is missing, wrong or revoked."
                },
                {
                  "status": 429,
                  "message": "Rate limit exceeded (60 requests/minute)",
                  "when": "Over the per-key budget; wait Retry-After seconds."
                }
              ],
              "notes": []
            },
            {
              "kind": "endpoint",
              "id": "webhooks-send-test",
              "method": "POST",
              "path": "/v1/webhooks/{id}/test",
              "summary": "Send a test event",
              "description": [
                "Queues a sample event of the topic you choose to this endpoint, whatever its topics. It arrives within a minute and appears in the deliveries list; a failed test delivery counts toward the failure streak like any other. The body is optional."
              ],
              "auth": "apiKey",
              "rateLimit": "general",
              "since": "2026-10-22",
              "pathParams": [
                {
                  "name": "id",
                  "type": "uuid",
                  "required": true,
                  "description": "The endpoint id."
                }
              ],
              "queryParams": [],
              "headers": [],
              "body": {
                "contentType": "application/json",
                "fields": [
                  {
                    "name": "topic",
                    "type": "string",
                    "required": false,
                    "description": "The sample’s topic.",
                    "values": [
                      "shipment.status_changed",
                      "shipment.eta_changed",
                      "shipment.completed",
                      "shipment.risk_raised",
                      "shipment.dnd",
                      "shipment.route_changed",
                      "shipment.discovery_finished"
                    ],
                    "defaultValue": "shipment.status_changed"
                  }
                ]
              },
              "response": {
                "status": 202,
                "contentType": "application/json",
                "fields": [
                  {
                    "name": "eventId",
                    "type": "uuid",
                    "description": "The test event’s id — the payload `id` and `X-Navlo-Event-Id`, and the `eventId` of its delivery."
                  },
                  {
                    "name": "topic",
                    "type": "string",
                    "description": "The topic the sample was built for."
                  }
                ]
              },
              "requestExamples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl -X POST \"https://api.navlo.io/v1/webhooks/2b7e9c41-6d3a-4f8e-a5c1-9e0d7b3f2a68/test\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"topic\": \"shipment.eta_changed\"\n  }'"
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const res = await fetch('https://api.navlo.io/v1/webhooks/2b7e9c41-6d3a-4f8e-a5c1-9e0d7b3f2a68/test', {\n  method: 'POST',\n  headers: {\n    'X-API-Key': process.env.NAVLO_API_KEY,\n    'Content-Type': 'application/json',\n  },\n  body: JSON.stringify({ topic: 'shipment.eta_changed' }),\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\nconst test = await res.json()"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.post(\n    \"https://api.navlo.io/v1/webhooks/2b7e9c41-6d3a-4f8e-a5c1-9e0d7b3f2a68/test\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    json={\"topic\": \"shipment.eta_changed\"},\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\ntest = r.json()"
                }
              ],
              "responseExamples": [
                {
                  "status": 202,
                  "contentType": "application/json",
                  "body": "{\n  \"eventId\": \"33729788-59e4-4e9e-8e11-ef83b47ce78b\",\n  \"topic\": \"shipment.eta_changed\"\n}"
                }
              ],
              "errors": [
                {
                  "status": 404,
                  "message": "Webhook not found",
                  "when": "Unknown id, or another organization’s endpoint."
                },
                {
                  "status": 409,
                  "message": "Webhook endpoint is disabled",
                  "when": "The endpoint is switched off — re-enable it first."
                },
                {
                  "status": 400,
                  "message": "Unknown webhook topic: shipment.created",
                  "when": "A topic outside the list."
                },
                {
                  "status": 403,
                  "message": "Only organization admins can manage webhooks",
                  "when": "The key’s creator is not an organization admin."
                },
                {
                  "status": 401,
                  "message": "Invalid or revoked API key",
                  "when": "The X-API-Key header is missing, wrong or revoked."
                },
                {
                  "status": 429,
                  "message": "Rate limit exceeded (60 requests/minute)",
                  "when": "Over the per-key budget; wait Retry-After seconds."
                }
              ],
              "notes": []
            },
            {
              "kind": "endpoint",
              "id": "webhooks-topics-list",
              "method": "GET",
              "path": "/v1/webhooks/topics",
              "summary": "List topics",
              "description": [],
              "auth": "apiKey",
              "rateLimit": "general",
              "since": "2026-10-22",
              "pathParams": [],
              "queryParams": [],
              "headers": [],
              "response": {
                "status": 200,
                "contentType": "application/json",
                "description": "Every topic you can subscribe to.",
                "fields": [
                  {
                    "name": "[].topic",
                    "type": "string",
                    "description": "Topic name."
                  },
                  {
                    "name": "[].description",
                    "type": "string",
                    "description": "When it fires."
                  }
                ]
              },
              "requestExamples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl \"https://api.navlo.io/v1/webhooks/topics\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\""
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const res = await fetch('https://api.navlo.io/v1/webhooks/topics', {\n  headers: { 'X-API-Key': process.env.NAVLO_API_KEY },\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\nconst topics = await res.json()"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.get(\n    \"https://api.navlo.io/v1/webhooks/topics\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\ntopics = r.json()"
                }
              ],
              "responseExamples": [
                {
                  "status": 200,
                  "contentType": "application/json",
                  "body": "[\n  {\n    \"topic\": \"shipment.status_changed\",\n    \"description\": \"The shipment reached a new status (loaded, departed, arrived, delivered...), was seen leaving or reaching port on the vessel's live position, or is approaching its destination.\"\n  },\n  {\n    \"topic\": \"shipment.eta_changed\",\n    \"description\": \"The carrier's estimated arrival moved. Carries the previous and the new ETA.\"\n  },\n  {\n    \"topic\": \"shipment.completed\",\n    \"description\": \"The shipment finished: every container completed its journey, or the air cargo was delivered.\"\n  },\n  {\n    \"topic\": \"shipment.risk_raised\",\n    \"description\": \"A risk was raised: a container idle at a port, a rolled container, a transshipment delay, cargo not loaded or a booking the airline cancelled.\"\n  },\n  {\n    \"topic\": \"shipment.dnd\",\n    \"description\": \"Demurrage, detention and storage: free time about to end, charges started, empty return due or done, air cargo near or past its free storage.\"\n  },\n  {\n    \"topic\": \"shipment.route_changed\",\n    \"description\": \"The carrier changed the port of discharge. Carries the previous and the new destination.\"\n  },\n  {\n    \"topic\": \"shipment.discovery_finished\",\n    \"description\": \"The search for a new shipment ended: the carrier returned it (RESOLVED), or Navlo found no carrier data and stopped searching on its own (NOT_FOUND).\"\n  }\n]"
                }
              ],
              "errors": [
                {
                  "status": 401,
                  "message": "Invalid or revoked API key",
                  "when": "The X-API-Key header is missing, wrong or revoked."
                },
                {
                  "status": 429,
                  "message": "Rate limit exceeded (60 requests/minute)",
                  "when": "Over the per-key budget; wait Retry-After seconds."
                }
              ],
              "notes": []
            }
          ]
        },
        {
          "id": "embed",
          "title": "Embed",
          "summary": "Live shipment tracking on your own website — a ready-made widget, or the endpoint behind it for your own design.",
          "blocks": [
            {
              "kind": "prose",
              "text": "Let your customers track their shipments on your website. They type a container, B/L, booking or air waybill number and see the live status — only for shipments your organization already tracks. The embed shows carrier facts only (milestones, vessel, ports, dates): never your customers, tags, notes, risk or costs, and it never starts a shipment or spends credits."
            },
            {
              "kind": "heading",
              "id": "embed-widget",
              "title": "The tracking widget"
            },
            {
              "kind": "list",
              "ordered": true,
              "items": [
                "Create an **embed key** under **Settings → API & Embedding → New key**, scope **Embed widget**. It starts with `nvle_`.",
                "Optionally pin it to your website’s origins, e.g. `https://www.example.com, https://portal.example.com`.",
                "Paste the iframe into your page."
              ]
            },
            {
              "kind": "code",
              "samples": [
                {
                  "lang": "html",
                  "label": "HTML",
                  "code": "<iframe\n  src=\"https://app.navlo.io/embed?key=nvle_your_embed_key\"\n  style=\"width:100%;height:640px;border:0;border-radius:12px\"\n  title=\"Shipment tracking\"\n  loading=\"lazy\"></iframe>"
                }
              ]
            },
            {
              "kind": "prose",
              "text": "The widget is responsive and needs about 640 px of height to show the map and timeline without scrolling."
            },
            {
              "kind": "heading",
              "id": "embed-origins",
              "title": "Origin pinning"
            },
            {
              "kind": "prose",
              "text": "An embed key is meant to be public — it sits in your page’s HTML. Pinning it to your origins stops other sites from embedding it: the widget reports the page it is embedded in, and a request from any other origin is refused with `403`. With no origins on the key, the widget works on any site."
            },
            {
              "kind": "list",
              "ordered": false,
              "items": [
                "Origins are scheme + host (+ port): `https://www.example.com` — no paths, no trailing slash needed.",
                "The widget learns your page’s origin from the browser’s referrer. Don’t set `referrerpolicy=\"no-referrer\"` on the iframe when the key is pinned, or every lookup is refused.",
                "Revoke the key in Settings to switch the widget off immediately."
              ]
            },
            {
              "kind": "heading",
              "id": "embed-custom",
              "title": "Building your own tracking box"
            },
            {
              "kind": "prose",
              "text": "Prefer your own design? Call the endpoint the widget uses. Call it **from your server**: `api.navlo.io` does not accept cross-origin browser requests from your domain, and your server can shape the answer for your page."
            },
            {
              "kind": "endpoint",
              "id": "embed-resolve",
              "method": "GET",
              "path": "/api/embed/resolve",
              "summary": "Look up a tracked shipment by number",
              "description": [
                "Finds the shipment your organization tracks under exactly the number typed — container, Master B/L, booking or Master AWB — and returns the public, read-only view your share links show. Unknown numbers are a plain `404`; nothing is ever created."
              ],
              "auth": "embedKey",
              "rateLimit": "none",
              "pathParams": [],
              "queryParams": [
                {
                  "name": "number",
                  "type": "string",
                  "required": true,
                  "description": "The number as your customer typed it. Matched exactly against your tracked shipments (case-insensitive)."
                },
                {
                  "name": "parentOrigin",
                  "type": "string",
                  "required": false,
                  "description": "The origin of the page the lookup is for, e.g. `https://www.example.com`. Required — and checked — when the key pins origins."
                },
                {
                  "name": "key",
                  "type": "string",
                  "required": false,
                  "description": "The embed key, when you can’t send the `X-Embed-Key` header."
                }
              ],
              "headers": [
                {
                  "name": "X-Embed-Key",
                  "type": "string",
                  "required": true,
                  "description": "Your embed key (`nvle_…`). Or pass it as the `key` query parameter."
                }
              ],
              "response": {
                "status": 200,
                "contentType": "application/json",
                "fields": [
                  {
                    "name": "trackingIdentifier",
                    "type": "string",
                    "description": "The tracked number the customer’s input matched."
                  },
                  {
                    "name": "trackingMode",
                    "type": "enum",
                    "description": "Branch on it: `OCEAN` fills `containers`, `AIR` fills `airShipments`.",
                    "values": [
                      "OCEAN",
                      "AIR"
                    ]
                  },
                  {
                    "name": "status",
                    "type": "enum",
                    "description": "Lifecycle status. `tracking` — air only: the waybill was accepted and Navlo is fetching the airline's first data. It becomes `active` when that data arrives (or `discovering` if no airline has it yet). A new air shipment's create response usually says `tracking`. List, export and report filters treat it as `active`.",
                    "values": [
                      "discovering",
                      "resolving",
                      "active",
                      "tracking",
                      "completed",
                      "stopped"
                    ]
                  },
                  {
                    "name": "containers",
                    "type": "array<object>",
                    "description": "OCEAN: one per container. The fields you need for a tracking box:"
                  },
                  {
                    "name": "containers[].id",
                    "type": "string",
                    "description": "The container’s place in this answer (`c1`, `c2`, …); timeline rows extend it (`c1-e1`). Use it to key rows, not to store."
                  },
                  {
                    "name": "containers[].containerNumber",
                    "type": "string",
                    "description": "Container number."
                  },
                  {
                    "name": "containers[].courierName",
                    "type": "string",
                    "description": "Carrier name (`courierLogoUrl` has its logo)."
                  },
                  {
                    "name": "containers[].statusListingName",
                    "type": "string",
                    "nullable": true,
                    "description": "The status headline Navlo shows — \"In Transit\", \"Discharged\", \"Completed\". Use this as the big label."
                  },
                  {
                    "name": "containers[].navloStatusName",
                    "type": "string",
                    "nullable": true,
                    "description": "The latest milestone, e.g. \"Departed\"."
                  },
                  {
                    "name": "containers[].navloStatusCategory",
                    "type": "enum",
                    "nullable": true,
                    "description": "Phase of the journey.",
                    "values": [
                      "PRE_SHIPMENT",
                      "ORIGIN",
                      "TRANSIT",
                      "DESTINATION",
                      "COMPLETED"
                    ]
                  },
                  {
                    "name": "containers[].originPortName",
                    "type": "string",
                    "nullable": true,
                    "description": "Port of loading (`originPortCode` = UN/LOCODE, `originCountryCode` = ISO alpha-2, `originPortCoordinates` = `{ lat, lng }`)."
                  },
                  {
                    "name": "containers[].destinationPortName",
                    "type": "string",
                    "nullable": true,
                    "description": "Port of discharge (`destinationPortCode`, `destinationCountryCode`, `destinationPortCoordinates` likewise)."
                  },
                  {
                    "name": "containers[].estimatedDeparture",
                    "type": "timestamp",
                    "nullable": true,
                    "description": "ETD — carrier local time; `actualDeparture` = ATD."
                  },
                  {
                    "name": "containers[].estimatedArrival",
                    "type": "timestamp",
                    "nullable": true,
                    "description": "ETA — carrier local time; `actualArrival` = ATA. Display as-is."
                  },
                  {
                    "name": "containers[].estimatedArrivalUtc",
                    "type": "timestamp",
                    "nullable": true,
                    "description": "The same times as true UTC instants, for arithmetic only (transit days). Never display these."
                  },
                  {
                    "name": "containers[].currentVesselName",
                    "type": "string",
                    "nullable": true,
                    "description": "Vessel now (`currentVoyageNumber`, `currentVesselImo`)."
                  },
                  {
                    "name": "containers[].aboardVessel",
                    "type": "boolean",
                    "description": "`true` while the container is verifiably on the vessel."
                  },
                  {
                    "name": "containers[].nextPlannedVessel",
                    "type": "object",
                    "nullable": true,
                    "description": "The next connection: `vesselName`, `voyageNumber`, `plannedAt`, `portName`, `portCode`."
                  },
                  {
                    "name": "containers[].activities",
                    "type": "array<object>",
                    "description": "The timeline rows. Sort by `activityTimestamp` for a strict chronology."
                  },
                  {
                    "name": "containers[].activities[].navloStatusName",
                    "type": "string",
                    "nullable": true,
                    "description": "Milestone, e.g. \"Loaded\" (`navloStatusCode` = `LOADED`)."
                  },
                  {
                    "name": "containers[].activities[].courierStatus",
                    "type": "string",
                    "description": "The carrier’s own wording."
                  },
                  {
                    "name": "containers[].activities[].location",
                    "type": "string",
                    "nullable": true,
                    "description": "Place (`locationCode`, `locationCountryCode`, `terminalName`)."
                  },
                  {
                    "name": "containers[].activities[].activityTimestamp",
                    "type": "timestamp",
                    "nullable": true,
                    "description": "When — carrier local time."
                  },
                  {
                    "name": "containers[].activities[].eventType",
                    "type": "enum",
                    "nullable": true,
                    "description": "Happened, or still planned.",
                    "values": [
                      "ACTUAL",
                      "EXPECTED"
                    ]
                  },
                  {
                    "name": "containers[].activities[].vesselName",
                    "type": "string",
                    "nullable": true,
                    "description": "Vessel for the event (`voyageNumber`)."
                  },
                  {
                    "name": "containers[].activities[].detectionSource",
                    "type": "string",
                    "nullable": true,
                    "description": "`AIS` when Navlo detected the milestone from live vessel tracking before the carrier reported it."
                  },
                  {
                    "name": "airShipments",
                    "type": "array<object>",
                    "description": "AIR: one per waybill — `awbNumber`, `courierName`, `originAirportCode`/`Name`, `destinationAirportCode`/`Name`, `statusListingCode`, `estimatedDeparture`, `actualDeparture`, `estimatedArrival`, `actualArrival`, `piecesCount`, `piecesWeight`, `milestones[]`, `flightSegments[]`."
                  },
                  {
                    "name": "vesselPosition",
                    "type": "object",
                    "nullable": true,
                    "description": "Where the vessel was last seen, only while the container is sailing on it: `vesselName`, `latitude`, `longitude`, `heading`, `source` (`LIVE` or `STALE`), `reportedAt`, `ageHours`. Show \"last seen N hours ago\" for `STALE`."
                  }
                ]
              },
              "requestExamples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl \"https://api.navlo.io/api/embed/resolve?number=MEDU1234562&parentOrigin=https:%2F%2Fwww.example.com\" \\\n  -H \"X-Embed-Key: $NAVLO_EMBED_KEY\""
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const params = new URLSearchParams({\n  number: 'MEDU1234562',\n  parentOrigin: 'https://www.example.com',\n})\n\nconst res = await fetch(`https://api.navlo.io/api/embed/resolve?${params}`, {\n  headers: { 'X-Embed-Key': process.env.NAVLO_EMBED_KEY },\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}`) // embed errors have an empty body\nconst shipment = await res.json()"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.get(\n    \"https://api.navlo.io/api/embed/resolve\",\n    headers={\"X-Embed-Key\": os.environ[\"NAVLO_EMBED_KEY\"]},\n    params={\n        \"number\": \"MEDU1234562\",\n        \"parentOrigin\": \"https://www.example.com\",\n    },\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}\")  # embed errors have an empty body\nshipment = r.json()"
                },
                {
                  "lang": "node",
                  "label": "Node.js (proxy)",
                  "code": "// Your server: GET /track?number=… → Navlo, so the browser never calls api.navlo.io directly.\nimport express from 'express'\n\nconst app = express()\n\napp.get('/track', async (req, res) => {\n  const params = new URLSearchParams({ number: String(req.query.number ?? '') })\n  const navlo = await fetch(`https://api.navlo.io/api/embed/resolve?${params}`, {\n    headers: { 'X-Embed-Key': process.env.NAVLO_EMBED_KEY },\n  })\n  if (navlo.status === 404) return res.status(404).json({ message: 'No tracked shipment matches that number.' })\n  if (navlo.status === 429) {\n    res.set('Retry-After', navlo.headers.get('retry-after') ?? '60')\n    return res.status(429).json({ message: 'Too many lookups right now. Try again in a minute.' })\n  }\n  if (!navlo.ok) return res.status(502).json({ message: 'Tracking is unavailable right now.' })\n\n  const shipment = await navlo.json()\n  const c = shipment.containers[0]\n  res.json({\n    number: shipment.trackingIdentifier,\n    status: c?.statusListingName ?? shipment.status,\n    from: c?.originPortName,\n    to: c?.destinationPortName,\n    eta: c?.estimatedArrival, // carrier local time — display as-is\n    timeline: (c?.activities ?? []).map((a) => ({ what: a.navloStatusName ?? a.courierStatus, where: a.location, when: a.activityTimestamp, planned: a.eventType === 'EXPECTED' })),\n  })\n})\n\napp.listen(3000)"
                }
              ],
              "responseExamples": [
                {
                  "status": 200,
                  "contentType": "application/json",
                  "body": "{\n  \"trackingIdentifier\": \"MEDU1234562\",\n  \"trackingMode\": \"OCEAN\",\n  \"status\": \"active\",\n  \"containers\": [\n    {\n      \"id\": \"c1\",\n      \"containerNumber\": \"MEDU1234562\",\n      \"courierCode\": \"MSC\",\n      \"courierName\": \"MSC\",\n      \"courierLogoUrl\": \"https://cdn.example.com/couriers/msc.png\",\n      \"navloStatusCode\": \"DEPARTED\",\n      \"navloStatusName\": \"Departed\",\n      \"navloStatusCategory\": \"TRANSIT\",\n      \"statusListingCode\": \"IN_TRANSIT\",\n      \"statusListingName\": \"In Transit\",\n      \"containerType\": \"40HC\",\n      \"containerIsoCode\": \"45G1\",\n      \"originPortCode\": \"CNSHA\",\n      \"originPortName\": \"Shanghai\",\n      \"originPortCoordinates\": {\n        \"lat\": 31.2304,\n        \"lng\": 121.4737\n      },\n      \"originTerminal\": \"Yangshan Deep Water Port Phase IV\",\n      \"destinationPortCode\": \"TRAMR\",\n      \"destinationPortName\": \"Ambarli\",\n      \"destinationPortCoordinates\": {\n        \"lat\": 40.9667,\n        \"lng\": 28.6833\n      },\n      \"destinationTerminal\": \"Marport Ambarli\",\n      \"currentLocation\": \"Shanghai\",\n      \"currentLocationCode\": \"CNSHA\",\n      \"currentVesselName\": \"MSC MARTINA\",\n      \"currentVoyageNumber\": \"438W\",\n      \"currentVesselImo\": \"9461805\",\n      \"originCountryCode\": \"CN\",\n      \"destinationCountryCode\": \"TR\",\n      \"demurrageFreeUntil\": null,\n      \"carrierFreeTimeDays\": 7,\n      \"carrierFreeTimeBasis\": \"Calendar Days\",\n      \"estimatedArrival\": \"2026-10-30T06:00:00Z\",\n      \"actualArrival\": null,\n      \"estimatedDeparture\": \"2026-09-26T22:00:00Z\",\n      \"actualDeparture\": \"2026-09-27T03:40:00Z\",\n      \"estimatedDepartureUtc\": \"2026-09-26T14:00:00Z\",\n      \"actualDepartureUtc\": \"2026-09-26T19:40:00Z\",\n      \"estimatedArrivalUtc\": \"2026-10-30T03:00:00Z\",\n      \"actualArrivalUtc\": null,\n      \"estimatedDelivery\": null,\n      \"actualDelivery\": null,\n      \"completedAt\": null,\n      \"co2eKg\": 1856.4,\n      \"co2Source\": \"GLEC\",\n      \"activities\": [\n        {\n          \"id\": \"c1-e1\",\n          \"navloStatusCode\": \"GATE_IN\",\n          \"navloStatusName\": \"Gate In\",\n          \"navloStatusIcon\": \"log-in\",\n          \"navloStatusDisplayOrder\": 20,\n          \"navloStatusCategory\": \"ORIGIN\",\n          \"courierStatus\": \"Export received at CY\",\n          \"location\": \"Shanghai\",\n          \"locationCode\": \"CNSHA\",\n          \"terminalName\": \"Yangshan Deep Water Port Phase IV\",\n          \"locationCountryCode\": \"CN\",\n          \"locationCoordinates\": {\n            \"lat\": 31.2304,\n            \"lng\": 121.4737\n          },\n          \"activityTimestamp\": \"2026-09-24T14:12:00Z\",\n          \"eventType\": \"ACTUAL\",\n          \"vesselName\": null,\n          \"voyageNumber\": null,\n          \"transportMode\": null,\n          \"detectionSource\": null\n        },\n        {\n          \"id\": \"c1-e2\",\n          \"navloStatusCode\": \"LOADED\",\n          \"navloStatusName\": \"Loaded\",\n          \"navloStatusIcon\": \"package\",\n          \"navloStatusDisplayOrder\": 40,\n          \"navloStatusCategory\": \"TRANSIT\",\n          \"courierStatus\": \"Export Loaded on Vessel\",\n          \"location\": \"Shanghai\",\n          \"locationCode\": \"CNSHA\",\n          \"terminalName\": \"Yangshan Deep Water Port Phase IV\",\n          \"locationCountryCode\": \"CN\",\n          \"locationCoordinates\": {\n            \"lat\": 31.2304,\n            \"lng\": 121.4737\n          },\n          \"activityTimestamp\": \"2026-09-26T21:30:00Z\",\n          \"eventType\": \"ACTUAL\",\n          \"vesselName\": \"MSC MARTINA\",\n          \"voyageNumber\": \"438W\",\n          \"transportMode\": \"VESSEL\",\n          \"detectionSource\": null\n        },\n        {\n          \"id\": \"c1-e3\",\n          \"navloStatusCode\": \"DEPARTED\",\n          \"navloStatusName\": \"Departed\",\n          \"navloStatusIcon\": \"ship\",\n          \"navloStatusDisplayOrder\": 50,\n          \"navloStatusCategory\": \"TRANSIT\",\n          \"courierStatus\": \"Vessel Departure\",\n          \"location\": \"Shanghai\",\n          \"locationCode\": \"CNSHA\",\n          \"terminalName\": \"Yangshan Deep Water Port Phase IV\",\n          \"locationCountryCode\": \"CN\",\n          \"locationCoordinates\": {\n            \"lat\": 31.2304,\n            \"lng\": 121.4737\n          },\n          \"activityTimestamp\": \"2026-09-27T03:40:00Z\",\n          \"eventType\": \"ACTUAL\",\n          \"vesselName\": \"MSC MARTINA\",\n          \"voyageNumber\": \"438W\",\n          \"transportMode\": \"VESSEL\",\n          \"detectionSource\": null\n        },\n        {\n          \"id\": \"c1-e4\",\n          \"navloStatusCode\": \"TRANSSHIPMENT\",\n          \"navloStatusName\": \"Transshipment\",\n          \"navloStatusIcon\": \"repeat\",\n          \"navloStatusDisplayOrder\": 90,\n          \"navloStatusCategory\": \"TRANSIT\",\n          \"courierStatus\": \"Estimated Time of Arrival\",\n          \"location\": \"Piraeus\",\n          \"locationCode\": \"GRPIR\",\n          \"terminalName\": null,\n          \"locationCountryCode\": \"GR\",\n          \"locationCoordinates\": {\n            \"lat\": 37.9421,\n            \"lng\": 23.6465\n          },\n          \"activityTimestamp\": \"2026-10-23T08:00:00Z\",\n          \"eventType\": \"EXPECTED\",\n          \"vesselName\": \"MSC MARTINA\",\n          \"voyageNumber\": \"438W\",\n          \"transportMode\": \"VESSEL\",\n          \"detectionSource\": null\n        },\n        {\n          \"id\": \"c1-e5\",\n          \"navloStatusCode\": \"ARRIVED\",\n          \"navloStatusName\": \"Arrived\",\n          \"navloStatusIcon\": \"anchor\",\n          \"navloStatusDisplayOrder\": 70,\n          \"navloStatusCategory\": \"DESTINATION\",\n          \"courierStatus\": \"Estimated Time of Arrival\",\n          \"location\": \"Ambarli\",\n          \"locationCode\": \"TRAMR\",\n          \"terminalName\": \"Marport Ambarli\",\n          \"locationCountryCode\": \"TR\",\n          \"locationCoordinates\": {\n            \"lat\": 40.9667,\n            \"lng\": 28.6833\n          },\n          \"activityTimestamp\": \"2026-10-30T06:00:00Z\",\n          \"eventType\": \"EXPECTED\",\n          \"vesselName\": \"MSC ARIANE\",\n          \"voyageNumber\": \"IP243A\",\n          \"transportMode\": \"VESSEL\",\n          \"detectionSource\": null\n        }\n      ],\n      \"aboardVessel\": true,\n      \"nextPlannedVessel\": {\n        \"vesselName\": \"MSC ARIANE\",\n        \"voyageNumber\": \"IP243A\",\n        \"plannedAt\": \"2026-10-27T18:00:00Z\",\n        \"portName\": \"Piraeus\",\n        \"portCode\": \"GRPIR\"\n      }\n    }\n  ],\n  \"airShipments\": [],\n  \"vesselPosition\": {\n    \"vesselName\": \"MSC MARTINA\",\n    \"latitude\": 34.9123,\n    \"longitude\": 25.6342,\n    \"heading\": 318,\n    \"source\": \"LIVE\",\n    \"reportedAt\": \"2026-10-22T05:41:00Z\",\n    \"ageHours\": 3\n  }\n}"
                }
              ],
              "errors": [
                {
                  "status": 400,
                  "message": "Required parameter 'number' is missing",
                  "when": "No `number` (general error shape)."
                },
                {
                  "status": 401,
                  "message": "",
                  "when": "Missing, wrong or revoked embed key — or a REST key."
                },
                {
                  "status": 403,
                  "message": "",
                  "when": "The key pins origins and `parentOrigin` is missing or not one of them."
                },
                {
                  "status": 404,
                  "message": "",
                  "when": "Your organization doesn’t track that number."
                },
                {
                  "status": 429,
                  "message": "",
                  "when": "More than 60 lookups in a minute with this key. Wait the `Retry-After` seconds."
                }
              ],
              "notes": [
                "Not charged, but limited to 60 lookups a minute per key — cache answers for a minute or two on your server if your page is busy.",
                "Errors have an empty body: branch on the status code."
              ]
            },
            {
              "kind": "heading",
              "id": "embed-response-notes",
              "title": "Reading the response"
            },
            {
              "kind": "definitions",
              "items": [
                {
                  "term": "The status headline",
                  "description": "`containers[0].statusListingName` (air: `airShipments[0].statusListingCode`)."
                },
                {
                  "term": "From → to",
                  "description": "`originPortName` → `destinationPortName`."
                },
                {
                  "term": "ETA",
                  "description": "`estimatedArrival`, displayed as-is (carrier local time)."
                },
                {
                  "term": "A timeline",
                  "description": "`activities[]` — `navloStatusName`, `location`, `activityTimestamp`, `eventType`."
                },
                {
                  "term": "A map",
                  "description": "`originPortCoordinates`, `destinationPortCoordinates`, `vesselPosition`."
                }
              ]
            },
            {
              "kind": "callout",
              "tone": "info",
              "text": "The payload is the one Navlo’s own share page renders, so it carries more fields than a simple tracking box needs — ignore the rest. Your integration code should read it like any other Navlo response: unknown fields can appear."
            },
            {
              "kind": "fields",
              "title": "Milestone code",
              "fields": [
                {
                  "name": "activities[].navloStatusCode",
                  "type": "string",
                  "description": "Milestone code — see [milestone codes](/developers/statuses-and-time-zones#statuses-milestones)."
                }
              ]
            },
            {
              "kind": "code",
              "title": "Full response",
              "samples": [
                {
                  "lang": "json",
                  "label": "Ocean shipment",
                  "code": "{\n  \"trackingIdentifier\": \"MEDU1234562\",\n  \"trackingMode\": \"OCEAN\",\n  \"status\": \"active\",\n  \"containers\": [\n    {\n      \"id\": \"c1\",\n      \"containerNumber\": \"MEDU1234562\",\n      \"courierCode\": \"MSC\",\n      \"courierName\": \"MSC\",\n      \"courierLogoUrl\": \"https://cdn.example.com/couriers/msc.png\",\n      \"navloStatusCode\": \"DEPARTED\",\n      \"navloStatusName\": \"Departed\",\n      \"navloStatusCategory\": \"TRANSIT\",\n      \"statusListingCode\": \"IN_TRANSIT\",\n      \"statusListingName\": \"In Transit\",\n      \"containerType\": \"40HC\",\n      \"containerIsoCode\": \"45G1\",\n      \"originPortCode\": \"CNSHA\",\n      \"originPortName\": \"Shanghai\",\n      \"originPortCoordinates\": {\n        \"lat\": 31.2304,\n        \"lng\": 121.4737\n      },\n      \"originTerminal\": \"Yangshan Deep Water Port Phase IV\",\n      \"destinationPortCode\": \"TRAMR\",\n      \"destinationPortName\": \"Ambarli\",\n      \"destinationPortCoordinates\": {\n        \"lat\": 40.9667,\n        \"lng\": 28.6833\n      },\n      \"destinationTerminal\": \"Marport Ambarli\",\n      \"currentLocation\": \"Shanghai\",\n      \"currentLocationCode\": \"CNSHA\",\n      \"currentVesselName\": \"MSC MARTINA\",\n      \"currentVoyageNumber\": \"438W\",\n      \"currentVesselImo\": \"9461805\",\n      \"originCountryCode\": \"CN\",\n      \"destinationCountryCode\": \"TR\",\n      \"demurrageFreeUntil\": null,\n      \"carrierFreeTimeDays\": 7,\n      \"carrierFreeTimeBasis\": \"Calendar Days\",\n      \"estimatedArrival\": \"2026-10-30T06:00:00Z\",\n      \"actualArrival\": null,\n      \"estimatedDeparture\": \"2026-09-26T22:00:00Z\",\n      \"actualDeparture\": \"2026-09-27T03:40:00Z\",\n      \"estimatedDepartureUtc\": \"2026-09-26T14:00:00Z\",\n      \"actualDepartureUtc\": \"2026-09-26T19:40:00Z\",\n      \"estimatedArrivalUtc\": \"2026-10-30T03:00:00Z\",\n      \"actualArrivalUtc\": null,\n      \"estimatedDelivery\": null,\n      \"actualDelivery\": null,\n      \"completedAt\": null,\n      \"co2eKg\": 1856.4,\n      \"co2Source\": \"GLEC\",\n      \"activities\": [\n        {\n          \"id\": \"c1-e1\",\n          \"navloStatusCode\": \"GATE_IN\",\n          \"navloStatusName\": \"Gate In\",\n          \"navloStatusIcon\": \"log-in\",\n          \"navloStatusDisplayOrder\": 20,\n          \"navloStatusCategory\": \"ORIGIN\",\n          \"courierStatus\": \"Export received at CY\",\n          \"location\": \"Shanghai\",\n          \"locationCode\": \"CNSHA\",\n          \"terminalName\": \"Yangshan Deep Water Port Phase IV\",\n          \"locationCountryCode\": \"CN\",\n          \"locationCoordinates\": {\n            \"lat\": 31.2304,\n            \"lng\": 121.4737\n          },\n          \"activityTimestamp\": \"2026-09-24T14:12:00Z\",\n          \"eventType\": \"ACTUAL\",\n          \"vesselName\": null,\n          \"voyageNumber\": null,\n          \"transportMode\": null,\n          \"detectionSource\": null\n        },\n        {\n          \"id\": \"c1-e2\",\n          \"navloStatusCode\": \"LOADED\",\n          \"navloStatusName\": \"Loaded\",\n          \"navloStatusIcon\": \"package\",\n          \"navloStatusDisplayOrder\": 40,\n          \"navloStatusCategory\": \"TRANSIT\",\n          \"courierStatus\": \"Export Loaded on Vessel\",\n          \"location\": \"Shanghai\",\n          \"locationCode\": \"CNSHA\",\n          \"terminalName\": \"Yangshan Deep Water Port Phase IV\",\n          \"locationCountryCode\": \"CN\",\n          \"locationCoordinates\": {\n            \"lat\": 31.2304,\n            \"lng\": 121.4737\n          },\n          \"activityTimestamp\": \"2026-09-26T21:30:00Z\",\n          \"eventType\": \"ACTUAL\",\n          \"vesselName\": \"MSC MARTINA\",\n          \"voyageNumber\": \"438W\",\n          \"transportMode\": \"VESSEL\",\n          \"detectionSource\": null\n        },\n        {\n          \"id\": \"c1-e3\",\n          \"navloStatusCode\": \"DEPARTED\",\n          \"navloStatusName\": \"Departed\",\n          \"navloStatusIcon\": \"ship\",\n          \"navloStatusDisplayOrder\": 50,\n          \"navloStatusCategory\": \"TRANSIT\",\n          \"courierStatus\": \"Vessel Departure\",\n          \"location\": \"Shanghai\",\n          \"locationCode\": \"CNSHA\",\n          \"terminalName\": \"Yangshan Deep Water Port Phase IV\",\n          \"locationCountryCode\": \"CN\",\n          \"locationCoordinates\": {\n            \"lat\": 31.2304,\n            \"lng\": 121.4737\n          },\n          \"activityTimestamp\": \"2026-09-27T03:40:00Z\",\n          \"eventType\": \"ACTUAL\",\n          \"vesselName\": \"MSC MARTINA\",\n          \"voyageNumber\": \"438W\",\n          \"transportMode\": \"VESSEL\",\n          \"detectionSource\": null\n        },\n        {\n          \"id\": \"c1-e4\",\n          \"navloStatusCode\": \"TRANSSHIPMENT\",\n          \"navloStatusName\": \"Transshipment\",\n          \"navloStatusIcon\": \"repeat\",\n          \"navloStatusDisplayOrder\": 90,\n          \"navloStatusCategory\": \"TRANSIT\",\n          \"courierStatus\": \"Estimated Time of Arrival\",\n          \"location\": \"Piraeus\",\n          \"locationCode\": \"GRPIR\",\n          \"terminalName\": null,\n          \"locationCountryCode\": \"GR\",\n          \"locationCoordinates\": {\n            \"lat\": 37.9421,\n            \"lng\": 23.6465\n          },\n          \"activityTimestamp\": \"2026-10-23T08:00:00Z\",\n          \"eventType\": \"EXPECTED\",\n          \"vesselName\": \"MSC MARTINA\",\n          \"voyageNumber\": \"438W\",\n          \"transportMode\": \"VESSEL\",\n          \"detectionSource\": null\n        },\n        {\n          \"id\": \"c1-e5\",\n          \"navloStatusCode\": \"ARRIVED\",\n          \"navloStatusName\": \"Arrived\",\n          \"navloStatusIcon\": \"anchor\",\n          \"navloStatusDisplayOrder\": 70,\n          \"navloStatusCategory\": \"DESTINATION\",\n          \"courierStatus\": \"Estimated Time of Arrival\",\n          \"location\": \"Ambarli\",\n          \"locationCode\": \"TRAMR\",\n          \"terminalName\": \"Marport Ambarli\",\n          \"locationCountryCode\": \"TR\",\n          \"locationCoordinates\": {\n            \"lat\": 40.9667,\n            \"lng\": 28.6833\n          },\n          \"activityTimestamp\": \"2026-10-30T06:00:00Z\",\n          \"eventType\": \"EXPECTED\",\n          \"vesselName\": \"MSC ARIANE\",\n          \"voyageNumber\": \"IP243A\",\n          \"transportMode\": \"VESSEL\",\n          \"detectionSource\": null\n        }\n      ],\n      \"aboardVessel\": true,\n      \"nextPlannedVessel\": {\n        \"vesselName\": \"MSC ARIANE\",\n        \"voyageNumber\": \"IP243A\",\n        \"plannedAt\": \"2026-10-27T18:00:00Z\",\n        \"portName\": \"Piraeus\",\n        \"portCode\": \"GRPIR\"\n      }\n    }\n  ],\n  \"airShipments\": [],\n  \"vesselPosition\": {\n    \"vesselName\": \"MSC MARTINA\",\n    \"latitude\": 34.9123,\n    \"longitude\": 25.6342,\n    \"heading\": 318,\n    \"source\": \"LIVE\",\n    \"reportedAt\": \"2026-10-22T05:41:00Z\",\n    \"ageHours\": 3\n  }\n}"
                }
              ]
            }
          ]
        }
      ]
    },
    {
      "id": "vessels-ports",
      "title": "Vessels & ports",
      "pages": [
        {
          "id": "vessels",
          "title": "Vessels",
          "summary": "Follow a vessel’s voyage — live position, ETA changes and port calls — exactly like the app’s Vessel Tracking page.",
          "blocks": [
            {
              "kind": "prose",
              "text": "Vessel tracking follows a ship rather than a container: its AIS position, the destination and ETA its crew broadcasts, and every port call. Use it for vessels you charter, or when you only know the ship."
            },
            {
              "kind": "definitions",
              "items": [
                {
                  "term": "Cost",
                  "description": "2 tracking credits per voyage, charged when you start following — free when one of your tracked containers is on the vessel."
                },
                {
                  "term": "Refunds",
                  "description": "None: completing or removing a follow doesn’t return credits."
                },
                {
                  "term": "Limit",
                  "description": "50 active follows per organization."
                },
                {
                  "term": "Voyage end",
                  "description": "Arrival at the broadcast destination, or 7 days idle in port; a reminder at day 45 and an automatic end at day 60."
                }
              ]
            },
            {
              "kind": "endpoint",
              "id": "vessels-search",
              "method": "GET",
              "path": "/v1/vessels/search",
              "summary": "Search vessels",
              "description": [
                "Searches Navlo’s vessel catalogue by name, IMO or MMSI. Free. A ship the catalogue doesn’t list can still be followed by its IMO or MMSI."
              ],
              "auth": "apiKey",
              "rateLimit": "general",
              "since": "2026-10-22",
              "pathParams": [],
              "queryParams": [
                {
                  "name": "q",
                  "type": "string",
                  "required": true,
                  "description": "3–60 characters: part of the name, or a full IMO / MMSI number."
                }
              ],
              "headers": [],
              "response": {
                "status": 200,
                "contentType": "application/json",
                "fields": [
                  {
                    "name": "available",
                    "type": "boolean",
                    "description": "`false` when the catalogue could not answer — retry."
                  },
                  {
                    "name": "results",
                    "type": "array<object>",
                    "description": "Up to 40 matching vessels, best match first."
                  },
                  {
                    "name": "results[].imo",
                    "type": "string",
                    "nullable": true,
                    "description": "IMO number."
                  },
                  {
                    "name": "results[].mmsi",
                    "type": "string",
                    "nullable": true,
                    "description": "MMSI."
                  },
                  {
                    "name": "results[].name",
                    "type": "string",
                    "description": "Vessel name."
                  },
                  {
                    "name": "results[].vesselType",
                    "type": "string",
                    "nullable": true,
                    "description": "e.g. \"Container Ship\"."
                  },
                  {
                    "name": "results[].flag",
                    "type": "string",
                    "nullable": true,
                    "description": "Flag state, ISO alpha-2."
                  },
                  {
                    "name": "results[].followId",
                    "type": "uuid",
                    "nullable": true,
                    "description": "Your follow of this vessel, if you have one."
                  },
                  {
                    "name": "results[].followStatus",
                    "type": "enum",
                    "nullable": true,
                    "description": "That follow’s status.",
                    "values": [
                      "ACTIVE",
                      "COMPLETED"
                    ]
                  }
                ]
              },
              "requestExamples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl \"https://api.navlo.io/v1/vessels/search?q=nordic%20aurora\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\""
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const params = new URLSearchParams({ q: 'nordic aurora' })\n\nconst res = await fetch(`https://api.navlo.io/v1/vessels/search?${params}`, {\n  headers: { 'X-API-Key': process.env.NAVLO_API_KEY },\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\nconst search = await res.json()"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.get(\n    \"https://api.navlo.io/v1/vessels/search\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    params={\"q\": \"nordic aurora\"},\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\nsearch = r.json()"
                }
              ],
              "responseExamples": [
                {
                  "status": 200,
                  "contentType": "application/json",
                  "body": "{\n  \"available\": true,\n  \"results\": [\n    {\n      \"imo\": \"9734512\",\n      \"mmsi\": \"636019274\",\n      \"name\": \"NORDIC AURORA\",\n      \"vesselType\": \"Container Ship\",\n      \"flag\": \"LR\",\n      \"followId\": null,\n      \"followStatus\": null\n    }\n  ]\n}"
                }
              ],
              "errors": [
                {
                  "status": 400,
                  "message": "Type at least 3 characters of the vessel name, or its IMO / MMSI number",
                  "when": "`q` shorter than 3 or longer than 60 characters."
                },
                {
                  "status": 401,
                  "message": "Invalid or revoked API key",
                  "when": "The X-API-Key header is missing, wrong or revoked."
                },
                {
                  "status": 429,
                  "message": "Rate limit exceeded (60 requests/minute)",
                  "when": "Over the per-key budget; wait Retry-After seconds."
                }
              ],
              "notes": []
            },
            {
              "kind": "endpoint",
              "id": "vessels-quote",
              "method": "POST",
              "path": "/v1/vessels/follows/quote",
              "summary": "Quote a follow",
              "description": [
                "What following this vessel would cost, before you commit — including the next voyage of a vessel whose follow you completed. Same body as [follow](#vessels-follow); `customer` is ignored. Changes nothing."
              ],
              "auth": "apiKey",
              "rateLimit": "general",
              "since": "2026-10-22",
              "pathParams": [],
              "queryParams": [],
              "headers": [],
              "body": {
                "contentType": "application/json",
                "fields": [
                  {
                    "name": "name",
                    "type": "string",
                    "required": true,
                    "description": "The vessel name, up to 100 characters."
                  },
                  {
                    "name": "imo",
                    "type": "string",
                    "required": false,
                    "description": "IMO number, 7 digits. Send `imo` or `mmsi` — a name alone can match several ships."
                  },
                  {
                    "name": "mmsi",
                    "type": "string",
                    "required": false,
                    "description": "MMSI, 9 digits."
                  }
                ]
              },
              "response": {
                "status": 200,
                "contentType": "application/json",
                "fields": [
                  {
                    "name": "credits",
                    "type": "number",
                    "description": "Tracking credits the follow would charge: 2, or 0 when covered or already followed."
                  },
                  {
                    "name": "covered",
                    "type": "boolean",
                    "description": "`true` when one of your tracked containers is on this vessel — following is free."
                  },
                  {
                    "name": "alreadyTracking",
                    "type": "boolean",
                    "description": "`true` when you already follow it — following again returns that follow at no charge."
                  },
                  {
                    "name": "enoughCredits",
                    "type": "boolean",
                    "description": "Whether your balance covers it."
                  }
                ]
              },
              "requestExamples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl -X POST \"https://api.navlo.io/v1/vessels/follows/quote\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"name\": \"NORDIC AURORA\",\n    \"imo\": \"9734512\"\n  }'"
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const res = await fetch('https://api.navlo.io/v1/vessels/follows/quote', {\n  method: 'POST',\n  headers: {\n    'X-API-Key': process.env.NAVLO_API_KEY,\n    'Content-Type': 'application/json',\n  },\n  body: JSON.stringify({ name: 'NORDIC AURORA', imo: '9734512' }),\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\nconst quote = await res.json()"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.post(\n    \"https://api.navlo.io/v1/vessels/follows/quote\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    json={\"name\": \"NORDIC AURORA\", \"imo\": \"9734512\"},\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\nquote = r.json()"
                }
              ],
              "responseExamples": [
                {
                  "status": 200,
                  "contentType": "application/json",
                  "body": "{\n  \"credits\": 2,\n  \"covered\": false,\n  \"alreadyTracking\": false,\n  \"enoughCredits\": true\n}"
                }
              ],
              "errors": [
                {
                  "status": 400,
                  "message": "IMO must be 7 digits",
                  "when": "Malformed `imo`."
                },
                {
                  "status": 400,
                  "message": "Request body is missing or is not valid JSON",
                  "when": "The body could not be parsed."
                },
                {
                  "status": 401,
                  "message": "Invalid or revoked API key",
                  "when": "The X-API-Key header is missing, wrong or revoked."
                },
                {
                  "status": 429,
                  "message": "Rate limit exceeded (60 requests/minute)",
                  "when": "Over the per-key budget; wait Retry-After seconds."
                }
              ],
              "notes": []
            },
            {
              "kind": "endpoint",
              "id": "vessels-follow",
              "method": "POST",
              "path": "/v1/vessels/follows",
              "summary": "Follow a vessel",
              "description": [
                "Starts following the vessel’s current voyage and charges for it. Following a vessel you already follow returns that follow without a charge (with `customer`, it sets or replaces the follow’s customer); following one whose voyage you completed starts — and charges — a new voyage. Always `201`."
              ],
              "auth": "apiKey",
              "rateLimit": "general",
              "since": "2026-10-22",
              "pathParams": [],
              "queryParams": [],
              "headers": [],
              "body": {
                "contentType": "application/json",
                "fields": [
                  {
                    "name": "name",
                    "type": "string",
                    "required": true,
                    "description": "The vessel name, up to 100 characters."
                  },
                  {
                    "name": "imo",
                    "type": "string",
                    "required": false,
                    "description": "IMO number, 7 digits. Send `imo` or `mmsi` — a name alone can match several ships."
                  },
                  {
                    "name": "mmsi",
                    "type": "string",
                    "required": false,
                    "description": "MMSI, 9 digits."
                  },
                  {
                    "name": "vesselType",
                    "type": "string",
                    "required": false,
                    "description": "As returned by search."
                  },
                  {
                    "name": "flag",
                    "type": "string",
                    "required": false,
                    "description": "As returned by search."
                  },
                  {
                    "name": "customer",
                    "type": "object",
                    "required": false,
                    "description": "Attribute the credits to a customer — `{ \"ref\", \"name\" }` or `{ \"id\" }`. Absent or null leaves the follow’s customer as it is."
                  },
                  {
                    "name": "customer.id",
                    "type": "uuid",
                    "required": false,
                    "description": "A Navlo customer id from [`GET /v1/customers`](/developers/customers#customers-list). Wins when both `id` and `ref` are sent."
                  },
                  {
                    "name": "customer.ref",
                    "type": "string",
                    "required": false,
                    "description": "Your own code for the customer (max 100 characters, case-insensitive, trimmed). An unknown ref creates the customer."
                  },
                  {
                    "name": "customer.name",
                    "type": "string",
                    "required": false,
                    "description": "Name used only when the ref creates a new customer. Defaults to the ref. Never renames an existing customer."
                  }
                ]
              },
              "response": {
                "status": 201,
                "contentType": "application/json",
                "fields": [
                  {
                    "name": "id",
                    "type": "uuid",
                    "description": "Follow id."
                  },
                  {
                    "name": "status",
                    "type": "enum",
                    "description": "`ACTIVE` while Navlo follows the voyage; `COMPLETED` when it ended.",
                    "values": [
                      "ACTIVE",
                      "COMPLETED"
                    ]
                  },
                  {
                    "name": "state",
                    "type": "enum",
                    "description": "What the vessel is doing now. `UNKNOWN` after 24 hours without a signal.",
                    "values": [
                      "IN_TRANSIT",
                      "IN_PORT",
                      "AT_ANCHOR",
                      "STOPPED",
                      "UNKNOWN"
                    ]
                  },
                  {
                    "name": "vessel",
                    "type": "object",
                    "description": "The ship: `imo`, `mmsi`, `name`, `vesselType`, `flag` (ISO alpha-2), `callsign`, `yearBuilt`, `grossTonnage`, `lengthMeters`, `widthMeters` — any can be null."
                  },
                  {
                    "name": "position",
                    "type": "object",
                    "nullable": true,
                    "description": "Latest AIS position: `latitude`, `longitude`, `courseDegrees`, `speedKnots`, `navStatus` and `reportedAt` (the AIS fix, UTC)."
                  },
                  {
                    "name": "destination",
                    "type": "string",
                    "nullable": true,
                    "description": "The destination the crew entered in AIS, as broadcast."
                  },
                  {
                    "name": "destinationPort",
                    "type": "object",
                    "nullable": true,
                    "description": "That destination resolved to a port. Both times are null while the voyage runs; on a completed follow `arrivedAt` is the actual arrival: `name`, `locode`, `countryCode`, `arrivedAt`, `departedAt` (UTC)."
                  },
                  {
                    "name": "eta",
                    "type": "timestamp",
                    "nullable": true,
                    "description": "The vessel’s current ETA there (UTC); null once completed."
                  },
                  {
                    "name": "firstEta",
                    "type": "timestamp",
                    "nullable": true,
                    "description": "The ETA when you started following."
                  },
                  {
                    "name": "etaChangeCount",
                    "type": "integer",
                    "description": "How often the ETA has changed since."
                  },
                  {
                    "name": "delayed",
                    "type": "boolean",
                    "description": "`true` when the ETA is more than 24 hours later than `firstEta`."
                  },
                  {
                    "name": "overdue",
                    "type": "boolean",
                    "description": "`true` when the ETA passed more than 24 hours ago and the vessel is not in port."
                  },
                  {
                    "name": "currentPort",
                    "type": "object",
                    "nullable": true,
                    "description": "The port the vessel is in, with `arrivedAt`: `name`, `locode`, `countryCode`, `arrivedAt`, `departedAt` (UTC)."
                  },
                  {
                    "name": "lastPort",
                    "type": "object",
                    "nullable": true,
                    "description": "The last port it left, with `departedAt`: `name`, `locode`, `countryCode`, `arrivedAt`, `departedAt` (UTC)."
                  },
                  {
                    "name": "customer",
                    "type": "object",
                    "nullable": true,
                    "description": "The customer its credits are attributed to: `{ id, ref, name, countryCode }`."
                  },
                  {
                    "name": "followedBy",
                    "type": "object",
                    "description": "Who started following: `name`, `email` — for API follows, the key’s creator."
                  },
                  {
                    "name": "createdAt",
                    "type": "timestamp",
                    "description": "Followed since (UTC)."
                  },
                  {
                    "name": "completedAt",
                    "type": "timestamp",
                    "nullable": true,
                    "description": "When following ended (UTC)."
                  }
                ]
              },
              "requestExamples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl -X POST \"https://api.navlo.io/v1/vessels/follows\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"name\": \"NORDIC AURORA\",\n    \"imo\": \"9734512\",\n    \"mmsi\": \"636019274\",\n    \"vesselType\": \"Container Ship\",\n    \"flag\": \"LR\",\n    \"customer\": {\n      \"ref\": \"C-1042\"\n    }\n  }'"
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const res = await fetch('https://api.navlo.io/v1/vessels/follows', {\n  method: 'POST',\n  headers: {\n    'X-API-Key': process.env.NAVLO_API_KEY,\n    'Content-Type': 'application/json',\n  },\n  body: JSON.stringify({\n    name: 'NORDIC AURORA',\n    imo: '9734512',\n    mmsi: '636019274',\n    vesselType: 'Container Ship',\n    flag: 'LR',\n    customer: { ref: 'C-1042' },\n  }),\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\nconst follow = await res.json()"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.post(\n    \"https://api.navlo.io/v1/vessels/follows\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    json={\n        \"name\": \"NORDIC AURORA\",\n        \"imo\": \"9734512\",\n        \"mmsi\": \"636019274\",\n        \"vesselType\": \"Container Ship\",\n        \"flag\": \"LR\",\n        \"customer\": {\"ref\": \"C-1042\"},\n    },\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\nfollow = r.json()"
                }
              ],
              "responseExamples": [
                {
                  "status": 201,
                  "contentType": "application/json",
                  "body": "{\n  \"id\": \"7c1e4a9d-3b6f-4d28-9e05-a2f8c6b1d3e7\",\n  \"status\": \"ACTIVE\",\n  \"state\": \"IN_TRANSIT\",\n  \"vessel\": {\n    \"imo\": \"9734512\",\n    \"mmsi\": \"636019274\",\n    \"name\": \"NORDIC AURORA\",\n    \"vesselType\": \"Container Ship\",\n    \"flag\": \"LR\",\n    \"callsign\": \"D5QK7\",\n    \"yearBuilt\": 2017,\n    \"grossTonnage\": 94511,\n    \"lengthMeters\": 299.9,\n    \"widthMeters\": 48.2\n  },\n  \"position\": {\n    \"latitude\": 13.1048,\n    \"longitude\": 48.7431,\n    \"courseDegrees\": 262.4,\n    \"speedKnots\": 17.2,\n    \"navStatus\": \"Under way using engine\",\n    \"reportedAt\": \"2026-10-22T07:58:00Z\"\n  },\n  \"destination\": \"TR AMR\",\n  \"destinationPort\": {\n    \"name\": \"Ambarli\",\n    \"locode\": \"TRAMR\",\n    \"countryCode\": \"TR\",\n    \"arrivedAt\": null,\n    \"departedAt\": null\n  },\n  \"eta\": \"2026-11-02T04:00:00Z\",\n  \"firstEta\": \"2026-10-31T22:00:00Z\",\n  \"etaChangeCount\": 2,\n  \"delayed\": true,\n  \"overdue\": false,\n  \"currentPort\": null,\n  \"lastPort\": {\n    \"name\": \"Singapore\",\n    \"locode\": \"SGSIN\",\n    \"countryCode\": \"SG\",\n    \"arrivedAt\": null,\n    \"departedAt\": \"2026-10-09T16:20:00Z\"\n  },\n  \"customer\": {\n    \"id\": \"c7d2a9e4-3f1b-4e8a-9b6c-1d5e7f3a2b90\",\n    \"ref\": \"C-1042\",\n    \"name\": \"Acme Trading Ltd.\",\n    \"countryCode\": \"TR\"\n  },\n  \"followedBy\": {\n    \"name\": \"Elif Yılmaz\",\n    \"email\": \"elif.yilmaz@forwarder.example\"\n  },\n  \"createdAt\": \"2026-10-05T09:12:44Z\",\n  \"completedAt\": null\n}"
                }
              ],
              "errors": [
                {
                  "status": 400,
                  "message": "IMO must be 7 digits",
                  "when": "Malformed `imo`."
                },
                {
                  "status": 400,
                  "message": "MMSI must be 9 digits",
                  "when": "Malformed `mmsi`."
                },
                {
                  "status": 400,
                  "message": "Pick a vessel with an IMO or MMSI number — a name alone can match several ships",
                  "when": "Neither `imo` nor `mmsi`."
                },
                {
                  "status": 400,
                  "message": "name: must not be blank",
                  "when": "`name` missing or blank."
                },
                {
                  "status": 400,
                  "message": "Unknown customer id",
                  "when": "`customer.id` is not one of your customers."
                },
                {
                  "status": 402,
                  "message": "Insufficient tracking credits in organization pool. Required: 2, Available: 1",
                  "when": "Not enough tracking credits."
                },
                {
                  "status": 409,
                  "message": "Your organization already follows 50 vessels — complete or remove one to add another",
                  "when": "50 active follows."
                },
                {
                  "status": 400,
                  "message": "Request body is missing or is not valid JSON",
                  "when": "The body could not be parsed."
                },
                {
                  "status": 401,
                  "message": "Invalid or revoked API key",
                  "when": "The X-API-Key header is missing, wrong or revoked."
                },
                {
                  "status": 429,
                  "message": "Rate limit exceeded (60 requests/minute)",
                  "when": "Over the per-key budget; wait Retry-After seconds."
                }
              ],
              "notes": []
            },
            {
              "kind": "endpoint",
              "id": "vessels-list",
              "method": "GET",
              "path": "/v1/vessels/follows",
              "summary": "List followed vessels",
              "description": [],
              "auth": "apiKey",
              "rateLimit": "general",
              "since": "2026-10-22",
              "pathParams": [],
              "queryParams": [
                {
                  "name": "page",
                  "type": "integer",
                  "required": false,
                  "description": "Zero-based page index.",
                  "defaultValue": "0"
                },
                {
                  "name": "size",
                  "type": "integer",
                  "required": false,
                  "description": "Page size, 1–100.",
                  "defaultValue": "20"
                }
              ],
              "headers": [],
              "response": {
                "status": 200,
                "contentType": "application/json",
                "fields": [
                  {
                    "name": "page",
                    "type": "integer",
                    "description": "Page index."
                  },
                  {
                    "name": "size",
                    "type": "integer",
                    "description": "Page size."
                  },
                  {
                    "name": "totalElements",
                    "type": "integer",
                    "description": "Follows."
                  },
                  {
                    "name": "totalPages",
                    "type": "integer",
                    "description": "Pages at this size."
                  },
                  {
                    "name": "follows",
                    "type": "array<object>",
                    "description": "Active follows first, then completed ones; newest first within each. Fields as on [follow](#vessels-follow)."
                  }
                ]
              },
              "requestExamples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl \"https://api.navlo.io/v1/vessels/follows\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\""
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const res = await fetch('https://api.navlo.io/v1/vessels/follows', {\n  headers: { 'X-API-Key': process.env.NAVLO_API_KEY },\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\nconst page = await res.json()"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.get(\n    \"https://api.navlo.io/v1/vessels/follows\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\npage = r.json()"
                }
              ],
              "responseExamples": [
                {
                  "status": 200,
                  "contentType": "application/json",
                  "body": "{\n  \"page\": 0,\n  \"size\": 20,\n  \"totalElements\": 1,\n  \"totalPages\": 1,\n  \"follows\": [\n    {\n      \"id\": \"7c1e4a9d-3b6f-4d28-9e05-a2f8c6b1d3e7\",\n      \"status\": \"ACTIVE\",\n      \"state\": \"IN_TRANSIT\",\n      \"vessel\": {\n        \"imo\": \"9734512\",\n        \"mmsi\": \"636019274\",\n        \"name\": \"NORDIC AURORA\",\n        \"vesselType\": \"Container Ship\",\n        \"flag\": \"LR\",\n        \"callsign\": \"D5QK7\",\n        \"yearBuilt\": 2017,\n        \"grossTonnage\": 94511,\n        \"lengthMeters\": 299.9,\n        \"widthMeters\": 48.2\n      },\n      \"position\": {\n        \"latitude\": 13.1048,\n        \"longitude\": 48.7431,\n        \"courseDegrees\": 262.4,\n        \"speedKnots\": 17.2,\n        \"navStatus\": \"Under way using engine\",\n        \"reportedAt\": \"2026-10-22T07:58:00Z\"\n      },\n      \"destination\": \"TR AMR\",\n      \"destinationPort\": {\n        \"name\": \"Ambarli\",\n        \"locode\": \"TRAMR\",\n        \"countryCode\": \"TR\",\n        \"arrivedAt\": null,\n        \"departedAt\": null\n      },\n      \"eta\": \"2026-11-02T04:00:00Z\",\n      \"firstEta\": \"2026-10-31T22:00:00Z\",\n      \"etaChangeCount\": 2,\n      \"delayed\": true,\n      \"overdue\": false,\n      \"currentPort\": null,\n      \"lastPort\": {\n        \"name\": \"Singapore\",\n        \"locode\": \"SGSIN\",\n        \"countryCode\": \"SG\",\n        \"arrivedAt\": null,\n        \"departedAt\": \"2026-10-09T16:20:00Z\"\n      },\n      \"customer\": {\n        \"id\": \"c7d2a9e4-3f1b-4e8a-9b6c-1d5e7f3a2b90\",\n        \"ref\": \"C-1042\",\n        \"name\": \"Acme Trading Ltd.\",\n        \"countryCode\": \"TR\"\n      },\n      \"followedBy\": {\n        \"name\": \"Elif Yılmaz\",\n        \"email\": \"elif.yilmaz@forwarder.example\"\n      },\n      \"createdAt\": \"2026-10-05T09:12:44Z\",\n      \"completedAt\": null\n    }\n  ]\n}"
                }
              ],
              "errors": [
                {
                  "status": 401,
                  "message": "Invalid or revoked API key",
                  "when": "The X-API-Key header is missing, wrong or revoked."
                },
                {
                  "status": 429,
                  "message": "Rate limit exceeded (60 requests/minute)",
                  "when": "Over the per-key budget; wait Retry-After seconds."
                }
              ],
              "notes": []
            },
            {
              "kind": "endpoint",
              "id": "vessels-get",
              "method": "GET",
              "path": "/v1/vessels/follows/{id}",
              "summary": "Retrieve a followed vessel",
              "description": [
                "The follow with its ETA history, the latest 20 port calls and the latest 100 events."
              ],
              "auth": "apiKey",
              "rateLimit": "general",
              "since": "2026-10-22",
              "pathParams": [
                {
                  "name": "id",
                  "type": "uuid",
                  "required": true,
                  "description": "The follow id."
                }
              ],
              "queryParams": [],
              "headers": [],
              "response": {
                "status": 200,
                "contentType": "application/json",
                "fields": [
                  {
                    "name": "id",
                    "type": "uuid",
                    "description": "Follow id."
                  },
                  {
                    "name": "status",
                    "type": "enum",
                    "description": "`ACTIVE` while Navlo follows the voyage; `COMPLETED` when it ended.",
                    "values": [
                      "ACTIVE",
                      "COMPLETED"
                    ]
                  },
                  {
                    "name": "state",
                    "type": "enum",
                    "description": "What the vessel is doing now. `UNKNOWN` after 24 hours without a signal.",
                    "values": [
                      "IN_TRANSIT",
                      "IN_PORT",
                      "AT_ANCHOR",
                      "STOPPED",
                      "UNKNOWN"
                    ]
                  },
                  {
                    "name": "vessel",
                    "type": "object",
                    "description": "The ship: `imo`, `mmsi`, `name`, `vesselType`, `flag` (ISO alpha-2), `callsign`, `yearBuilt`, `grossTonnage`, `lengthMeters`, `widthMeters` — any can be null."
                  },
                  {
                    "name": "position",
                    "type": "object",
                    "nullable": true,
                    "description": "Latest AIS position: `latitude`, `longitude`, `courseDegrees`, `speedKnots`, `navStatus` and `reportedAt` (the AIS fix, UTC)."
                  },
                  {
                    "name": "destination",
                    "type": "string",
                    "nullable": true,
                    "description": "The destination the crew entered in AIS, as broadcast."
                  },
                  {
                    "name": "destinationPort",
                    "type": "object",
                    "nullable": true,
                    "description": "That destination resolved to a port. Both times are null while the voyage runs; on a completed follow `arrivedAt` is the actual arrival: `name`, `locode`, `countryCode`, `arrivedAt`, `departedAt` (UTC)."
                  },
                  {
                    "name": "eta",
                    "type": "timestamp",
                    "nullable": true,
                    "description": "The vessel’s current ETA there (UTC); null once completed."
                  },
                  {
                    "name": "firstEta",
                    "type": "timestamp",
                    "nullable": true,
                    "description": "The ETA when you started following."
                  },
                  {
                    "name": "etaChangeCount",
                    "type": "integer",
                    "description": "How often the ETA has changed since."
                  },
                  {
                    "name": "delayed",
                    "type": "boolean",
                    "description": "`true` when the ETA is more than 24 hours later than `firstEta`."
                  },
                  {
                    "name": "overdue",
                    "type": "boolean",
                    "description": "`true` when the ETA passed more than 24 hours ago and the vessel is not in port."
                  },
                  {
                    "name": "currentPort",
                    "type": "object",
                    "nullable": true,
                    "description": "The port the vessel is in, with `arrivedAt`: `name`, `locode`, `countryCode`, `arrivedAt`, `departedAt` (UTC)."
                  },
                  {
                    "name": "lastPort",
                    "type": "object",
                    "nullable": true,
                    "description": "The last port it left, with `departedAt`: `name`, `locode`, `countryCode`, `arrivedAt`, `departedAt` (UTC)."
                  },
                  {
                    "name": "customer",
                    "type": "object",
                    "nullable": true,
                    "description": "The customer its credits are attributed to: `{ id, ref, name, countryCode }`."
                  },
                  {
                    "name": "followedBy",
                    "type": "object",
                    "description": "Who started following: `name`, `email` — for API follows, the key’s creator."
                  },
                  {
                    "name": "createdAt",
                    "type": "timestamp",
                    "description": "Followed since (UTC)."
                  },
                  {
                    "name": "completedAt",
                    "type": "timestamp",
                    "nullable": true,
                    "description": "When following ended (UTC)."
                  },
                  {
                    "name": "etaHistory",
                    "type": "array<object>",
                    "description": "Every ETA the vessel broadcast on this voyage, oldest first: `destination`, `eta`, `observedAt`."
                  },
                  {
                    "name": "portCalls",
                    "type": "array<object>",
                    "description": "This voyage’s port calls, newest first: `name`, `locode`, `countryCode`, `arrivedAt`, `departedAt`, `current`."
                  },
                  {
                    "name": "events",
                    "type": "array<object>",
                    "description": "What happened, newest first: `id`, `type`, `occurredAt`, `portName`, `destination`, `previousEta`, `newEta`."
                  },
                  {
                    "name": "events[].type",
                    "type": "enum",
                    "description": "Event kind.",
                    "values": [
                      "DEPARTED",
                      "ARRIVED",
                      "IN_TRANSIT",
                      "IN_PORT",
                      "AT_ANCHOR",
                      "STOPPED",
                      "ETA_UPDATED",
                      "APPROACHING",
                      "SIGNAL_LOST",
                      "VOYAGE_COMPLETED",
                      "TRACKING_REMINDER",
                      "TRACKING_ENDED"
                    ]
                  }
                ]
              },
              "requestExamples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl \"https://api.navlo.io/v1/vessels/follows/7c1e4a9d-3b6f-4d28-9e05-a2f8c6b1d3e7\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\""
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const res = await fetch('https://api.navlo.io/v1/vessels/follows/7c1e4a9d-3b6f-4d28-9e05-a2f8c6b1d3e7', {\n  headers: { 'X-API-Key': process.env.NAVLO_API_KEY },\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\nconst follow = await res.json()"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.get(\n    \"https://api.navlo.io/v1/vessels/follows/7c1e4a9d-3b6f-4d28-9e05-a2f8c6b1d3e7\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\nfollow = r.json()"
                }
              ],
              "responseExamples": [
                {
                  "status": 200,
                  "contentType": "application/json",
                  "body": "{\n  \"id\": \"7c1e4a9d-3b6f-4d28-9e05-a2f8c6b1d3e7\",\n  \"status\": \"ACTIVE\",\n  \"state\": \"IN_TRANSIT\",\n  \"vessel\": {\n    \"imo\": \"9734512\",\n    \"mmsi\": \"636019274\",\n    \"name\": \"NORDIC AURORA\",\n    \"vesselType\": \"Container Ship\",\n    \"flag\": \"LR\",\n    \"callsign\": \"D5QK7\",\n    \"yearBuilt\": 2017,\n    \"grossTonnage\": 94511,\n    \"lengthMeters\": 299.9,\n    \"widthMeters\": 48.2\n  },\n  \"position\": {\n    \"latitude\": 13.1048,\n    \"longitude\": 48.7431,\n    \"courseDegrees\": 262.4,\n    \"speedKnots\": 17.2,\n    \"navStatus\": \"Under way using engine\",\n    \"reportedAt\": \"2026-10-22T07:58:00Z\"\n  },\n  \"destination\": \"TR AMR\",\n  \"destinationPort\": {\n    \"name\": \"Ambarli\",\n    \"locode\": \"TRAMR\",\n    \"countryCode\": \"TR\",\n    \"arrivedAt\": null,\n    \"departedAt\": null\n  },\n  \"eta\": \"2026-11-02T04:00:00Z\",\n  \"firstEta\": \"2026-10-31T22:00:00Z\",\n  \"etaChangeCount\": 2,\n  \"delayed\": true,\n  \"overdue\": false,\n  \"currentPort\": null,\n  \"lastPort\": {\n    \"name\": \"Singapore\",\n    \"locode\": \"SGSIN\",\n    \"countryCode\": \"SG\",\n    \"arrivedAt\": null,\n    \"departedAt\": \"2026-10-09T16:20:00Z\"\n  },\n  \"customer\": {\n    \"id\": \"c7d2a9e4-3f1b-4e8a-9b6c-1d5e7f3a2b90\",\n    \"ref\": \"C-1042\",\n    \"name\": \"Acme Trading Ltd.\",\n    \"countryCode\": \"TR\"\n  },\n  \"followedBy\": {\n    \"name\": \"Elif Yılmaz\",\n    \"email\": \"elif.yilmaz@forwarder.example\"\n  },\n  \"createdAt\": \"2026-10-05T09:12:44Z\",\n  \"completedAt\": null,\n  \"etaHistory\": [\n    {\n      \"destination\": \"TR AMR\",\n      \"eta\": \"2026-10-31T22:00:00Z\",\n      \"observedAt\": \"2026-10-05T09:12:44Z\"\n    },\n    {\n      \"destination\": \"TR AMR\",\n      \"eta\": \"2026-11-01T10:00:00Z\",\n      \"observedAt\": \"2026-10-12T21:40:00Z\"\n    },\n    {\n      \"destination\": \"TR AMR\",\n      \"eta\": \"2026-11-02T04:00:00Z\",\n      \"observedAt\": \"2026-10-19T03:10:00Z\"\n    }\n  ],\n  \"portCalls\": [\n    {\n      \"name\": \"Singapore\",\n      \"locode\": \"SGSIN\",\n      \"countryCode\": \"SG\",\n      \"arrivedAt\": \"2026-10-08T05:30:00Z\",\n      \"departedAt\": \"2026-10-09T16:20:00Z\",\n      \"current\": false\n    },\n    {\n      \"name\": \"Port Klang\",\n      \"locode\": \"MYPKG\",\n      \"countryCode\": \"MY\",\n      \"arrivedAt\": \"2026-10-06T11:05:00Z\",\n      \"departedAt\": \"2026-10-07T02:45:00Z\",\n      \"current\": false\n    }\n  ],\n  \"events\": [\n    {\n      \"id\": \"c1d7a3e9-5b2f-4e84-9a06-3f8b1d5c7e20\",\n      \"type\": \"ETA_UPDATED\",\n      \"occurredAt\": \"2026-10-19T03:10:00Z\",\n      \"portName\": null,\n      \"destination\": \"TR AMR\",\n      \"previousEta\": \"2026-11-01T10:00:00Z\",\n      \"newEta\": \"2026-11-02T04:00:00Z\"\n    },\n    {\n      \"id\": \"8f2b4d6a-1c9e-4a73-b5d0-e7a3c1f9b246\",\n      \"type\": \"DEPARTED\",\n      \"occurredAt\": \"2026-10-09T16:20:00Z\",\n      \"portName\": \"Singapore\",\n      \"destination\": \"TR AMR\",\n      \"previousEta\": null,\n      \"newEta\": null\n    },\n    {\n      \"id\": \"4a9c1e7f-3d5b-4f28-8e60-b2d4f6a8c913\",\n      \"type\": \"ARRIVED\",\n      \"occurredAt\": \"2026-10-08T05:30:00Z\",\n      \"portName\": \"Singapore\",\n      \"destination\": \"SG SIN\",\n      \"previousEta\": null,\n      \"newEta\": null\n    }\n  ]\n}"
                }
              ],
              "errors": [
                {
                  "status": 404,
                  "message": "Vessel not found",
                  "when": "Unknown or removed follow, or another organization’s."
                },
                {
                  "status": 401,
                  "message": "Invalid or revoked API key",
                  "when": "The X-API-Key header is missing, wrong or revoked."
                },
                {
                  "status": 429,
                  "message": "Rate limit exceeded (60 requests/minute)",
                  "when": "Over the per-key budget; wait Retry-After seconds."
                }
              ],
              "notes": []
            },
            {
              "kind": "endpoint",
              "id": "vessels-complete",
              "method": "POST",
              "path": "/v1/vessels/follows/{id}/complete",
              "summary": "Complete a follow",
              "description": [
                "Stops following the voyage now. The follow and its history stay. No credits are returned. Idempotent."
              ],
              "auth": "apiKey",
              "rateLimit": "general",
              "since": "2026-10-22",
              "pathParams": [
                {
                  "name": "id",
                  "type": "uuid",
                  "required": true,
                  "description": "The follow id."
                }
              ],
              "queryParams": [],
              "headers": [],
              "response": {
                "status": 200,
                "contentType": "application/json",
                "fields": [
                  {
                    "name": "id",
                    "type": "uuid",
                    "description": "Follow id."
                  },
                  {
                    "name": "status",
                    "type": "enum",
                    "description": "`ACTIVE` while Navlo follows the voyage; `COMPLETED` when it ended.",
                    "values": [
                      "ACTIVE",
                      "COMPLETED"
                    ]
                  },
                  {
                    "name": "state",
                    "type": "enum",
                    "description": "What the vessel is doing now. `UNKNOWN` after 24 hours without a signal.",
                    "values": [
                      "IN_TRANSIT",
                      "IN_PORT",
                      "AT_ANCHOR",
                      "STOPPED",
                      "UNKNOWN"
                    ]
                  },
                  {
                    "name": "vessel",
                    "type": "object",
                    "description": "The ship: `imo`, `mmsi`, `name`, `vesselType`, `flag` (ISO alpha-2), `callsign`, `yearBuilt`, `grossTonnage`, `lengthMeters`, `widthMeters` — any can be null."
                  },
                  {
                    "name": "position",
                    "type": "object",
                    "nullable": true,
                    "description": "Latest AIS position: `latitude`, `longitude`, `courseDegrees`, `speedKnots`, `navStatus` and `reportedAt` (the AIS fix, UTC)."
                  },
                  {
                    "name": "destination",
                    "type": "string",
                    "nullable": true,
                    "description": "The destination the crew entered in AIS, as broadcast."
                  },
                  {
                    "name": "destinationPort",
                    "type": "object",
                    "nullable": true,
                    "description": "That destination resolved to a port. Both times are null while the voyage runs; on a completed follow `arrivedAt` is the actual arrival: `name`, `locode`, `countryCode`, `arrivedAt`, `departedAt` (UTC)."
                  },
                  {
                    "name": "eta",
                    "type": "timestamp",
                    "nullable": true,
                    "description": "The vessel’s current ETA there (UTC); null once completed."
                  },
                  {
                    "name": "firstEta",
                    "type": "timestamp",
                    "nullable": true,
                    "description": "The ETA when you started following."
                  },
                  {
                    "name": "etaChangeCount",
                    "type": "integer",
                    "description": "How often the ETA has changed since."
                  },
                  {
                    "name": "delayed",
                    "type": "boolean",
                    "description": "`true` when the ETA is more than 24 hours later than `firstEta`."
                  },
                  {
                    "name": "overdue",
                    "type": "boolean",
                    "description": "`true` when the ETA passed more than 24 hours ago and the vessel is not in port."
                  },
                  {
                    "name": "currentPort",
                    "type": "object",
                    "nullable": true,
                    "description": "The port the vessel is in, with `arrivedAt`: `name`, `locode`, `countryCode`, `arrivedAt`, `departedAt` (UTC)."
                  },
                  {
                    "name": "lastPort",
                    "type": "object",
                    "nullable": true,
                    "description": "The last port it left, with `departedAt`: `name`, `locode`, `countryCode`, `arrivedAt`, `departedAt` (UTC)."
                  },
                  {
                    "name": "customer",
                    "type": "object",
                    "nullable": true,
                    "description": "The customer its credits are attributed to: `{ id, ref, name, countryCode }`."
                  },
                  {
                    "name": "followedBy",
                    "type": "object",
                    "description": "Who started following: `name`, `email` — for API follows, the key’s creator."
                  },
                  {
                    "name": "createdAt",
                    "type": "timestamp",
                    "description": "Followed since (UTC)."
                  },
                  {
                    "name": "completedAt",
                    "type": "timestamp",
                    "nullable": true,
                    "description": "When following ended (UTC)."
                  }
                ]
              },
              "requestExamples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl -X POST \"https://api.navlo.io/v1/vessels/follows/7c1e4a9d-3b6f-4d28-9e05-a2f8c6b1d3e7/complete\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\""
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const res = await fetch('https://api.navlo.io/v1/vessels/follows/7c1e4a9d-3b6f-4d28-9e05-a2f8c6b1d3e7/complete', {\n  method: 'POST',\n  headers: { 'X-API-Key': process.env.NAVLO_API_KEY },\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\nconst follow = await res.json()"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.post(\n    \"https://api.navlo.io/v1/vessels/follows/7c1e4a9d-3b6f-4d28-9e05-a2f8c6b1d3e7/complete\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\nfollow = r.json()"
                }
              ],
              "responseExamples": [
                {
                  "status": 200,
                  "contentType": "application/json",
                  "body": "{\n  \"id\": \"7c1e4a9d-3b6f-4d28-9e05-a2f8c6b1d3e7\",\n  \"status\": \"COMPLETED\",\n  \"state\": \"IN_TRANSIT\",\n  \"vessel\": {\n    \"imo\": \"9734512\",\n    \"mmsi\": \"636019274\",\n    \"name\": \"NORDIC AURORA\",\n    \"vesselType\": \"Container Ship\",\n    \"flag\": \"LR\",\n    \"callsign\": \"D5QK7\",\n    \"yearBuilt\": 2017,\n    \"grossTonnage\": 94511,\n    \"lengthMeters\": 299.9,\n    \"widthMeters\": 48.2\n  },\n  \"position\": {\n    \"latitude\": 13.1048,\n    \"longitude\": 48.7431,\n    \"courseDegrees\": 262.4,\n    \"speedKnots\": 17.2,\n    \"navStatus\": \"Under way using engine\",\n    \"reportedAt\": \"2026-10-22T07:58:00Z\"\n  },\n  \"destination\": \"TR AMR\",\n  \"destinationPort\": {\n    \"name\": \"Ambarli\",\n    \"locode\": \"TRAMR\",\n    \"countryCode\": \"TR\",\n    \"arrivedAt\": null,\n    \"departedAt\": null\n  },\n  \"eta\": \"2026-11-02T04:00:00Z\",\n  \"firstEta\": \"2026-10-31T22:00:00Z\",\n  \"etaChangeCount\": 2,\n  \"delayed\": true,\n  \"overdue\": false,\n  \"currentPort\": null,\n  \"lastPort\": {\n    \"name\": \"Singapore\",\n    \"locode\": \"SGSIN\",\n    \"countryCode\": \"SG\",\n    \"arrivedAt\": null,\n    \"departedAt\": \"2026-10-09T16:20:00Z\"\n  },\n  \"customer\": {\n    \"id\": \"c7d2a9e4-3f1b-4e8a-9b6c-1d5e7f3a2b90\",\n    \"ref\": \"C-1042\",\n    \"name\": \"Acme Trading Ltd.\",\n    \"countryCode\": \"TR\"\n  },\n  \"followedBy\": {\n    \"name\": \"Elif Yılmaz\",\n    \"email\": \"elif.yilmaz@forwarder.example\"\n  },\n  \"createdAt\": \"2026-10-05T09:12:44Z\",\n  \"completedAt\": \"2026-10-22T09:40:00Z\"\n}"
                }
              ],
              "errors": [
                {
                  "status": 404,
                  "message": "Vessel not found",
                  "when": "Unknown or removed follow, or another organization’s."
                },
                {
                  "status": 401,
                  "message": "Invalid or revoked API key",
                  "when": "The X-API-Key header is missing, wrong or revoked."
                },
                {
                  "status": 429,
                  "message": "Rate limit exceeded (60 requests/minute)",
                  "when": "Over the per-key budget; wait Retry-After seconds."
                }
              ],
              "notes": []
            },
            {
              "kind": "endpoint",
              "id": "vessels-delete",
              "method": "DELETE",
              "path": "/v1/vessels/follows/{id}",
              "summary": "Remove a follow",
              "description": [
                "Stops following and removes it from your list. Credits already charged stay in the usage report."
              ],
              "auth": "apiKey",
              "rateLimit": "general",
              "since": "2026-10-22",
              "pathParams": [
                {
                  "name": "id",
                  "type": "uuid",
                  "required": true,
                  "description": "The follow id."
                }
              ],
              "queryParams": [],
              "headers": [],
              "response": {
                "status": 204,
                "contentType": "",
                "description": "No body.",
                "fields": []
              },
              "requestExamples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl -X DELETE \"https://api.navlo.io/v1/vessels/follows/7c1e4a9d-3b6f-4d28-9e05-a2f8c6b1d3e7\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\""
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const res = await fetch('https://api.navlo.io/v1/vessels/follows/7c1e4a9d-3b6f-4d28-9e05-a2f8c6b1d3e7', {\n  method: 'DELETE',\n  headers: { 'X-API-Key': process.env.NAVLO_API_KEY },\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\n// 204 No Content: nothing to parse"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.delete(\n    \"https://api.navlo.io/v1/vessels/follows/7c1e4a9d-3b6f-4d28-9e05-a2f8c6b1d3e7\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\n# 204 No Content: nothing to parse"
                }
              ],
              "responseExamples": [
                {
                  "status": 204,
                  "contentType": "",
                  "body": ""
                }
              ],
              "errors": [
                {
                  "status": 404,
                  "message": "Vessel not found",
                  "when": "Unknown or removed follow, or another organization’s."
                },
                {
                  "status": 401,
                  "message": "Invalid or revoked API key",
                  "when": "The X-API-Key header is missing, wrong or revoked."
                },
                {
                  "status": 429,
                  "message": "Rate limit exceeded (60 requests/minute)",
                  "when": "Over the per-key budget; wait Retry-After seconds."
                }
              ],
              "notes": []
            },
            {
              "kind": "callout",
              "tone": "tip",
              "text": "Tracking containers already shows the vessel they are on: `vessel` on [`GET /v1/shipments/{id}`](/developers/shipments#shipments-get) gives its last position for free. Follow a vessel only when you need the ship itself."
            }
          ]
        },
        {
          "id": "ports-and-airports",
          "title": "Ports & airports",
          "summary": "Port congestion from live AIS, and current airport delays — the data behind the map layers in Navlo Pulse.",
          "blocks": [
            {
              "kind": "prose",
              "text": "The congestion and delay data the app draws on the Navlo Pulse map and uses in its risk scores. These reads are free. When the data is temporarily unavailable you get `200` with `\"available\": false` and empty data — never an error — so a dashboard keeps running."
            },
            {
              "kind": "endpoint",
              "id": "ports-congestion",
              "method": "GET",
              "path": "/v1/ports/congestion",
              "summary": "Port congestion",
              "description": [
                "Current congestion, measured from AIS: vessels at anchor and in port and how long they stay, against each port’s own baseline. By default only the ports your live shipments load at, call at or discharge at — the Pulse map’s set; `scope=all` returns every monitored port. Readings are from the last 36 hours, most congested first."
              ],
              "auth": "apiKey",
              "rateLimit": "general",
              "since": "2026-10-22",
              "pathParams": [],
              "queryParams": [
                {
                  "name": "scope",
                  "type": "enum",
                  "required": false,
                  "description": "`shipments`: ports of your live ocean shipments (empty when you have none). `all`: every monitored port.",
                  "values": [
                    "shipments",
                    "all"
                  ],
                  "defaultValue": "shipments"
                },
                {
                  "name": "country",
                  "type": "string",
                  "required": false,
                  "description": "ISO alpha-2 country, e.g. `TR` (matched on the UN/LOCODE prefix)."
                },
                {
                  "name": "limit",
                  "type": "integer",
                  "required": false,
                  "description": "Maximum ports, 1–500 (values outside are clamped).",
                  "defaultValue": "100"
                }
              ],
              "headers": [],
              "response": {
                "status": 200,
                "contentType": "application/json",
                "fields": [
                  {
                    "name": "available",
                    "type": "boolean",
                    "description": "`false` when congestion data is temporarily unavailable — `ports` is then empty."
                  },
                  {
                    "name": "scope",
                    "type": "enum",
                    "description": "The scope used.",
                    "values": [
                      "shipments",
                      "all"
                    ]
                  },
                  {
                    "name": "ports",
                    "type": "array<object>",
                    "description": "Sorted by level (CRITICAL first), then vessels at anchorage."
                  },
                  {
                    "name": "ports[].locode",
                    "type": "string",
                    "description": "UN/LOCODE."
                  },
                  {
                    "name": "ports[].name",
                    "type": "string",
                    "description": "Port name."
                  },
                  {
                    "name": "ports[].countryCode",
                    "type": "string",
                    "description": "ISO alpha-2 (the LOCODE’s first two letters)."
                  },
                  {
                    "name": "ports[].latitude",
                    "type": "number",
                    "description": "Port centre."
                  },
                  {
                    "name": "ports[].longitude",
                    "type": "number",
                    "description": "Port centre."
                  },
                  {
                    "name": "ports[].congestionLevel",
                    "type": "enum",
                    "description": "Against the port’s own normal.",
                    "values": [
                      "LOW",
                      "MEDIUM",
                      "HIGH",
                      "CRITICAL"
                    ]
                  },
                  {
                    "name": "ports[].calibrating",
                    "type": "boolean",
                    "description": "`true` while the port has under 14 days of baseline — read the level with care."
                  },
                  {
                    "name": "ports[].vesselsAtAnchorage",
                    "type": "integer",
                    "nullable": true,
                    "description": "Vessels waiting at anchor; null where Navlo doesn’t measure the port’s anchorage."
                  },
                  {
                    "name": "ports[].medianWaitHours",
                    "type": "number",
                    "nullable": true,
                    "description": "Median hours vessels wait at anchor; null when none is waiting or the anchorage isn’t measured."
                  },
                  {
                    "name": "ports[].vesselsInPort",
                    "type": "integer",
                    "nullable": true,
                    "description": "Vessels at berth."
                  },
                  {
                    "name": "ports[].medianTimeInPortHours",
                    "type": "number",
                    "nullable": true,
                    "description": "Median hours vessels spend in port."
                  },
                  {
                    "name": "ports[].baselineDays",
                    "type": "integer",
                    "nullable": true,
                    "description": "Days of history behind the port’s normal."
                  },
                  {
                    "name": "ports[].sampledAt",
                    "type": "timestamp",
                    "description": "Time of the reading (UTC)."
                  }
                ]
              },
              "requestExamples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl \"https://api.navlo.io/v1/ports/congestion?scope=shipments\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\""
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const params = new URLSearchParams({ scope: 'shipments' })\n\nconst res = await fetch(`https://api.navlo.io/v1/ports/congestion?${params}`, {\n  headers: { 'X-API-Key': process.env.NAVLO_API_KEY },\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\nconst congestion = await res.json()"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.get(\n    \"https://api.navlo.io/v1/ports/congestion\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    params={\"scope\": \"shipments\"},\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\ncongestion = r.json()"
                }
              ],
              "responseExamples": [
                {
                  "status": 200,
                  "contentType": "application/json",
                  "body": "{\n  \"available\": true,\n  \"scope\": \"shipments\",\n  \"ports\": [\n    {\n      \"locode\": \"GRPIR\",\n      \"name\": \"Piraeus\",\n      \"countryCode\": \"GR\",\n      \"latitude\": 37.9421,\n      \"longitude\": 23.6465,\n      \"congestionLevel\": \"HIGH\",\n      \"calibrating\": false,\n      \"vesselsAtAnchorage\": 14,\n      \"medianWaitHours\": 43.6,\n      \"vesselsInPort\": 9,\n      \"medianTimeInPortHours\": 38.2,\n      \"baselineDays\": 30,\n      \"sampledAt\": \"2026-10-22T07:41:12.345Z\"\n    },\n    {\n      \"locode\": \"TRAMR\",\n      \"name\": \"Ambarli\",\n      \"countryCode\": \"TR\",\n      \"latitude\": 40.9667,\n      \"longitude\": 28.6833,\n      \"congestionLevel\": \"MEDIUM\",\n      \"calibrating\": false,\n      \"vesselsAtAnchorage\": 6,\n      \"medianWaitHours\": 18.5,\n      \"vesselsInPort\": 11,\n      \"medianTimeInPortHours\": 26.4,\n      \"baselineDays\": 30,\n      \"sampledAt\": \"2026-10-22T07:41:12.345Z\"\n    }\n  ]\n}"
                },
                {
                  "status": 200,
                  "label": "Service unavailable",
                  "contentType": "application/json",
                  "body": "{\n  \"available\": false,\n  \"scope\": \"all\",\n  \"ports\": []\n}"
                }
              ],
              "errors": [
                {
                  "status": 400,
                  "message": "scope must be one of: shipments, all",
                  "when": "Another `scope`."
                },
                {
                  "status": 400,
                  "message": "country must be an ISO 3166-1 alpha-2 code, e.g. TR",
                  "when": "A `country` that isn’t two letters."
                },
                {
                  "status": 400,
                  "message": "Invalid value for limit",
                  "when": "`limit` is not a number."
                },
                {
                  "status": 401,
                  "message": "Invalid or revoked API key",
                  "when": "The X-API-Key header is missing, wrong or revoked."
                },
                {
                  "status": 429,
                  "message": "Rate limit exceeded (60 requests/minute)",
                  "when": "Over the per-key budget; wait Retry-After seconds."
                }
              ],
              "notes": []
            },
            {
              "kind": "endpoint",
              "id": "ports-congestion-history",
              "method": "GET",
              "path": "/v1/ports/{locode}/congestion",
              "summary": "Congestion history of a port",
              "description": [
                "One reading per day for a port, oldest first — for trend charts and for judging whether today is unusual."
              ],
              "auth": "apiKey",
              "rateLimit": "general",
              "since": "2026-10-22",
              "pathParams": [
                {
                  "name": "locode",
                  "type": "string",
                  "required": true,
                  "description": "UN/LOCODE of the port, e.g. `GRPIR`."
                }
              ],
              "queryParams": [
                {
                  "name": "days",
                  "type": "integer",
                  "required": false,
                  "description": "Days of history, 1–90 (values outside are clamped).",
                  "defaultValue": "30"
                }
              ],
              "headers": [],
              "response": {
                "status": 200,
                "contentType": "application/json",
                "fields": [
                  {
                    "name": "available",
                    "type": "boolean",
                    "description": "`false` when the history could not be read; `history` is then empty."
                  },
                  {
                    "name": "locode",
                    "type": "string",
                    "description": "UN/LOCODE."
                  },
                  {
                    "name": "name",
                    "type": "string",
                    "description": "Port name."
                  },
                  {
                    "name": "countryCode",
                    "type": "string",
                    "description": "ISO alpha-2."
                  },
                  {
                    "name": "latitude",
                    "type": "number",
                    "description": "Port centre."
                  },
                  {
                    "name": "longitude",
                    "type": "number",
                    "description": "Port centre."
                  },
                  {
                    "name": "days",
                    "type": "integer",
                    "description": "Days covered."
                  },
                  {
                    "name": "history",
                    "type": "array<object>",
                    "description": "Daily readings, oldest first."
                  },
                  {
                    "name": "history[].sampledAt",
                    "type": "timestamp",
                    "description": "Time of the reading (UTC)."
                  },
                  {
                    "name": "history[].congestionLevel",
                    "type": "enum",
                    "description": "Against the port’s own normal.",
                    "values": [
                      "LOW",
                      "MEDIUM",
                      "HIGH",
                      "CRITICAL"
                    ]
                  },
                  {
                    "name": "history[].calibrating",
                    "type": "boolean",
                    "description": "`true` while the port has under 14 days of baseline — read the level with care."
                  },
                  {
                    "name": "history[].vesselsAtAnchorage",
                    "type": "integer",
                    "nullable": true,
                    "description": "Vessels waiting at anchor; null where Navlo doesn’t measure the port’s anchorage."
                  },
                  {
                    "name": "history[].medianWaitHours",
                    "type": "number",
                    "nullable": true,
                    "description": "Median hours vessels wait at anchor; null when none is waiting or the anchorage isn’t measured."
                  },
                  {
                    "name": "history[].vesselsInPort",
                    "type": "integer",
                    "nullable": true,
                    "description": "Vessels at berth."
                  },
                  {
                    "name": "history[].medianTimeInPortHours",
                    "type": "number",
                    "nullable": true,
                    "description": "Median hours vessels spend in port."
                  },
                  {
                    "name": "history[].baselineDays",
                    "type": "integer",
                    "nullable": true,
                    "description": "Days of history behind the port’s normal."
                  }
                ]
              },
              "requestExamples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl \"https://api.navlo.io/v1/ports/GRPIR/congestion?days=3\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\""
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const params = new URLSearchParams({ days: '3' })\n\nconst res = await fetch(`https://api.navlo.io/v1/ports/GRPIR/congestion?${params}`, {\n  headers: { 'X-API-Key': process.env.NAVLO_API_KEY },\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\nconst history = await res.json()"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.get(\n    \"https://api.navlo.io/v1/ports/GRPIR/congestion\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    params={\"days\": \"3\"},\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\nhistory = r.json()"
                }
              ],
              "responseExamples": [
                {
                  "status": 200,
                  "contentType": "application/json",
                  "body": "{\n  \"available\": true,\n  \"locode\": \"GRPIR\",\n  \"name\": \"Piraeus\",\n  \"countryCode\": \"GR\",\n  \"latitude\": 37.9421,\n  \"longitude\": 23.6465,\n  \"days\": 3,\n  \"history\": [\n    {\n      \"sampledAt\": \"2026-10-20T07:38:09Z\",\n      \"congestionLevel\": \"MEDIUM\",\n      \"calibrating\": false,\n      \"vesselsAtAnchorage\": 8,\n      \"medianWaitHours\": 21.4,\n      \"vesselsInPort\": 9,\n      \"medianTimeInPortHours\": 38.2,\n      \"baselineDays\": 30\n    },\n    {\n      \"sampledAt\": \"2026-10-21T07:40:11Z\",\n      \"congestionLevel\": \"HIGH\",\n      \"calibrating\": false,\n      \"vesselsAtAnchorage\": 12,\n      \"medianWaitHours\": 36.8,\n      \"vesselsInPort\": 9,\n      \"medianTimeInPortHours\": 38.2,\n      \"baselineDays\": 30\n    },\n    {\n      \"sampledAt\": \"2026-10-22T07:41:12Z\",\n      \"congestionLevel\": \"HIGH\",\n      \"calibrating\": false,\n      \"vesselsAtAnchorage\": 14,\n      \"medianWaitHours\": 43.6,\n      \"vesselsInPort\": 9,\n      \"medianTimeInPortHours\": 38.2,\n      \"baselineDays\": 30\n    }\n  ]\n}"
                }
              ],
              "errors": [
                {
                  "status": 404,
                  "message": "Port not found",
                  "when": "Navlo doesn’t monitor that port."
                },
                {
                  "status": 400,
                  "message": "locode must be a 5-character UN/LOCODE, e.g. TRAMR",
                  "when": "A malformed `locode`."
                },
                {
                  "status": 400,
                  "message": "Invalid value for days",
                  "when": "`days` is not a number."
                },
                {
                  "status": 401,
                  "message": "Invalid or revoked API key",
                  "when": "The X-API-Key header is missing, wrong or revoked."
                },
                {
                  "status": 429,
                  "message": "Rate limit exceeded (60 requests/minute)",
                  "when": "Over the per-key budget; wait Retry-After seconds."
                }
              ],
              "notes": []
            },
            {
              "kind": "endpoint",
              "id": "airports-delays",
              "method": "GET",
              "path": "/v1/airports/delays",
              "summary": "Airport delays",
              "description": [
                "Average delay and ground stops at the airports Navlo monitors, from readings in the last 3 hours — ground stops first, then the longest delays. The list can be empty when no airport has a current reading."
              ],
              "auth": "apiKey",
              "rateLimit": "general",
              "since": "2026-10-22",
              "pathParams": [],
              "queryParams": [],
              "headers": [],
              "response": {
                "status": 200,
                "contentType": "application/json",
                "fields": [
                  {
                    "name": "available",
                    "type": "boolean",
                    "description": "`false` when delay data is temporarily unavailable; the list is then empty."
                  },
                  {
                    "name": "airports",
                    "type": "array<object>",
                    "description": "One per airport with a recent reading."
                  },
                  {
                    "name": "airports[].iataCode",
                    "type": "string",
                    "description": "IATA code."
                  },
                  {
                    "name": "airports[].name",
                    "type": "string",
                    "nullable": true,
                    "description": "Airport name."
                  },
                  {
                    "name": "airports[].latitude",
                    "type": "number",
                    "nullable": true,
                    "description": "Location."
                  },
                  {
                    "name": "airports[].longitude",
                    "type": "number",
                    "nullable": true,
                    "description": "Location."
                  },
                  {
                    "name": "airports[].delayed",
                    "type": "boolean",
                    "description": "`true` with any average delay or a ground stop."
                  },
                  {
                    "name": "airports[].averageDelayMinutes",
                    "type": "integer",
                    "nullable": true,
                    "description": "Average of departure and arrival delay, in minutes."
                  },
                  {
                    "name": "airports[].groundStop",
                    "type": "boolean",
                    "description": "`true` while departures are held."
                  },
                  {
                    "name": "airports[].groundStopReason",
                    "type": "string",
                    "nullable": true,
                    "description": "The reason given for the ground stop."
                  },
                  {
                    "name": "airports[].sampledAt",
                    "type": "timestamp",
                    "description": "Time of the reading (UTC)."
                  }
                ]
              },
              "requestExamples": [
                {
                  "lang": "curl",
                  "label": "cURL",
                  "code": "curl \"https://api.navlo.io/v1/airports/delays\" \\\n  -H \"X-API-Key: $NAVLO_API_KEY\""
                },
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "const res = await fetch('https://api.navlo.io/v1/airports/delays', {\n  headers: { 'X-API-Key': process.env.NAVLO_API_KEY },\n})\nif (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)\nconst delays = await res.json()"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "import os\nimport requests\n\nr = requests.get(\n    \"https://api.navlo.io/v1/airports/delays\",\n    headers={\"X-API-Key\": os.environ[\"NAVLO_API_KEY\"]},\n    timeout=30,\n)\nif not r.ok:\n    raise RuntimeError(f\"Navlo {r.status_code}: {r.json()['message']}\")\ndelays = r.json()"
                }
              ],
              "responseExamples": [
                {
                  "status": 200,
                  "contentType": "application/json",
                  "body": "{\n  \"available\": true,\n  \"airports\": [\n    {\n      \"iataCode\": \"AMS\",\n      \"name\": \"Amsterdam Airport Schiphol\",\n      \"latitude\": 52.3086,\n      \"longitude\": 4.7639,\n      \"delayed\": true,\n      \"averageDelayMinutes\": 34,\n      \"groundStop\": false,\n      \"groundStopReason\": null,\n      \"sampledAt\": \"2026-10-22T08:05:00Z\"\n    },\n    {\n      \"iataCode\": \"IST\",\n      \"name\": \"Istanbul Airport\",\n      \"latitude\": 41.2753,\n      \"longitude\": 28.7519,\n      \"delayed\": false,\n      \"averageDelayMinutes\": 0,\n      \"groundStop\": false,\n      \"groundStopReason\": null,\n      \"sampledAt\": \"2026-10-22T08:05:00Z\"\n    }\n  ]\n}"
                }
              ],
              "errors": [
                {
                  "status": 401,
                  "message": "Invalid or revoked API key",
                  "when": "The X-API-Key header is missing, wrong or revoked."
                },
                {
                  "status": 429,
                  "message": "Rate limit exceeded (60 requests/minute)",
                  "when": "Over the per-key budget; wait Retry-After seconds."
                }
              ],
              "notes": []
            },
            {
              "kind": "heading",
              "id": "ports-usage",
              "title": "Using it"
            },
            {
              "kind": "list",
              "ordered": false,
              "items": [
                "Warn about shipments heading into a congested port: match `ports[].locode` against `containers[].destination.code` on your shipments — `scope=shipments` already narrows the list to those ports.",
                "Navlo already folds congestion into each shipment’s [risk](/developers/shipment-intelligence#intelligence-risk) and [Navlo ETA](/developers/shipment-intelligence#intelligence-navlo-eta) — read those when you want the conclusion rather than the raw reading.",
                "Readings change slowly; caching them for 15 minutes loses nothing."
              ]
            }
          ]
        }
      ]
    },
    {
      "id": "reference",
      "title": "Reference",
      "pages": [
        {
          "id": "statuses-and-time-zones",
          "title": "Statuses & time zones",
          "summary": "What each status and milestone code means, and how to read the timestamps — carrier times are local to the port.",
          "blocks": [
            {
              "kind": "heading",
              "id": "statuses-shipment",
              "title": "Shipment status"
            },
            {
              "kind": "definitions",
              "items": [
                {
                  "term": "`discovering`",
                  "description": "Navlo is finding the carrier and the first data. A shipment without carrier data yet stays here while Navlo keeps trying."
                },
                {
                  "term": "`resolving`",
                  "description": "The carrier is known and the first full data set is being built."
                },
                {
                  "term": "`active`",
                  "description": "Tracked and refreshed on Navlo’s polling schedule."
                },
                {
                  "term": "`tracking`",
                  "description": "air only: the waybill was accepted and Navlo is fetching the airline's first data. It becomes `active` when that data arrives (or `discovering` if no airline has it yet). A new air shipment's create response usually says `tracking`. List, export and report filters treat it as `active`."
                },
                {
                  "term": "`completed`",
                  "description": "Finished — delivered, or the empty container returned. Polling has ended."
                },
                {
                  "term": "`stopped`",
                  "description": "Navlo can’t track this identifier — an unsupported carrier, or a number no carrier recognises. Polling has ended."
                }
              ]
            },
            {
              "kind": "list",
              "ordered": false,
              "items": [
                "The usual path is `discovering` → `resolving` → `active` → `completed`; air waybills go `tracking` → `active` → `completed`.",
                "There is no failed status. An identifier that hasn’t resolved stays `discovering` while Navlo keeps trying — and if it never resolves, the credit is refunded and tracking stops.",
                "Pausing with [`/stop`](/developers/shipments#shipments-stop) doesn’t change `status`; it only halts polling (`details.pollingStoppedAt`)."
              ]
            },
            {
              "kind": "heading",
              "id": "statuses-milestones",
              "title": "Milestone codes"
            },
            {
              "kind": "prose",
              "text": "`containers[].status`, `events[].status`, `airShipments[].status` and webhook `details.milestone.code` use Navlo’s milestone codes — the same codes for every carrier. The list grows as carriers add events: show `name` (or the carrier’s own text) for codes you don’t recognise."
            },
            {
              "kind": "definitions",
              "items": [
                {
                  "term": "`EMPTY_CONTAINER`",
                  "description": "Empty pickup or release. Phase `PRE_SHIPMENT`."
                },
                {
                  "term": "`GATE_IN`",
                  "description": "Container entered the origin terminal. `ORIGIN`."
                },
                {
                  "term": "`EXPORT_PROCESSING`",
                  "description": "Export received, ready to load. `ORIGIN`."
                },
                {
                  "term": "`LOADED`",
                  "description": "Loaded on the vessel or transport. `TRANSIT`."
                },
                {
                  "term": "`DEPARTED`",
                  "description": "Vessel, flight or transport left. `TRANSIT`."
                },
                {
                  "term": "`IN_TRANSIT`",
                  "description": "Moving between locations. `TRANSIT`."
                },
                {
                  "term": "`TRANSSHIPMENT`",
                  "description": "At an intermediate port. `TRANSIT`."
                },
                {
                  "term": "`ARRIVED`",
                  "description": "Vessel, flight or transport arrived. `DESTINATION`."
                },
                {
                  "term": "`DISCHARGED`",
                  "description": "Unloaded from the vessel. `DESTINATION`."
                },
                {
                  "term": "`IMPORT_PROCESSING`",
                  "description": "Import positioning, customs. `DESTINATION`."
                },
                {
                  "term": "`READY_FOR_DELIVERY`",
                  "description": "Available for pickup. `DESTINATION`."
                },
                {
                  "term": "`GATE_OUT`",
                  "description": "Left the destination terminal for delivery. `DESTINATION`."
                },
                {
                  "term": "`DELIVERED`",
                  "description": "Final delivery done. `COMPLETED`."
                },
                {
                  "term": "`BOOKED`",
                  "description": "AIR: booked on a flight. `PRE_SHIPMENT`."
                },
                {
                  "term": "`RECEIVED_FROM_SHIPPER`",
                  "description": "AIR: cargo accepted by the airline. `ORIGIN`."
                },
                {
                  "term": "`CONSIGNEE_NOTIFIED`",
                  "description": "AIR: consignee told the cargo is ready. `DESTINATION`."
                },
                {
                  "term": "`PARTIALLY_DELIVERED`",
                  "description": "AIR: some pieces of a split consignment delivered. `DESTINATION`."
                }
              ]
            },
            {
              "kind": "prose",
              "text": "The phase (`PRE_SHIPMENT`, `ORIGIN`, `TRANSIT`, `DESTINATION`, `COMPLETED`) is also what [email subscribers](/developers/shipment-actions#actions-subscribers) choose their events by."
            },
            {
              "kind": "heading",
              "id": "statuses-time-zones",
              "title": "Time zones"
            },
            {
              "kind": "list",
              "ordered": false,
              "items": [
                "**System times are UTC** — `createdAt`, `recordedAt`, `computedAt`, `occurredAt` and every other time Navlo itself records. They end in `Z` and mean it.",
                "**Carrier times are local to the place** — ETD, ATD, ETA, ATA, event timestamps, flight times and `details.eventAt` carry the wall-clock time at the port or airport, written with a `Z` suffix. Display them exactly as they are, without converting to the viewer’s time zone: a departure from Shanghai at 03:40 local reads `2026-09-27T03:40:00Z` and should show as 03:40.",
                "Air times are airport-local too.",
                "For arithmetic across zones (transit time), the [embed payload](/developers/embed) also carries the four schedule times as true UTC instants (`…Utc` fields); don’t display those.",
                "Dates without a time (`YYYY-MM-DD` in the usage report) are UTC days."
              ]
            },
            {
              "kind": "code",
              "samples": [
                {
                  "lang": "node",
                  "label": "Node.js",
                  "code": "// Show a carrier time as written: read it as UTC so nothing shifts it.\nconst eta = new Date('2026-10-30T06:00:00Z')\nconst label = eta.toLocaleString('en-GB', { timeZone: 'UTC', dateStyle: 'medium', timeStyle: 'short' })\n// → \"30 Oct 2026, 06:00\" — 06:00 at Ambarli, wherever the viewer is"
                },
                {
                  "lang": "python",
                  "label": "Python",
                  "code": "from datetime import datetime\n\n# Show a carrier time as written: drop the \"Z\" instead of converting it.\neta = datetime.fromisoformat(\"2026-10-30T06:00:00Z\".replace(\"Z\", \"\"))\nprint(eta.strftime(\"%d %b %Y, %H:%M\"))  # 30 Oct 2026, 06:00 — local time at Ambarli"
                }
              ]
            },
            {
              "kind": "heading",
              "id": "statuses-other-values",
              "title": "Other values"
            },
            {
              "kind": "definitions",
              "items": [
                {
                  "term": "`events[].type`",
                  "description": "`ACTUAL` happened · `EXPECTED` carrier projection · null when unknown."
                },
                {
                  "term": "`vessel.source`",
                  "description": "`LIVE` fresh fix · `STALE` old fix of the same ship · `LAST_KNOWN` last port, not a ship."
                },
                {
                  "term": "`risk.level`",
                  "description": "`LOW` · `MEDIUM` · `HIGH` · null when stale or unknown."
                },
                {
                  "term": "`mode`",
                  "description": "`OCEAN` · `AIR`"
                },
                {
                  "term": "`etaHistory[].field`",
                  "description": "`ETA` · `ETD` · `ATA` · `ATD`"
                }
              ]
            }
          ]
        },
        {
          "id": "openapi-and-postman",
          "title": "OpenAPI & Postman",
          "summary": "A machine-readable description of the whole API, generated from the code — import it into Postman or generate a client.",
          "blocks": [
            {
              "kind": "definitions",
              "items": [
                {
                  "term": "OpenAPI 3",
                  "description": "[`https://api.navlo.io/v1/openapi.json`](https://api.navlo.io/v1/openapi.json) — no key needed."
                },
                {
                  "term": "Postman collection",
                  "description": "[`navlo-api.postman_collection.json`](https://app.navlo.io/developers/navlo-api.postman_collection.json)"
                },
                {
                  "term": "These docs as JSON",
                  "description": "[`developer-docs.json`](https://app.navlo.io/developers/developer-docs.json) — every page, endpoint and example."
                }
              ]
            },
            {
              "kind": "prose",
              "text": "The OpenAPI 3.1 document is generated from the API’s own code on every release, so it can’t drift from what the API does. It covers every `/v1` endpoint and `GET /api/embed/resolve`, with the `ApiKeyAuth` (`X-API-Key`) and `EmbedKeyAuth` (`X-Embed-Key`) security schemes, and describes the seven webhook events under `webhooks`."
            },
            {
              "kind": "heading",
              "id": "openapi-postman",
              "title": "Postman"
            },
            {
              "kind": "list",
              "ordered": true,
              "items": [
                "Download the collection and import it (**File → Import**).",
                "Open the collection’s **Variables** and set `apiKey` to your `nvl_…` key (and `embedKey` for the embed request). `baseUrl` is `https://api.navlo.io`.",
                "Requests are grouped by area — Shipments, Webhooks, Navlo AI… — with path variables ready to fill in."
              ]
            },
            {
              "kind": "heading",
              "id": "openapi-clients",
              "title": "Generating a client"
            },
            {
              "kind": "code",
              "samples": [
                {
                  "lang": "curl",
                  "label": "Shell",
                  "code": "# TypeScript (fetch)\nnpx @openapitools/openapi-generator-cli generate \\\n  -i https://api.navlo.io/v1/openapi.json -g typescript-fetch -o ./navlo-client\n\n# Python\nnpx @openapitools/openapi-generator-cli generate \\\n  -i https://api.navlo.io/v1/openapi.json -g python -o ./navlo-client-python"
                }
              ]
            },
            {
              "kind": "callout",
              "tone": "tip",
              "text": "Generated clients deserialise strictly by default. Turn on “ignore unknown properties” (or its equivalent) so new response fields never break you — see the [Compatibility promise](/developers/compatibility)."
            },
            {
              "kind": "callout",
              "tone": "info",
              "text": "Streamed Navlo AI answers are not a request/response shape OpenAPI describes well: the [Navlo AI](/developers/navlo-ai#ai-events) page documents every event. Webhook payloads are in the document’s `webhooks` section and on the [Webhooks](/developers/webhooks#webhooks-payload) page."
            }
          ]
        },
        {
          "id": "changelog",
          "title": "Changelog",
          "summary": "What changed in the API, newest first. Every change to `/v1` is additive.",
          "blocks": [
            {
              "kind": "heading",
              "id": "changelog-2026-10-22",
              "title": "22 October 2026"
            },
            {
              "kind": "prose",
              "text": "The API now does what the app does. Requests without the new parameters answer exactly as before. The old `data` block in webhook payloads is deprecated: it is still sent until 16 November 2026, then removed."
            },
            {
              "kind": "list",
              "ordered": false,
              "items": [
                "**Customers on requests** — `customer` (`{ \"ref\", \"name\" }` or `{ \"id\" }`) on `POST /v1/shipments`, batch items, Navlo AI and vessel follows; `PATCH /v1/shipments/{id}`; the [Customers API](/developers/customers).",
                "**Shipment list** — filters (`status`, `mode`, `carrier`, `customerId`, `customerRef`, `tag`, `risk`, ETA and creation ranges, `updatedSince`), `sort` and `include`.",
                "**Shipment intelligence** — `include=` on the detail: risk, recommendations, Navlo ETA, D&D, carbon, route alerts, customer, tags, details.",
                "**Shipment actions** — notes, documents, share links, email subscribers, mute, complete, change carrier; the [Tags API](/developers/tags).",
                "**Reports & export** — CSV/XLSX export and `POST /v1/reports`.",
                "**Usage & credits** — `GET /v1/credits` and `GET /v1/usage` (JSON or CSV, per customer, shipment or day) for re-billing.",
                "**Navlo AI** — `POST /v1/ai/ask` and conversations, streaming by default.",
                "**Webhooks** — managed over the API (list, read, create, update, rotate, delete, deliveries, test events), a `shipment` snapshot with mode, status, carrier, customer, route, ETA and vessel, a fixed `details` object per topic (the old `data` block is deprecated and goes away on 16 November 2026), and the events in the OpenAPI document — every topic, `shipment.discovery_finished` included, fires for ocean and air shipments.",
                "**Vessels, ports & airports** — vessel follows, port congestion and airport delays.",
                "**Embed** — `GET /api/embed/resolve` answers only what the tracking box shows; ids are positions in the answer (`c1`, `c1-e1`).",
                "**Errors and limits** — every error body has `message`; `X-RateLimit-*` headers on every response; Navlo AI has its own 10-a-minute budget and runs at most 2 answers at once per organization; bodies over 1 MB (uploads over 10 MB) answer `413`; the tracking widget allows 60 lookups a minute per key; an organization has at most 10 live keys and emails at most 500 share recipients per 24 hours ([caps per organization](/developers/rate-limits#rate-limits-organization)).",
                "**Statuses** — the air-only `tracking` status is [documented](/developers/statuses-and-time-zones#statuses-shipment); list, export and report filters treat it as `active`.",
                "**OpenAPI & Postman** — `GET /v1/openapi.json` and a Postman collection."
              ]
            },
            {
              "kind": "heading",
              "id": "changelog-2026-10-07",
              "title": "7 October 2026"
            },
            {
              "kind": "list",
              "ordered": false,
              "items": [
                "A blank `identifier` is rejected with `400 identifier must not be blank`."
              ]
            },
            {
              "kind": "heading",
              "id": "changelog-2026-09-22",
              "title": "22 September 2026"
            },
            {
              "kind": "list",
              "ordered": false,
              "items": [
                "Air shipments on the detail: `airShipments[]` with flights, air events with `flight`, `pieces` and `weight`, and air legs on the route.",
                "`mode` is required on create; an unambiguous identifier (container number, AWB with a valid check digit) wins over the value sent."
              ]
            },
            {
              "kind": "heading",
              "id": "changelog-2026-08-22",
              "title": "22 August 2026"
            },
            {
              "kind": "list",
              "ordered": false,
              "items": [
                "`GET /v1/shipments/{id}/route` (GeoJSON), `POST …/stop`, `POST …/resume` and `DELETE /v1/shipments/{id}`.",
                "`etaHistory` and `vessel` on the shipment detail.",
                "Webhooks."
              ]
            },
            {
              "kind": "heading",
              "id": "changelog-2026-08-04",
              "title": "4 August 2026"
            },
            {
              "kind": "list",
              "ordered": false,
              "items": [
                "Rate limit raised from 20 to 60 requests a minute per key."
              ]
            },
            {
              "kind": "heading",
              "id": "changelog-2026-08-01",
              "title": "1 August 2026"
            },
            {
              "kind": "list",
              "ordered": false,
              "items": [
                "The API launches: start tracking (single and batch), shipment list and detail, and the embed widget."
              ]
            }
          ]
        }
      ]
    }
  ]
}
