{
  "openapi": "3.1.0",
  "info": {
    "title": "AMN Airline Integration API",
    "version": "1.0.0",
    "description": "Airline-private integration contract. Payload and PIREP operations require an AMN-issued Bearer credential and Idempotency-Key."
  },
  "servers": [
    {
      "url": "/api/v1"
    }
  ],
  "paths": {
    "/admin/e2e-certification": {
      "get": {
        "operationId": "getE2eCertification",
        "description": "Read-only persisted flight certification. Summary and stage totals reflect filters. No-store; no real flight is certified by an empty result.",
        "security": [
          {
            "ownerAccess": []
          }
        ],
        "parameters": [
          {
            "name": "date",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "airline",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "AMN Airline.id"
          },
          {
            "name": "flightNumber",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "enum": [
                "CERTIFIED",
                "IN_PROGRESS",
                "WARNING",
                "FAILED"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Summary, stageTotals and per-flight identity/overallStatus/stages/reasonCodes"
          },
          "400": {
            "description": "Invalid filter"
          },
          "401": {
            "description": "Owner access denied"
          },
          "503": {
            "description": "Certification evidence unavailable"
          }
        }
      }
    },
    "/health": {
      "get": {
        "operationId": "getHealth",
        "responses": {
          "200": {
            "description": "API foundation status"
          }
        }
      }
    },
    "/scheduled-flights": {
      "post": {
        "operationId": "declareScheduledFlight",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ScheduledFlightDeclaration"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Existing idempotent declaration"
          },
          "201": {
            "description": "Scheduled flight declared"
          },
          "409": {
            "description": "Schedule or idempotency conflict"
          },
          "422": {
            "description": "Airport, aircraft or capacity evidence unavailable"
          }
        }
      }
    },
    "/payload-requests": {
      "post": {
        "operationId": "createPayloadRequest",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PayloadRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Existing active or renewed Payload hold",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PayloadAllocation"
                }
              }
            }
          },
          "201": {
            "description": "Payload generated and temporarily held; no Booking or Dispatch is confirmed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PayloadAllocation"
                }
              }
            }
          },
          "409": {
            "description": "Idempotency key reused with a different request body"
          },
          "422": {
            "description": "Registered capacity or market snapshot unavailable"
          }
        }
      }
    },
    "/payload-confirmations": {
      "post": {
        "operationId": "confirmPayloadAfterOfpPreparation",
        "description": "Confirms an active Payload hold only after the airline has successfully created its Booking, Dispatch and OFP.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PayloadConfirmation"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Existing idempotent confirmation"
          },
          "201": {
            "description": "Payload hold confirmed after OFP preparation"
          },
          "409": {
            "description": "Idempotency conflict"
          },
          "410": {
            "description": "Payload hold expired before OFP preparation"
          },
          "422": {
            "description": "Payload hold or confirmation evidence is invalid"
          }
        }
      }
    },
    "/pireps": {
      "post": {
        "operationId": "createPirep",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Pirep"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "PIREP accepted or identical report replayed; returns pirepId and normalized submitted fields"
          },
          "401": {
            "description": "Invalid airline credential"
          },
          "403": {
            "description": "Missing pirep:write scope"
          },
          "409": {
            "description": "Flight/report identity or idempotency conflict"
          },
          "422": {
            "description": "PIREP violates flight or capacity constraints"
          }
        }
      }
    },
    "/admin/owner-portal": {
      "get": {
        "operationId": "getOwnerPortalSection",
        "description": "Read an owner operations, airlines, world-state or audit section. Airline credentials are returned only as non-secret metadata.",
        "security": [
          {
            "ownerAccess": []
          }
        ],
        "parameters": [
          {
            "name": "section",
            "in": "query",
            "schema": {
              "enum": [
                "operations",
                "airlines",
                "world",
                "audit"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Requested owner portal section"
          },
          "400": {
            "description": "Invalid section"
          },
          "401": {
            "description": "Owner access denied"
          }
        }
      },
      "post": {
        "operationId": "runOwnerPortalAction",
        "description": "Run an audited owner action: reconcile fallback world feedback, change an active airline status, enable or disable an integration connection, or revoke an API credential.",
        "security": [
          {
            "ownerAccess": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "action"
                ],
                "properties": {
                  "action": {
                    "enum": [
                      "RUN_WORLD_FEEDBACK",
                      "SET_AIRLINE_STATUS",
                      "SET_CONNECTION_ENABLED",
                      "REVOKE_CREDENTIAL"
                    ]
                  },
                  "targetId": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "status": {
                    "enum": [
                      "ACTIVE",
                      "SUSPENDED"
                    ]
                  },
                  "enabled": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Action completed and audit record persisted"
          },
          "400": {
            "description": "Invalid or failed action"
          },
          "401": {
            "description": "Owner access denied"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ownerAccess": {
        "type": "apiKey",
        "in": "header",
        "name": "x-amn-admin-code"
      },
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "AMN API key"
      }
    },
    "parameters": {
      "IdempotencyKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": true,
        "schema": {
          "type": "string",
          "minLength": 8,
          "maxLength": 128
        }
      }
    },
    "schemas": {
      "ScheduledFlightDeclaration": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "externalFlightId",
          "flightNumber",
          "operatingDate",
          "originIata",
          "destinationIata",
          "scheduledDepartureUtc",
          "aircraftTypeCode",
          "registration"
        ],
        "properties": {
          "externalFlightId": {
            "type": "string",
            "minLength": 1
          },
          "flightNumber": {
            "type": "string",
            "minLength": 1
          },
          "operatingDate": {
            "type": "string",
            "format": "date"
          },
          "originIata": {
            "type": "string",
            "pattern": "^[A-Z]{3}$"
          },
          "destinationIata": {
            "type": "string",
            "pattern": "^[A-Z]{3}$"
          },
          "scheduledDepartureUtc": {
            "type": "string",
            "format": "date-time"
          },
          "aircraftTypeCode": {
            "type": "string",
            "pattern": "^[A-Z0-9]{2,4}$"
          },
          "registration": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "PayloadRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "externalFlightId",
          "flightNumber",
          "operatingDate",
          "originIata",
          "destinationIata",
          "aircraftTypeCode",
          "registration",
          "loadStage"
        ],
        "properties": {
          "externalFlightId": {
            "type": "string",
            "minLength": 1
          },
          "flightNumber": {
            "type": "string",
            "minLength": 1
          },
          "operatingDate": {
            "type": "string",
            "format": "date"
          },
          "originIata": {
            "type": "string",
            "pattern": "^[A-Z]{3}$"
          },
          "destinationIata": {
            "type": "string",
            "pattern": "^[A-Z]{3}$"
          },
          "aircraftTypeCode": {
            "type": "string",
            "pattern": "^[A-Z0-9]{2,4}$"
          },
          "registration": {
            "type": [
              "string",
              "null"
            ]
          },
          "loadStage": {
            "enum": [
              "FORECAST",
              "BOOKED",
              "FINAL"
            ]
          }
        }
      },
      "PayloadAllocation": {
        "type": "object",
        "required": [
          "payloadRequestId",
          "marketSnapshotId",
          "allocationStatus",
          "holdExpiresAt",
          "lifecycleModelId",
          "capacity",
          "passengers",
          "cargo",
          "provenance"
        ],
        "properties": {
          "payloadRequestId": {
            "type": "string"
          },
          "marketSnapshotId": {
            "type": "string"
          },
          "allocationStatus": {
            "enum": [
              "HELD",
              "CONFIRMED"
            ],
            "description": "New allocation is HELD. Replay preserves the current lifecycle; expired holds are rejected without renewal."
          },
          "holdExpiresAt": {
            "type": "string",
            "format": "date-time"
          },
          "lifecycleModelId": {
            "const": "AMN_PAYLOAD_ALLOCATION_LIFECYCLE_V1"
          },
          "capacity": {
            "type": "object"
          },
          "passengers": {
            "type": "object"
          },
          "cargo": {
            "type": "object"
          },
          "provenance": {
            "type": "object"
          }
        }
      },
      "PayloadConfirmation": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "payloadRequestId",
          "externalFlightId",
          "operatingDate",
          "externalBookingId",
          "externalDispatchId",
          "externalOfpId"
        ],
        "properties": {
          "payloadRequestId": {
            "type": "string",
            "minLength": 1
          },
          "externalFlightId": {
            "type": "string",
            "minLength": 1
          },
          "operatingDate": {
            "type": "string",
            "format": "date"
          },
          "externalBookingId": {
            "type": "string",
            "minLength": 1
          },
          "externalDispatchId": {
            "type": "string",
            "minLength": 1
          },
          "externalOfpId": {
            "type": "string",
            "minLength": 1
          }
        }
      },
      "Pirep": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "externalPirepId",
          "externalFlightId",
          "operatingDate",
          "operationalStatus",
          "actualPassengers",
          "actualCargoWeightKg"
        ],
        "properties": {
          "externalPirepId": {
            "type": "string",
            "minLength": 1
          },
          "externalFlightId": {
            "type": "string",
            "minLength": 1
          },
          "operatingDate": {
            "type": "string",
            "format": "date"
          },
          "operationalStatus": {
            "enum": [
              "COMPLETED",
              "CANCELLED"
            ]
          },
          "actualPassengers": {
            "type": "integer",
            "minimum": 0
          },
          "actualCargoWeightKg": {
            "type": "integer",
            "minimum": 0
          },
          "scheduledArrivalAt": {
            "type": "string",
            "format": "date-time",
            "description": "UTC scheduled arrival; required for completed-flight world feedback"
          },
          "actualArrivalAt": {
            "type": "string",
            "format": "date-time",
            "description": "UTC actual arrival; required for completed-flight world feedback"
          }
        }
      }
    }
  }
}