{ "openapi": "3.1.0", "info": { "title": "aircargomcp REST API", "version": "1.0.0", "description": "Air-cargo AWB tracking, live aircraft positions, and air-freight rate quotes. One backend serves two surfaces: aircargomcp.com (AWB tracking + the free prefix oracle + live aircraft positions) and airratesmcp.com (rate quotes). Tracking normalises every airline/platform connector onto an IATA Cargo-IMP milestone shape (RCS → DEP → ARR → RCF → NFD → DLV); the rich geo/route/datetime fields are structure-aligned with the SeaRates Air-Tracking envelope, so a caller who already consumes SeaRates reads this with the same shape. Paid endpoints take `Authorization: Bearer ` (or `X-API-Key: `) — one `tmcp_` family key entitled to the `aircargo` product. The `/prefix/{code}` oracle is free and unauthenticated. AI agents can use the hosted MCP server at https://mcp.aircargomcp.com/mcp instead.", "contact": { "name": "aircargomcp", "url": "https://aircargomcp.com", "email": "hello@aircargomcp.com" } }, "servers": [{ "url": "https://api.aircargomcp.com" }], "security": [{ "bearerAuth": [] }, { "apiKeyHeader": [] }], "tags": [ { "name": "Tracking", "description": "AWB tracking and the AWB-prefix airline oracle." }, { "name": "Aircraft", "description": "Live aircraft positions from ADS-B (the air analogue of AIS vessel tracking)." }, { "name": "Rates", "description": "Air-freight rate quotes." } ], "paths": { "/track/{awb}": { "get": { "operationId": "trackAwb", "tags": ["Tracking"], "summary": "Track an air waybill", "description": "Resolve an AWB to its current status, route, pieces, weight, ETA and IATA Cargo-IMP milestone events. Any AWB format is accepted (`203-1234 5675`, `20312345675`, `203-12345675`); the 3-digit prefix selects the airline connector. The raw upstream provider body is never returned — provider + freshness metadata is exposed via `data.metadata` instead.", "parameters": [ { "name": "awb", "in": "path", "required": true, "description": "Air waybill number: 3-digit airline prefix + 8-digit serial (last digit is the modulo-7 check digit). Separators and spaces are ignored.", "schema": { "type": "string", "example": "176-12345675" } } ], "responses": { "200": { "description": "Tracking result.", "content": { "application/json": { "schema": { "type": "object", "required": ["data"], "properties": { "data": { "$ref": "#/components/schemas/AwbTrackingData" } } } } } }, "400": { "$ref": "#/components/responses/BadReference" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/NotEntitled" }, "404": { "description": "The AWB prefix resolves to a carrier without a wired connector (`unsupported_carrier`), or the airline returned no record for that AWB (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/UpstreamError" }, "503": { "$ref": "#/components/responses/AuthUnavailable" } } } }, "/prefix/{code}": { "get": { "operationId": "resolvePrefix", "tags": ["Tracking"], "summary": "Resolve an AWB prefix to its airline (free)", "description": "Free, unauthenticated offline oracle. The 3-digit numeric prefix at the head of every air waybill identifies the issuing airline — the air-cargo equivalent of a container BIC prefix. Returns the airline, its public track-and-trace URL, and which shared platform (if any) fronts it.", "security": [], "parameters": [ { "name": "code", "in": "path", "required": true, "description": "3-digit IATA numeric AWB prefix.", "schema": { "type": "string", "example": "176" } } ], "responses": { "200": { "description": "Airline for the prefix.", "content": { "application/json": { "schema": { "type": "object", "required": ["data"], "properties": { "data": { "$ref": "#/components/schemas/AirlinePrefixInfo" } } } } } }, "404": { "description": "Unknown AWB prefix.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/aircraft/flight/{flightNumber}": { "get": { "operationId": "aircraftByFlight", "tags": ["Aircraft"], "summary": "Live position by flight number", "description": "Live position(s) for the aircraft operating an IATA flight number (e.g. `EK9812` → callsign `UAE9812`), sourced from ADS-B with OpenSky and FR24 fallback. Airborne-only: a parked or out-of-coverage aircraft is a 404.", "parameters": [ { "name": "flightNumber", "in": "path", "required": true, "description": "IATA flight number.", "schema": { "type": "string", "example": "EK9812" } } ], "responses": { "200": { "$ref": "#/components/responses/AircraftPositions" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/NotEntitled" }, "404": { "$ref": "#/components/responses/AircraftNotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/AuthUnavailable" } } } }, "/aircraft/reg/{tail}": { "get": { "operationId": "aircraftByReg", "tags": ["Aircraft"], "summary": "Live position by registration / tail number", "description": "Live position(s) for an aircraft by registration (tail number), e.g. `N895FD`. Airborne-only.", "parameters": [ { "name": "tail", "in": "path", "required": true, "description": "Aircraft registration / tail number.", "schema": { "type": "string", "example": "N895FD" } } ], "responses": { "200": { "$ref": "#/components/responses/AircraftPositions" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/NotEntitled" }, "404": { "$ref": "#/components/responses/AircraftNotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/AuthUnavailable" } } } }, "/aircraft/callsign/{cs}": { "get": { "operationId": "aircraftByCallsign", "tags": ["Aircraft"], "summary": "Live position by ATC callsign", "description": "Live position(s) for an aircraft by its raw ATC callsign, e.g. `UAE9812`, `FDX9002`. Airborne-only.", "parameters": [ { "name": "cs", "in": "path", "required": true, "description": "Raw ATC callsign.", "schema": { "type": "string", "example": "UAE9812" } } ], "responses": { "200": { "$ref": "#/components/responses/AircraftPositions" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/NotEntitled" }, "404": { "$ref": "#/components/responses/AircraftNotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/AuthUnavailable" } } } }, "/rates/quote": { "post": { "operationId": "quoteRate", "tags": ["Rates"], "summary": "Quote an air-freight lane", "description": "Price a lane against the best available rate card. Chargeable weight is `max(gross, volumetric)` where volumetric = `volume_cm3 / 6000`; the applied weight break, net per-kg, surcharges and all-in per-kg are returned. Card source, best-first: live carrier rates (CargoAi) → Freightos FAX region rate → sample card fallback.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AirRateQuery" }, "example": { "origin": "HKG", "destination": "FRA", "weight_kg": 250, "service": "general" } } } }, "responses": { "200": { "description": "Rate quote.", "content": { "application/json": { "schema": { "type": "object", "required": ["data"], "properties": { "data": { "$ref": "#/components/schemas/AirRateQuote" } } } } } }, "400": { "$ref": "#/components/responses/BadReference" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/NotEntitled" }, "404": { "description": "No rate card for the requested lane.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/UpstreamError" }, "503": { "$ref": "#/components/responses/AuthUnavailable" } } } }, "/health": { "get": { "operationId": "health", "summary": "Health check", "security": [], "responses": { "200": { "description": "Service is up.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true } } } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Family API key entitled to the `aircargo` product, sent as `Authorization: Bearer `. Create keys in the dashboard at https://aircargomcp.com." }, "apiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "The same family API key, sent as `X-API-Key: ` instead of a bearer token." } }, "responses": { "AircraftPositions": { "description": "One or more live aircraft positions (a flight can map to more than one airframe).", "content": { "application/json": { "schema": { "type": "object", "required": ["data"], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AirAircraftPosition" } } } } } } }, "AircraftNotFound": { "description": "No live position — aircraft not airborne or out of ADS-B coverage (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "BadReference": { "description": "Malformed request: bad AWB (`invalid_reference`) or an invalid rate-quote body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "Unauthorized": { "description": "Missing (`missing_key`), unrecognised (`invalid_key`), revoked (`revoked_key`) or expired (`expired_key`) API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "NotEntitled": { "description": "The key's org does not hold an active `aircargo` entitlement (`not_entitled`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "RateLimited": { "description": "A usage window (daily / weekly / monthly / lifetime) is exhausted (`rate_limited`), or an upstream airline rate limit was hit. See the `X-Usage-*` response headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "UpstreamError": { "description": "The upstream airline/rate source errored, timed out or blocked the lookup (`blocked` / `rate_limited` / `upstream_error`). Safe to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "AuthUnavailable": { "description": "Key verification or the entitlement check is temporarily unavailable (`auth_unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "schemas": { "ErrorEnvelope": { "type": "object", "required": ["error"], "properties": { "error": { "type": "object", "required": ["code", "message"], "properties": { "code": { "type": "string", "description": "Machine-readable error code.", "enum": [ "invalid_reference", "unsupported_carrier", "not_found", "blocked", "rate_limited", "upstream_error", "missing_key", "invalid_key", "revoked_key", "expired_key", "not_entitled", "auth_unavailable" ] }, "message": { "type": "string", "description": "Human-readable explanation." } } } } }, "AirLocation": { "type": "object", "description": "A place (station / airport). Every field is optional; a connector that only knows the IATA code sets just `iata_code`.", "properties": { "iata_code": { "type": ["string", "null"], "description": "3-letter IATA airport code.", "example": "HKG" }, "icao_code": { "type": ["string", "null"], "description": "4-letter ICAO airport code.", "example": "VHHH" }, "name": { "type": ["string", "null"], "example": "Hong Kong International Airport" }, "city": { "type": ["string", "null"] }, "state": { "type": ["string", "null"] }, "country": { "type": ["string", "null"] }, "country_code": { "type": ["string", "null"], "description": "ISO 3166-1 alpha-2." }, "lat": { "type": ["number", "null"] }, "lng": { "type": ["number", "null"] }, "timezone": { "type": ["string", "null"], "description": "IANA timezone.", "example": "Asia/Hong_Kong" } } }, "AirDateTimes": { "type": "object", "description": "An estimated/actual datetime pair (ISO 8601). `actual != null` means the milestone truly happened.", "properties": { "estimated": { "type": ["string", "null"], "format": "date-time" }, "actual": { "type": ["string", "null"], "format": "date-time" } } }, "AirStatusCode": { "type": "string", "description": "IATA Cargo-IMP milestone code (unknown codes fall through as a free string).", "enum": ["FOH", "RCS", "MAN", "DEP", "ARR", "RCF", "TFD", "NFD", "AWD", "CCD", "DLV"] }, "AirEventFamily": { "type": "string", "enum": ["ACCEPTANCE", "FLIGHT", "DELIVERY", "CUSTOMS"] }, "AirEvent": { "type": "object", "required": ["status_code", "event_family", "is_actual", "datetime"], "properties": { "status_code": { "description": "IATA Cargo-IMP code, or a raw string for codes outside the closed set.", "oneOf": [{ "$ref": "#/components/schemas/AirStatusCode" }, { "type": "string" }] }, "event_family": { "$ref": "#/components/schemas/AirEventFamily" }, "is_actual": { "type": "boolean", "description": "True once this milestone actually occurred." }, "datetime": { "type": "string", "format": "date-time", "description": "Resolved time (actual ?? estimated); flat, for sorting." }, "datetimes": { "$ref": "#/components/schemas/AirDateTimes" }, "station": { "type": ["string", "null"], "description": "IATA 3-letter station code.", "example": "HKG" }, "station_name": { "type": ["string", "null"] }, "location": { "oneOf": [{ "$ref": "#/components/schemas/AirLocation" }, { "type": "null" }] }, "flight_number": { "type": ["string", "null"], "example": "EK9812" }, "pieces": { "type": ["integer", "null"] }, "weight_kg": { "type": ["number", "null"] }, "description": { "type": ["string", "null"] } } }, "AirRoute": { "type": "object", "description": "A single leg of the journey (flight or trucking segment). `path` is the great-circle polyline to draw on a map.", "properties": { "order_id": { "type": ["integer", "null"] }, "status": { "type": ["string", "null"], "description": "Upstream leg status (ARRIVED, IN_TRANSIT, …)." }, "transport_type": { "type": ["string", "null"], "description": "PLANE, TRUCK, or an upstream string.", "example": "PLANE" }, "from": { "oneOf": [{ "$ref": "#/components/schemas/AirLocation" }, { "type": "null" }] }, "to": { "oneOf": [{ "$ref": "#/components/schemas/AirLocation" }, { "type": "null" }] }, "departure": { "$ref": "#/components/schemas/AirDateTimes" }, "arrival": { "$ref": "#/components/schemas/AirDateTimes" }, "flight_number": { "type": ["string", "null"] }, "pieces": { "type": ["integer", "null"] }, "weight_kg": { "type": ["number", "null"] }, "path": { "type": ["array", "null"], "description": "[lat, lng] polyline points.", "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } } } }, "AwbMetadata": { "type": "object", "description": "Provider + freshness metadata — replaces the raw upstream body in the public response.", "properties": { "status_code": { "type": "string", "description": "Upstream status code (OK, AIRLINE_HASNT_PROVIDE_INFO, …)." }, "airline": { "type": "object", "properties": { "name": { "type": ["string", "null"] }, "prefix": { "type": ["string", "null"] }, "iata_code": { "type": ["string", "null"] }, "icao_code": { "type": ["string", "null"] }, "url": { "type": ["string", "null"] } } }, "updated_at": { "type": ["string", "null"], "format": "date-time", "description": "When the tracking data was last refreshed." }, "from_cache": { "type": "boolean", "description": "Whether this response was served from our cache." }, "cache_expires": { "type": ["string", "null"], "format": "date-time", "description": "When our cached copy expires." } } }, "AwbStatus": { "type": "string", "enum": ["booked", "accepted", "in_transit", "arrived", "available", "delivered", "unknown"] }, "AwbTrackingData": { "type": "object", "description": "Public AWB tracking payload (the raw/source upstream bodies are stripped at the API boundary). The flat scalar fields are the guaranteed baseline every connector populates; the geo/route/datetime objects are optional enrichment.", "required": ["awb", "airline_prefix", "airline_iata", "airline_name", "status", "events"], "properties": { "awb": { "type": "string", "description": "Canonical 11-digit AWB.", "example": "176-12345675" }, "airline_prefix": { "type": "string", "description": "3-digit IATA numeric prefix.", "example": "176" }, "airline_iata": { "type": "string", "description": "2-char IATA airline code.", "example": "EK" }, "airline_name": { "type": "string", "example": "Emirates SkyCargo" }, "status": { "$ref": "#/components/schemas/AwbStatus" }, "origin": { "type": ["string", "null"], "description": "IATA origin station code.", "example": "HKG" }, "origin_name": { "type": ["string", "null"] }, "origin_location": { "oneOf": [{ "$ref": "#/components/schemas/AirLocation" }, { "type": "null" }] }, "destination": { "type": ["string", "null"], "example": "FRA" }, "destination_name": { "type": ["string", "null"] }, "destination_location": { "oneOf": [{ "$ref": "#/components/schemas/AirLocation" }, { "type": "null" }] }, "pieces": { "type": ["integer", "null"], "description": "Total pieces on the AWB." }, "weight_kg": { "type": ["number", "null"], "description": "Total gross weight." }, "flight_number": { "type": ["string", "null"], "description": "Primary flight number on the AWB." }, "departure": { "$ref": "#/components/schemas/AirDateTimes" }, "arrival": { "$ref": "#/components/schemas/AirDateTimes" }, "eta": { "type": ["string", "null"], "format": "date-time", "description": "Resolved arrival (actual ?? estimated); flat." }, "eta_is_actual": { "type": "boolean" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/AirEvent" } }, "routes": { "type": "array", "description": "Per-leg breakdown with map path, when the source provides it.", "items": { "$ref": "#/components/schemas/AirRoute" } }, "metadata": { "$ref": "#/components/schemas/AwbMetadata" } } }, "AirTrackingPlatform": { "type": "string", "description": "Shared platform fronting the airline's track-and-trace, if any.", "enum": ["smartkargo", "ibs-icargo", "dhl-aviation", "accelya", "hna-portal2", "ceair"] }, "AirlinePrefixInfo": { "type": "object", "required": ["prefix", "iata", "name", "site"], "properties": { "prefix": { "type": "string", "description": "3-digit IATA numeric prefix.", "example": "176" }, "iata": { "type": "string", "description": "2-char IATA airline code.", "example": "EK" }, "name": { "type": "string", "example": "Emirates SkyCargo" }, "site": { "type": "string", "description": "Public track-and-trace URL (may be a deep link / template).", "example": "https://www.skycargo.com/shipping-services/track-shipments/" }, "platform": { "$ref": "#/components/schemas/AirTrackingPlatform" } } }, "AirAircraftPosition": { "type": "object", "description": "One normalised live aircraft position, mapped off an ADS-B record. Airborne-only.", "required": ["callsign", "registration", "icao24_hex", "aircraft_type", "lat", "lon", "alt_ft", "ground_speed_kt", "heading", "vertical_rate_fpm", "seen_at"], "properties": { "callsign": { "type": "string", "description": "ATC callsign, trimmed.", "example": "UAE9812" }, "registration": { "type": ["string", "null"], "description": "Tail number, null when not broadcast.", "example": "A6-EFD" }, "icao24_hex": { "type": "string", "description": "24-bit ICAO address (lower-case hex) — the stable aircraft id.", "example": "896180" }, "aircraft_type": { "type": ["string", "null"], "description": "ICAO type designator, null when unknown.", "example": "B77L" }, "lat": { "type": "number" }, "lon": { "type": "number" }, "alt_ft": { "type": ["number", "null"], "description": "Barometric altitude in feet; 0 on the ground; null when not broadcast." }, "ground_speed_kt": { "type": ["number", "null"] }, "heading": { "type": ["number", "null"], "description": "True track over ground, degrees 0–359." }, "vertical_rate_fpm": { "type": ["number", "null"], "description": "Climb/descent rate, feet per minute (+climb / −descent)." }, "origin_iata": { "type": "string", "description": "Departure airport IATA — only when enriched (ADS-B has no route data)." }, "dest_iata": { "type": "string", "description": "Arrival airport IATA — only when enriched." }, "operator_iata": { "type": "string", "description": "2-char IATA operator code, when resolvable from the callsign." }, "seen_at": { "type": "string", "format": "date-time", "description": "When this position was last observed (ISO 8601 UTC)." } } }, "AirRateService": { "type": "string", "enum": ["general", "express", "pharma", "perishable", "dangerous_goods"] }, "AirRateQuery": { "type": "object", "required": ["origin", "destination", "weight_kg"], "properties": { "origin": { "type": "string", "minLength": 3, "maxLength": 3, "description": "Origin airport IATA code.", "example": "HKG" }, "destination": { "type": "string", "minLength": 3, "maxLength": 3, "description": "Destination airport IATA code.", "example": "FRA" }, "weight_kg": { "type": "number", "exclusiveMinimum": 0, "description": "Gross weight in kilograms." }, "volume_cm3": { "type": "number", "exclusiveMinimum": 0, "description": "Total volume in cm³, for volumetric/chargeable weight. Omitted → chargeable = gross." }, "service": { "$ref": "#/components/schemas/AirRateService" } } }, "AirRateQuote": { "type": "object", "required": ["origin", "destination", "chargeable_weight_kg", "applied_band", "net_per_kg", "surcharge_per_kg", "all_in_per_kg", "total_charge", "currency", "source"], "properties": { "origin": { "type": "string", "example": "HKG" }, "destination": { "type": "string", "example": "FRA" }, "chargeable_weight_kg": { "type": "number", "description": "max(gross, volumetric), where volumetric = volume_cm3 / 6000." }, "applied_band": { "type": "string", "description": "Weight break used.", "enum": ["MIN", "N", "+45", "+100", "+300", "+500", "+1000"] }, "net_per_kg": { "type": "number", "description": "Net air rate for the applied band." }, "surcharge_per_kg": { "type": "number", "description": "Fuel + security surcharges per kg." }, "all_in_per_kg": { "type": "number", "description": "net_per_kg + surcharge_per_kg." }, "total_charge": { "type": "number", "description": "max(min_charge, chargeable_weight * all_in_per_kg)." }, "currency": { "type": "string", "description": "ISO 4217.", "example": "USD" }, "airline_iata": { "type": ["string", "null"], "description": "Quoting carrier, when carrier-specific." }, "source": { "type": "string", "description": "Where the rate card came from.", "example": "cargoai" } } } } } }