{
  "openapi": "3.1.0",
  "info": {
    "title": "Panvaya Tracking API",
    "version": "1.0.0",
    "description": "Metered REST API for real-time ocean container and air cargo tracking. Authenticate with an API key sent in the X-API-Key header. Live keys bill your monthly quota on successful lookups; sandbox keys (pv_test_...) return deterministic mock data for free.",
    "contact": { "name": "Panvaya Support", "url": "https://panvaya.com/contact-us" }
  },
  "servers": [
    { "url": "https://api.panvaya.com/api/v1", "description": "Production" }
  ],
  "security": [ { "ApiKeyAuth": [] } ],
  "paths": {
    "/track/ocean": {
      "post": {
        "summary": "Track an ocean container",
        "operationId": "trackOcean",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["containerNumber"],
                "properties": {
                  "containerNumber": { "type": "string", "description": "ISO 6346 container number.", "example": "MSCU1234567" },
                  "carrierId": { "type": "integer", "description": "Optional Panvaya carrier id (see /carriers) to disambiguate." }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Tracking data found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrackingResponse" } } } },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "402": { "$ref": "#/components/responses/Error" },
          "403": { "$ref": "#/components/responses/Error" },
          "404": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/Error" },
          "502": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/track/air": {
      "post": {
        "summary": "Track an air waybill",
        "operationId": "trackAir",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["awbNumber"],
                "properties": {
                  "awbNumber": { "type": "string", "description": "Air waybill number (with or without the 3-digit airline prefix).", "example": "020-12345675" },
                  "carrierId": { "type": "integer", "description": "Optional Panvaya carrier id (see /carriers)." }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Tracking data found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrackingResponse" } } } },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "402": { "$ref": "#/components/responses/Error" },
          "403": { "$ref": "#/components/responses/Error" },
          "404": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/Error" },
          "502": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/carriers": {
      "get": {
        "summary": "List supported carriers",
        "operationId": "listCarriers",
        "parameters": [
          { "name": "mode", "in": "query", "schema": { "type": "string", "enum": ["ocean", "air"], "default": "ocean" } }
        ],
        "responses": {
          "200": {
            "description": "Supported carriers and their Panvaya ids.",
            "content": { "application/json": { "schema": {
              "type": "object",
              "properties": {
                "mode": { "type": "string" },
                "carriers": { "type": "array", "items": { "type": "object", "properties": {
                  "id": { "type": "integer" }, "name": { "type": "string" }, "code": { "type": "string" }
                } } }
              }
            } } }
          }
        }
      }
    },
    "/health": {
      "get": {
        "summary": "Service health probe",
        "operationId": "health",
        "security": [],
        "responses": { "200": { "description": "Service is up." } }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" }
    },
    "responses": {
      "Error": {
        "description": "Error envelope.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": { "type": "string", "description": "Stable machine-readable code.", "example": "QUOTA_EXCEEDED" },
              "message": { "type": "string" }
            }
          }
        }
      },
      "Milestone": {
        "type": "object",
        "properties": {
          "event": { "type": "string" },
          "location": { "type": "string" },
          "timestamp": { "type": "string", "format": "date-time", "nullable": true }
        }
      },
      "TrackingResponse": {
        "type": "object",
        "description": "Canonical tracking payload (fields present depend on mode + carrier data).",
        "properties": {
          "status": { "type": "string", "example": "IN_TRANSIT" },
          "shipmentType": { "type": "string", "enum": ["OCEAN", "AIR"] },
          "carrierCode": { "type": "string" },
          "carrierName": { "type": "string" },
          "containerNo": { "type": "string" },
          "eta": { "type": "string", "format": "date-time", "nullable": true },
          "ata": { "type": "string", "format": "date-time", "nullable": true },
          "etd": { "type": "string", "format": "date-time", "nullable": true },
          "atd": { "type": "string", "format": "date-time", "nullable": true },
          "milestones": { "type": "array", "items": { "$ref": "#/components/schemas/Milestone" } }
        }
      }
    }
  }
}