CargoPilot Developer API

Shipment Tracking

Create shipments, receive milestone events, AI-revised ETAs, and real-time vessel positions across 300+ carriers.

Port Intelligence

850+ ports with congestion scores, dwell times, demurrage rates, vessel counts, and weekly plain-English summaries.

Live Vessel Positions

Real-time AIS satellite positions, speed, course, navigational status, and next port ETA for all tracked vessels.

Quick Start

Get up and running in under 5 minutes. Request an API key, then start pulling your container data immediately — no SDKs or complex setup required.

1. Authenticate

bash

curl https://api.cargopilot.ai/v1/shipments \
  -H "X-API-Key: cp_live_your_key_here"

2. Node.js example

javascript

const API_KEY = process.env.CARGOPILOT_API_KEY;

async function getShipments() {
  const res = await fetch('https://api.cargopilot.ai/v1/shipments', {
    headers: { 'X-API-Key': API_KEY },
  });
  return res.json();
}

const { data, pagination } = await getShipments();
console.log(`Tracking ${pagination.total} containers`);

3. Python example

python

import requests

API_KEY = os.environ["CARGOPILOT_API_KEY"]
BASE = "https://api.cargopilot.ai/v1"

headers = {"X-API-Key": API_KEY}

# List all shipments
resp = requests.get(f"{BASE}/shipments", headers=headers)
data = resp.json()
print(f"Tracking {data['pagination']['total']} containers")

# Get a specific shipment
shipment = requests.get(
    f"{BASE}/shipments/{data['data'][0]['id']}",
    headers=headers
).json()

Authentication

All requests require your API key in the X-API-Key header. Keys are organisation-scoped and return data only for your organisation. Keys begin with cp_live_ for production and cp_test_ for sandbox.

bash

curl https://api.cargopilot.ai/v1/shipments \
  -H "X-API-Key: cp_live_your_key_here" \
  -H "Content-Type: application/json"

API access requires the Professional plan or above. Keys are issued on request — .

Shipments

Create and manage shipments across ocean and air freight. Shipments created via API count against the same container quota as the web app. ETAs are AI-revised using live AIS data, port congestion intelligence, and carrier telemetry.

Endpoints

GET

/v1/shipments

List all shipments (paginated)

GET

/v1/shipments/:id

Get full shipment detail with milestone history

POST

/v1/shipments

Create a shipment (ocean or air freight)

GET

/v1/shipments/:id/master-timeline

Complete merged event timeline

POST

/v1/shipments/:id/tags

Add a reference tag (PO number, booking ref, etc.)

DELETE

/v1/shipments/:id/tags/:tagId

Remove a reference tag

POST

/v1/shipments/:id/pin

Pin / unpin a shipment

POST

/v1/shipments/:id/dismiss-alert

Acknowledge an active alert

POST

/v1/shipments/:id/refresh-air

Force re-fetch of air freight data

GET /v1/shipments — Response

json

{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "container_number": "MSCU1234567",
      "transport_mode": "ocean_freight",
      "status": "in_transit",
      "pol": "CNSHA",
      "pod": "GBFXT",
      "eta": "2026-04-12T00:00:00Z",
      "original_eta": "2026-04-10T00:00:00Z",
      "carrier_name": "MSC",
      "vessel_name": "MSC TINA",
      "current_vessel_imo": "9839338",
      "share_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "latest_milestone": "departed_port_of_loading",
      "latest_milestone_date": "2026-03-18T08:30:00Z"
    }
  ],
  "pagination": { "limit": 20, "offset": 0, "total": 47 }
}

GET /v1/shipments/:id — Response

json

{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "container_number": "MSCU1234567",
    "transport_mode": "ocean_freight",
    "status": "in_transit",
    "pol": "CNSHA",
    "pod": "GBFXT",
    "eta": "2026-04-12T00:00:00Z",
    "original_eta": "2026-04-10T00:00:00Z",
    "actual_arrival": null,
    "carrier_name": "MSC",
    "vessel_name": "MSC TINA",
    "current_vessel_imo": "9839338",
    "tags": [{ "id": "uuid", "label": "PO Number", "value": "PO-2026-00114" }],
    "share_token": "a1b2c3d4-...",
    "events": [
      {
        "event_type": "gate_in_full",
        "location_name": "Shanghai Yangshan",
        "location_iso": "CNSHA",
        "vessel_name": null,
        "event_ts": "2026-03-15T06:00:00Z"
      },
      {
        "event_type": "departed_port_of_loading",
        "location_name": "Shanghai Yangshan",
        "location_iso": "CNSHA",
        "vessel_name": "MSC TINA",
        "event_ts": "2026-03-18T08:30:00Z"
      }
    ]
  }
}

POST /v1/shipments — Request body

json

// Ocean freight
{
  "container_number": "MSCU1234567",
  "carrier_scac": "MSCU",
  "pol": "CNSHA",         // optional
  "pod": "GBFXT"          // optional
}

// Air freight
{
  "airway_bill_number": "057-12345678",
  "airline_iata": "EK"
}

Ports

Access CargoPilot's port intelligence database covering 850+ global container terminals. Each port record includes live congestion scores, average dwell times, vessel counts, weekly plain-English operational summaries, demurrage rates, and customs free time. Updated weekly.

Endpoints

GET

/v1/ports

List all 850+ tracked ports

GET

/v1/ports/:unlocode

Full intelligence for a specific port (by UN/LOCODE)

GET

/v1/ports/slugs

Slugs and last-updated timestamps for all ports (sitemap use)

GET /v1/ports — Response

json

{
  "data": [
    {
      "unlocode": "CNSHA",
      "name": "Shanghai (Yangshan)",
      "country": "CN",
      "region": "East Asia",
      "slug": "shanghai",
      "congestion_score": 72,
      "avg_dwell_days": 3.4,
      "vessel_count": 210,
      "updated_at": "2026-03-28T00:00:00Z"
    }
  ],
  "total": 850
}

GET /v1/ports/:unlocode — Response

json

{
  "unlocode": "CNSHA",
  "name": "Shanghai (Yangshan)",
  "country": "CN",
  "region": "East Asia",
  "congestion_score": 72,
  "congestion_label": "High",
  "avg_dwell_days": 3.4,
  "vessel_count": 210,
  "weekly_summary": "High congestion at Yangshan with vessel wait times averaging 2–3 days. Gate-in delays reported on inbound lanes.",
  "free_days_standard": 5,
  "demurrage_rate_usd_per_day": 145,
  "updated_at": "2026-03-28T00:00:00Z"
}

Congestion score

0–100. Below 40 = low congestion. 40–70 = moderate. 70–100 = high. Calculated weekly from vessel wait times, AIS dwell data, and port authority reports.

Vessels

Live AIS satellite vessel positions for all vessels currently tracked by CargoPilot. Vessels carrying your organisation's containers are flagged with monitored: true and include the linked container number and shipment ID.

Endpoints

GET

/v1/vessels

All live vessel positions

GET

/v1/vessels/:imo

Position and detail for a specific vessel by IMO number

GET /v1/vessels — Response

json

{
  "data": [
    {
      "imo": "9839338",
      "name": "MSC TINA",
      "mmsi": "636021234",
      "lat": 35.6155,
      "lng": 139.7810,
      "speed": 14.2,
      "course": 270,
      "navigational_status": "Under way using engine",
      "next_port_name": "Felixstowe",
      "next_port_locode": "GBFXT",
      "next_port_eta": "2026-04-12T00:00:00Z",
      "monitored": true,
      "container_number": "MSCU1234567",
      "shipment_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    }
  ],
  "total": 2480
}

Analytics

Aggregated performance data computed from your organisation's shipment history. Use to power carrier scorecards, lane benchmarking, and executive reporting. All endpoints accept optional from, to, and mode query parameters. Default window: 90 days.

Endpoints

GET

/v1/analytics/summary

Portfolio summary: on-time rate, avg delay, volume by mode

GET

/v1/analytics/carriers

Carrier scorecard: on-time %, avg delay, shipment count

GET

/v1/analytics/lanes

Lane performance: delay stats by origin–destination pair

GET

/v1/analytics/commodities

Commodity breakdown: delay exposure by cargo type

GET /v1/analytics/summary — Response

json

{
  "total_shipments": 48,
  "on_time_rate": 78.3,
  "avg_delay_days": 2.4,
  "ocean_count": 34,
  "air_count": 14,
  "carriers": [
    {
      "carrier_name": "Maersk",
      "shipment_count": 18,
      "on_time_pct": 83.3,
      "avg_delay_days": 1.2
    }
  ],
  "from": "2025-12-18T00:00:00Z",
  "to": "2026-03-18T00:00:00Z"
}

Documents

Attach, retrieve, and AI-extract shipping documents linked to any shipment. CargoPilot's Document Intelligence uses GPT-4o vision to read any shipping document — Bill of Lading, commercial invoice, packing list, airway bill, certificate of origin — in any language, and returns structured JSON data.

Endpoints

GET

/v1/documents/shipment/:shipmentId

List all documents attached to a shipment

POST

/v1/documents/shipment/:shipmentId

Upload a document (multipart/form-data, max 10 MB)

GET

/v1/documents/:docId/download

Download raw file content

DELETE

/v1/documents/:docId

Permanently delete a document

POST

/v1/documents/:docId/extract

Trigger AI extraction (GPT-4o vision)

GET

/v1/documents/:docId/extraction

Get structured AI extraction result

PUT

/v1/documents/:docId/extraction/correct

Save a manual correction to an extracted field

bash

# Upload a Bill of Lading
curl -X POST https://api.cargopilot.ai/v1/documents/shipment/SHIPMENT_ID \
  -H "X-API-Key: cp_live_your_key_here" \
  -F "file=@bill-of-lading.pdf"

# Trigger AI extraction
curl -X POST https://api.cargopilot.ai/v1/documents/DOC_ID/extract \
  -H "X-API-Key: cp_live_your_key_here"

AI extraction response

json

{
  "document_type": "bill_of_lading",
  "extracted_data": {
    "bl_number":         "MAEU-B0123456",
    "shipper":           "Exportadora del Pacífico S.A.",
    "consignee":         "Rotterdam Fresh B.V.",
    "port_of_loading":   "Puerto Limón, Costa Rica",
    "port_of_discharge": "Rotterdam, Netherlands",
    "cargo_description": "Fresh avocados (Persea americana), 1,200 cartons",
    "declared_value":    "USD 48,000",
    "incoterms":         "FOB"
  },
  "created_at": "2026-03-14T09:45:00.000Z"
}

Reports

Generate AI-authored PDF shipment reports server-side. Each report contains the milestone timeline, vessel route map, delay analysis, AI-generated narrative, and cargo details extracted from uploaded documents. Reports include a unique verification token so third parties can independently confirm authenticity.

Endpoints

POST

/v1/report/:shipmentId/generate

Generate a PDF shipment report (returns binary stream)

GET

/v1/report/verify/:token

Verify report authenticity (public, no auth required)

bash

# Generate and save a report
curl -X POST https://api.cargopilot.ai/v1/report/SHIPMENT_ID/generate \
  -H "X-API-Key: cp_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"lang": "en"}' \
  --output cargo-report.pdf

Webhooks

Receive real-time push events when your shipments change status. CargoPilot sends an HTTP POST to your configured endpoint whenever a milestone is hit, an ETA changes, an alert is triggered, or a shipment arrives. Outbound webhook configuration is available on request for Professional and Enterprise plans.

Event types

shipment.milestoneshipment.eta_changeshipment.alertshipment.arriveddocument.extractedreport.generated

Webhook payload example

json

{
  "event": "shipment.eta_change",
  "shipment_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "container_number": "MSCU1234567",
  "previous_eta": "2026-04-10T00:00:00Z",
  "new_eta": "2026-04-12T00:00:00Z",
  "delay_days": 2,
  "reason": "Port congestion at Felixstowe",
  "timestamp": "2026-03-28T14:22:00Z"
}

Securing webhooks

Every webhook request includes an X-CargoPilot-Signature header — an HMAC-SHA256 signature of the raw payload using your webhook secret. Always verify this signature before processing the event.

Public Tracking

Every shipment has a unique share_token that enables a read-only public tracking view — no authentication required. Use this to share live tracking links with customers, partners, or auditors.

Endpoint — No auth required

GET

/v1/track/:token

Read-only shipment view by share token

bash

curl https://api.cargopilot.ai/v1/track/a1b2c3d4-e5f6-7890-abcd-ef1234567890

Activity Log

A tamper-evident audit trail of every meaningful action taken within your organisation — shipments created, documents uploaded, reports generated, users invited, and settings changed. Available to administrators. Maximum 200 events per request.

Endpoints

GET

/v1/activity

Paginated, reverse-chronological activity events

bash

curl "https://api.cargopilot.ai/v1/activity?from=2026-03-01&limit=50" \
  -H "X-API-Key: cp_live_your_key_here"

Errors & Rate Limits

Status	Code	Meaning
200	ok	Request succeeded
201	created	Resource created successfully
400	bad_request	Invalid request body or parameters
401	authentication_required	X-API-Key header missing or invalid
403	api_plan_required	Professional plan required for API access
404	not_found	Resource does not exist
429	rate_limit_exceeded	120 req/min limit exceeded
500	server_error	Internal server error — contact support

json

{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Maximum 120 requests per minute.",
  "retry_after_seconds": 60
}

Rate limit

120 req/min

Window

60 seconds

Scope

Per API key

Retry header

retry_after_seconds

Ready to integrate?

Start building today

API keys are issued on request, usually the same business day. Tell us what you're building and we'll get you set up immediately.

Enterprise enquiries

Build with CargoPilot

Quick Start

Authentication

Shipments

Ports

Vessels

Analytics

Documents

Reports

Webhooks

Public Tracking

Activity Log

Errors & Rate Limits

Start building today

Build with
CargoPilot