Wakepoint API

One REST API for the entire ocean. Track containers across 120+ carriers, register webhooks for milestone changes, and query your fleet in natural language with Copilot. Every carrier and source normalizes into one clean JSON shape.

Base URL & authentication

All requests are made over HTTPS to your Wakepoint API host. In local demo mode that is:

http://localhost:8000

In production, authenticate every request with your secret API key in the Authorization header. Keys are issued per account in the dashboard.

Authorization: Bearer wk_live_xxxxxxxxxxxxxxxx

Quickstart

Track a container in one call. Wakepoint auto-detects the carrier from the number and validates the ISO 6346 check digit.

curl -X POST http://localhost:8000/v1/track \
     -H "Content-Type: application/json" \
     -d '{"number": "MSKU0000006"}'

Track a shipment

Look up a container, booking, or bill-of-lading number. Walks the cost tiers (cache → free carrier APIs → paid aggregator → demo) and returns the normalized shipment. Subsequent lookups of the same number are served from cache within the TTL.

Request body

Response 200 · Shipment

{
  "number": "MSKU0000006",
  "carrier": "maersk",
  "status": "IN_TRANSIT",
  "pol": "BRSSZ", "pol_name": "Santos, Brazil",
  "pod": "USMIA", "pod_name": "Miami, USA",
  "vessel": { "name": "ONE Innovation", "voyage": "668E", "lat": 29.9, "lon": 99.9, "speed_kn": 20.9 },
  "eta_carrier": "2026-07-17",
  "eta_predicted": "2026-07-18",
  "events": [ { "type": "departed", "description": "Vessel departed", "locode": "BRSSZ", "at": "2026-07-03T17:00:00", "projected": false }, ... ],
  "source": "mock"
}

List tracked shipments

Returns every shipment currently in your account's cache as an array of Shipment objects. This is what powers the dashboard fleet view.

curl http://localhost:8000/v1/shipments

Get one shipment

Returns the cached status for a single number. Responds 404 if the number has not been tracked yet, call POST /v1/track first.

curl http://localhost:8000/v1/shipments/MSKU0000006

Register a webhook

Get notified the moment a milestone changes, with no polling. Deliveries are HMAC-signed so you can verify authenticity.

Request body

curl -X POST http://localhost:8000/v1/webhooks \
     -H "Content-Type: application/json" \
     -d '{"url": "https://yoursite.com/hooks", "events": ["eta.changed","arrived"]}'

Ask Copilot

Natural-language questions over your live fleet, e.g. "which shipments are delayed?", "what's arriving this week?". Requires ANTHROPIC_API_KEY for full reasoning; returns a concise deterministic answer in demo mode.

curl -X POST http://localhost:8000/v1/copilot/ask \
     -H "Content-Type: application/json" \
     -d '{"q": "which shipments are delayed?"}'

Response

{ "answer": "You have 1 tracked shipment. 1 on the water and on schedule.", "mode": "demo" }

Health

Liveness plus a report of which data sources are configured, handy for a status page or uptime monitor.

{ "ok": true, "demo_mode": true, "sources": { "maersk_free": false, "copilot": false, "billing_stripe": false, ... } }

WAKEPOINT+ agents

Six agents act on your fleet. Each uses Claude when ANTHROPIC_API_KEY is set and returns a solid deterministic result otherwise, so every endpoint works in demo mode.

Agent status

Lists the six agents and the top-line count each is watching right now.

{ "agents": [
  { "slug": "delay_sentinel",  "name": "Delay Sentinel",  "active": true, "investigations": 4 },
  { "slug": "demurrage_guard", "name": "Demurrage Guard", "active": true, "at_risk": 1 },
  { "slug": "morning_brief",   "name": "Morning Brief",   "active": true },
  { "slug": "trade_analyst",   "name": "Trade Analyst",   "active": true },
  { "slug": "customer_answer", "name": "Customer Answer Agent", "active": true },
  { "slug": "inbox_agent",     "name": "Inbox Agent",     "active": true }
] }

Morning Brief

A concise overnight digest: departures, arrivals, and the items that need action.

{ "date": "2026-07-11", "action_items": 2, "departures": 3, "arrivals": 1, "brief": "Overnight: 3 departures, 1 arrival. 2 items need you..." }

Delay Sentinel

Flags shipments drifting late or rolled at transshipment, with a root cause and confidence.

{ "active": true, "investigations": 1, "findings": [
  { "number": "CMAU7215880", "issue": "rolled at transshipment", "drift_days": 4, "root_cause": "vessel rollover / berth congestion", "confidence": 0.87, "lane": "INNSA -> NLRTM" }
] }

Demurrage Guard

Tracks free days on arrived containers and totals the weekend exposure at risk.

{ "active": true, "watching": 3, "at_risk": 1, "weekend_exposure_usd": 3750, "rows": [ ... ] }

Draft a dispatch

Body { "number": "MSCU8831049" }. Returns an editable dispatch email (to, subject, body). Nothing is sent; approval happens in your UI.

Trade Analyst

Turns your tracked shipments into lane, carrier, volume, and on-time intelligence.

{ "shipments": 6, "teu_estimate": 12, "on_time_rate": 83, "top_lanes": [ { "lane": "CNSHA -> USLGB", "count": 2, "share": 33 } ], "carrier_mix": [ ... ] }

Customer Answer Agent

Drafts a friendly, accurate status reply to a customer question about one shipment.

curl -X POST http://localhost:8000/v1/agents/customer-answer \
     -H "Content-Type: application/json" \
     -d '{"number": "MSKU0000006", "question": "when will it arrive?"}'

{ "number": "MSKU0000006", "reply": "Hi, here's the latest on MSKU0000006..." }

Inbox Agent

Parses a forwarded B/L or booking email, extracts the container/booking numbers, and starts tracking them automatically.

curl -X POST http://localhost:8000/v1/agents/inbox \
     -H "Content-Type: application/json" \
     -d '{"text": "Attached B/L. Container HLXU 000000-2 is ready."}'

{ "found": ["HLXU0000002"], "tracked": ["HLXU0000002"] }

Billing & account

Create a checkout session

Starts a subscription. With STRIPE_SECRET_KEY set it returns a Stripe Checkout URL to redirect to; in demo mode it returns a safe demo URL. Plans: starter, pro, tracker. enterprise is sales-led.

curl -X POST http://localhost:8000/v1/checkout \
     -H "Content-Type: application/json" \
     -d '{"plan": "pro", "email": "you@company.com"}'

{ "url": "https://checkout.stripe.com/...", "mode": "live" }

Stripe webhook

Receives Stripe events. On checkout.session.completed the account is activated. Set STRIPE_WEBHOOK_SECRET to verify signatures in production.

Account usage

Reports this month's shipment usage against the plan cap. The account is resolved from your API key. /v1/track counts only new shipments and returns 429 once the cap is reached.

curl http://localhost:8000/v1/account/usage -H "Authorization: Bearer wp_live_xxx"

{ "plan": "pro", "period": "2026-07", "used": 61, "limit": 100, "remaining": 39, "over_cap": false }

Shipment schema

One shape for every carrier and source. Dates are ISO 8601; eta_* are date-only.

Errors

Standard HTTP status codes. Error bodies are { "detail": "..." }.

Service status

Live component health. Wire this to your uptime monitor's public JSON in production.

Prototype reference. Endpoints reflect the shipped Wakepoint backend (wakepoint-backend/).