API Reference

SeaRates-compatible API

A compatibility layer over the same core as the v1 API below. It accepts SeaRates' request shape and answers in their response shape, so a client already written against them moves across without being rewritten.

It is a migration path, not a second product: it covers tracking only, and a new integration should use v1.

Open the SeaRates-compatible docs

All endpoints

Every v1 path, relative to the base URL, with a Bearer key — except the sandbox, which needs none.

Try it — live sandbox

Run a real request now — no key, no sign-up. Every v1 endpoint has a copy under /api/v1/sandbox with a schema-identical reply, so what you build here works live. Every endpoint on this page is in the box, grouped as in the sidebar.

Schema, not contents. Keys, types and error bodies match live; values are a sample, so a name, a region or a row count can differ. Having no account, it cannot show two things: a plan refusal on congestion or disruptions (always 200 here) and a re-minted share link (201, never 200 with created: false).

What you get

Capped at 60 requests a minute per IP, with the same X-RateLimit-* headers as live — so you can test your back-off here.

Magic references — build your error handling first

Errors are the hard part to test — a 402 only happens when a customer outgrows their plan. These reserved references return each error with the real production body.

They work on /container, /bl and per item inside POST /track.

Receive a real webhook, before you have an account

A webhook receiver normally cannot be tested until a real shipment moves. Name a URL and get one delivery now:

curl -X POST "https://traqocontainer.com/api/v1/sandbox/webhooks/fire" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://your-server.example.com/hooks", "event": "eta.changed" }'

Signed by the same code production uses, with a one-time secret in the reply so you can check it. Nothing is saved. 5 a minute; the target must be a public https URL.

Webhook event payloads

Every delivery has the same envelope — { event, created, data } — so branch on event, not on the shape:

{
  "event": "eta.changed",
  "created": 1787654321,
  "data": {
    "shipment_id": "SHP-1042",
    "reference_number": "MRSU6859427",
    "carrier": "MAEU",
    "status": "IN_TRANSIT",
    "previous_status": "IN_TRANSIT",
    "eta": "2026-09-13T00:00:00.000Z",
    "previous_eta": "2026-09-08T00:00:00.000Z",
    "ata": null
  }
}

Authentication

Send your API key as a Bearer token in the Authorization header. Generate and manage keys in the Developer section of your dashboard.

What every request needs

Both apply to every endpoint below, so they are not repeated on each one.

Base URL

All endpoints are relative to the following base URL:

Postman & OpenAPI

Two ready-made files, both public — no key needed.

Postman collection

Every endpoint, pre-built. Import, set the apiKey variable, run. Generated from the OpenAPI document below, so it never drifts.

Download the collection — or in Postman: Import → Link, and paste the URL above.

OpenAPI 3.1 specification

Feed it to openapi-generator, orval, Swagger UI or Redoc for a typed client. Covers the webhook payloads too.

Open the spec — or point your generator straight at the URL so a regenerated client tracks our changes.

Errors

All error responses return JSON with a consistent structure:

A 402 carries a data object. data.error of "payment_overdue" means a payment failed and the grace period is over — fix billing at data.manageUrl to start again. Shipments you already have are unaffected:

Shipment limits

Two separate limits: how many requests a key may make (API rate limits), and how many shipments your plan allows.

Your shipment limit is an intake allowance, not a ceiling on how many you hold at once: it counts what you add this cycle. Older shipments keep tracking free until delivered.

API rate limits

Each API key gets 120 requests per minute by default, counted in a fixed one-minute window. Your key's own limit is in the headers below.

Vessel & schedule lookups

GET /vessel/track and GET /voyage/schedules reach an external provider, so they share a daily allowance per key, on top of the per-minute limit. A repeat lookup served from cache does not count against it.

Over it you get a 429 carrying lookup_limit_exceeded, with X-Lookup-Limit, X-Lookup-Remaining and X-Lookup-Reset — its own header family, because it is its own budget and backing off for a minute would be the wrong wait.

Every response carries your current budget, so you never have to guess:

Go over and you get a 429 with a Retry-After. Wait that many seconds — trying sooner just costs you another 429:

Response times

Three classes of endpoint, and they are nothing like each other. Budget for the right one:

Measured from real successful requests over the last 30 days, not a target.

External means someone we call for you, not a carrier tracking a box; /voyage/schedules is the slowest endpoint on the API. Both save good answers — "cached": true — for 5 minutes (vessel position) and 30 minutes (sailing schedule).

Try any of them without a key — the live sandbox above runs real requests against real references.

Track a container

Full tracking data for a container — status, route, ETA, port events, vessels. The shipment is saved to your account in the background.

Parameters

Sending sealine

The carrier actually used comes back as carrier.sealine. Don't know it? /carriers/lookup resolves it free, with no shipment created.

Send a code we don't list and we ignore it and detect the carrier ourselves — you get the shipment, and carrier.sealine tells you who answered. A missing carrier is a gap in our directory, not a mistake in your request, so it never costs you a call. A code that isn't four characters is still rejected: that one is a malformed request.

Container equipment

Every containers_table row has these three keys. They are always there and may be null — null means "the carrier did not supply it", never "no equipment".

container_summary (2×40HC, 1×20GP) counts only boxes whose type we know, so it can add up to fewer than the table holds.

No "return to port by" date. Carriers publish free days, not a deadline, so no field carries one. The dashboard's detention & demurrage estimate is not exposed on this API, and is not a date to invoice against.

Track a bill of lading

Full tracking data for a BL. Same response shape as /container; saved to your account in the background.

Parameters

Container equipment fields behave exactly as on /container.

Bulk track shipments

Up to 50 containers or BLs per request. New shipments cost a slot each; ones you already track are free.

Request body

List tracked shipments

A paginated list of every shipment on your account — containers and bills of lading — with current status, route and ETA.

Query parameters

Get a shipment

Where a shipment you already track stands right now, from stored data. Never calls the carrier, never uses a slot — poll this one.

Case, spaces and hyphens are ignored.

ata is when the vessel arrived at the final port of discharge — null until it has, and never a transshipment call. status is the carrier's status for the whole journey and still reads IN_TRANSIT after arrival. Same field on /shipments, /container and /bl.

customers: names, [] if none. Also on /shipments; set via PATCH.

Re-reading the stored document

Add ?include=full for a document of the tracking tables we hold (events_table, containers_table, vessels_table, locations_table, voyage_plan_table, route_json, last position), plus cached_at and mode: "stored".

Nothing cached yet? You get document: null, cached_at: null and a hint. One /container or /bl call populates it; every later read is local.

When predictive ETA is enabled for your plan, the data object also carries predictive_eta and demurrage_risk — see Predictive ETA. Always carries terminal.

Predictive ETA

With predictive ETA on, /api/v1/container/:number adds a predictive_eta object: p50 and p80 times, a source (model / blend / carrier), a confidence (high / medium / low) and computed_at. It uses vessel progress and port congestion, so it beats an old carrier ETA.

Terminal record

data.terminal on Get a shipment.

• Same data as the Terminal card
• One item per box and terminal
• "found": all facts and events
• "finding": still checking, no facts
• null: nothing for this shipment
• Terminal's own keys, snake_case
• Blank hold: absent, not released
• Over 24h: current facts dropped
• Read error: terminal: null

Retry failed shipments

Retry every shipment that failed in the last 7 days, in one call. Nothing is fetched while you wait — read GET /api/v1/shipments/:id for the result.

Body (optional)

Send nothing to retry everything. Send { "shipment_ids": ["SHP-00000044"] } to retry only those — ids outside your organisation are ignored.

Response

examined is how many failed rows matched; queued is how many jobs started. They differ when your plan has no carrier discovery, and the gap shows as skipped.

Capped at 200 references per call, and one call per organisation every 15 minutes. The work is asynchronous, so calling it again sooner adds nothing.

Correct a shipment

Fixes the carrier or type of a shipment you already track, then tracks it again, and sets its customer. Every field is optional, at least one is needed, and anything you leave out keeps its stored value.

Only for shipments this key's own user added: a teammate's shipment reads 200 on GET and answers 404 here.

The same as editing a shipment in the dashboard: it moves a reference you already track to another carrier, which ?sealine= on a first add cannot do.

Body

reference_number: refused, 400.

The customer

• {"customer": "Acme GmbH"} sets it
• Matches name, any case
• No match: creates the customer
• Replaces, never adds
• null or "" clears it
• Alone or with carrier
• Reads return customers (names)

• View-only key: 403
• Plan without customers: 403
• Customer limit reached: 422

When the carrier still finds nothing

Not an error: 200 with still_failed: true means the row was saved and we are still looking for the carrier — poll GET /shipments/:id. Sending the same values back answers unchanged: true.

Untrack a shipment

Removes a shipment from your account, like removing it from the dashboard. A soft delete: it leaves /api/v1/shipments and stops updating.

Only for shipments this key's own user added: a teammate's shipment reads 200 on GET and answers 404 here.

:id is the container or BL number, or the shipment id — which to prefer, and why.

Response

shipment_id is the real id of the row you untracked — not what you sent, if you used a container or BL number.

Create a public tracking link

Creates a branded /s/<token> link your customer can open with no account and no login — straight from your own system.

Idempotent

Ask twice and you get the same link back — same URL, created: false, 200. A brand new one answers 201. True however you name the shipment, so one box never gets two links. Shared with the dashboard.

:id is the container or BL number, or the shipment id — which to prefer, and why.

Response

Revoke the link

The link stops working on the next request, and you can make a new one later. Already revoked, never shared and just revoked all return the same body — telling them apart would reveal whether a link ever existed.

:id is the container or BL number, or the shipment id — which to prefer, and why.

Your quota and billing cycle

Check this instead of finding your limit by hitting it — so you can warn your team, or buy slots, before tracking stops.

Notes

• used counts distinct references tracked this cycle. A reference you later untrack still counts — deleting does not return the slot.
• On a yearly plan the cycle is the year and the shipment numbers are pool numbers for that year. Read period_days (30 vs 365) to tell which shape you are holding rather than inferring it from the dates.
• rate_limit is the per-minute window and mirrors the X-RateLimit-* headers on the same response. There is no daily API quota, so none is reported.
• Both 402 bodies carry usageApi: "/api/v1/account/usage", so a client that does hit the wall is pointed straight at the endpoint that would have prevented it.

Track a vessel

Returns real-time AIS position, speed, heading, and voyage information for a vessel. Both imo (7 digits) and mmsi (9 digits) are required.

Query parameters

Voyage schedules

Returns sailing schedules between two ports for a given date, across available carriers.

Query parameters

Port congestion

The latest congestion score for a port (UN/LOCODE) plus 90 days of history: a 0–100 score, a bucket (fluid / normal / moderate / high / critical), a data-sufficiency tier (A/B/C), a 7-day trend, and per-signal components (dwell, anchorage wait, ETA-slip, schedule deviation, bunching) with raw value, baseline and z-score.

Two fields answer the question people actually ask without reading components: median_anchorage_wait_h, the hours a ship waits at anchor for a berth, and longest_wait_days, how long the longest-waiting vessel has been there. Either is null — never 0 — when we hold no reading.

Reads Traqo's own analytics — no upstream call, so it never consumes a shipment slot.

Congestion board

Every scored port in one call — the same score / bucket / tier, plus trend_7d, vessels_waiting (ships waiting at the port right now), computed_at and coordinates. Build a map or watchlist without polling port by port.

Readings are not all equally fresh — about half the board is recomputed inside any 24 hours — so check computed_at before treating a port as current.

Same gating as Port congestion, and 200 in the sandbox either way. Reads Traqo's own analytics — no upstream call, no shipment slot.

Search ports

Resolves a UN/LOCODE, port name or city to canonical metadata (locode, name, city, country, region, coordinates) — how free-text origin/destination becomes the locodes congestion and schedules expect. Local read.

Query parameters

List disruptions

Published port and trade disruptions — strikes, port closures, canal and chokepoint delays, weather, surcharges — most severe first. Active events by default; status=resolved lists the ones that are over. Each has a severity from 1 (info) to 4 (critical), the entities it names (ports, carriers, countries, chokepoints), and the publishers that reported it.

Every event is classified before it is published, and anything at severity 3 or above is verified first. The headline and summary are ours; sources are the publishers' names and links, never their text.

Query parameters

Filters combine with AND. A bad value gets 400 with data.error: "invalid_parameter" and data.param naming it — checked before your plan, so a typo is never mistaken for a subscription problem.

Reads Traqo's own data — no upstream call, no shipment slot.

Get a disruption

One published disruption, by the id from List disruptions, in the same shape. Useful for re-checking one event you are already showing — whether it has resolved, or picked up new sources.

Disruptions on a shipment

The active disruptions touching one shipment in your account — up to ten, most severe first — and how each reaches it. match_types says why: pol / pod (its port of loading or discharge), transship, carrier, lane_interest or country.

:id is the shipment id or the container / bill-of-lading number, as on Get a shipment.

Resolve the carrier for a reference

Which carrier moves a container or BL, without tracking it — no shipment, no write, no slot.

Query parameters

Confidence

Some sources are stronger than others, so every candidate carries a confidence — the difference between a value you can act on and one to check first.

“We don’t know” vs “we couldn’t ask”

Both look like carrier: null but need opposite handling. sources_unavailable lists sources that failed or took longer than 3 seconds — empty is healthy.

Two rules worth coding against

• carrier is null iff candidates is empty. No confidence floor — a low winner is still returned. Want only strong answers? Filter on confidence yourself.
• candidates is always an array — never null, never absent, possibly empty.

Limits

A daily cap per key (default 1,000), separate from the per-minute limit, because each new reference triggers several lookups.

Over the cap you get a 429 saying when it lifts. Use the error code to tell it from the per-minute limit, which says rate_limit_exceeded and clears within the minute:

List supported carriers

Every ocean carrier Traqo can track, with its 4-character scac and name — the value you pass as the optional sealine. Local read, never spends a slot.

Query parameters

Webhooks

Instead of polling, we POST events to your server as they happen — a status or ETA change, or carrier discovery recovering a failed shipment. Register endpoints on the Webhooks tab.

Every delivery is a JSON POST with the same envelope — an event name, a created unix timestamp (seconds), and an event-specific data object:

Request headers

Delivery & retries

Reply 2xx within 10 seconds — say yes first, do the work after. Anything else is retried with a growing wait (≈30s, 1m, 2m, 4m … up to 6h) until we give up and mark it failed.

Webhook events

Subscribe an endpoint to any of these events, or to * for all of them.

The four shipment events share the data shape shown in the envelope above (status/previous_status carry the transition; eta/previous_eta the ETA move; ata the vessel's arrival at the final port, null until then). discovery.recovered carries the recovered carrier:

Verifying signatures

Every delivery is signed, so you can be sure it came from Traqo and nobody changed it. The X-Traqo-Signature header holds a timestamp and a signature:

v1 is the HMAC-SHA256, lowercase hex, of <t>.<raw body>, keyed with your signing secret (whsec_…, shown once). Recompute, compare in constant time, and reject any t over 300s old.

MCP server

Traqo Ocean provides a remote MCP server at https://traqocontainer.com/api/mcp; authenticate with your Traqo API key. Point Claude, ChatGPT, Cursor or any Model Context Protocol client at it and ask about your shipments in plain language — the model reads your live data instead of guessing.

It is read-only. Nothing here adds, edits, deletes or refreshes anything, so a model cannot spend a slot, change a shipment or open a ticket. Same key, same developer-mode requirement and same per-minute rate limit as the REST API above — one key, one set of rules, whichever way you reach us.

Three limits worth knowing before you write the client. A batch holds at most 20 messages; a longer one is refused whole rather than answered in part. track_vessel and get_vessel_schedules reach the same provider as GET /vessel/track and GET /voyage/schedules, so they draw on the same daily allowance per key — one pool, whichever surface you call from. And tool output is additive only: a key may appear, never vanish or change name, and every change is listed in the changelog against a server version.

Before you start

1. An API key, from Dashboard → Developer. The same one the REST API uses — nothing new is issued.
2. Developer mode on for your account, on that same page. Without it every call answers 403.
3. A client that speaks MCP. Claude Desktop, Claude Code, Cursor and Windsurf all do; anything else can bridge with mcp-remote.

Connect

Streamable HTTP, stateless — there is no install and nothing to run. Paste the block on the right into your client's config, replace YOUR_API_KEY, and restart the client: none of them re-read that file while running, which is the single most common reason a correct config appears to do nothing.

Then ask it something

Once it is connected, these are questions it can answer from your own account:

• “Which of my containers are late, and by how long?”
• “Where is MSKU1234567 and when does it land?”
• “Any of my shipments running out of free days this week?”
• “How bad is Rotterdam right now, and does it affect anything I have moving?”
• “Summarise everything arriving in the next seven days for my customer Acme.”
• “What sails from Shanghai to Hamburg in the next three weeks?”

The tools

21 tools, all read-only, every one scoped to your own organisation — no tool takes an account, organisation or user id, so a model cannot express a request for somebody else's data. Your client calls these for you; you never name one.

When it does not work

What it will not do

No writes of any kind: no adding, editing, deleting, sharing or refreshing a shipment, and no raising a ticket. No billing — invoices, plans and usage are not on this surface. No staff data, whoever holds the key. And no carrier calls, so a model cannot spend your daily lookup allowance by asking repeatedly.

What’s new

Newest first. Every change is additive except the one row marked breaking — ignore fields you don’t know and pick up the rest at your own pace.