Cosmos API
    • Overview
    • Getting started
    • Authentication
    • Environments
    • Rate Limits & Quotas
    • Error Handling
    • Idempotency & State management
    • Forward Compatibility
    • Upsert flight legs
      POST
    • Schemas
      • IngestRequest
      • FlightLeg
      • Delay
      • PassengersPerCabinClass
      • SpecialServices
      • TurnaroundFeedbackCheck
      • IngestResponse
      • MishandledBag
      • IngestResult
      • IngestSummary
      • ValidationError
      • ErrorResponse
    Open appWebsiteStatusLinkedin
    Open appWebsiteStatusLinkedin

    Idempotency & State management

    Cosmos uses a full-state replacement model. If a match exists, the record is updated. Otherwise, a new record is created. Requests are idempotent and safe to retry. Thus, always send the complete current state of a flight leg, not just the fields that changed. Partial updates will cause data loss.

    Match key#

    Flight legs are matched by four fields:
    FieldExample
    airlineEW
    flight_number1234
    originCGN
    scheduled_departure_at2026-03-24T08:30:00Z
    WARNING
    destination is not part of the match key. If a flight is diverted to a different destination, updating the destination field will update the existing record — it will not create a new one.

    Full-state replacement#

    Every field you include will overwrite the existing value. Fields set to null will be cleared. Omitted optional fields will also be set to null — so always send the full state.
    This applies to all nested objects:
    Delays
    Passengers
    Special Services
    Turnaround Checks
    Send the full list of current delay codes every time. Cosmos compares the incoming set against existing delays (matched by code + subcode):
    New codes → create incidents
    Removed codes → deactivate incidents
    Changed minutes → update existing incidents
    Empty array [] → deactivates all existing delays

    Nullable fields#

    Send null for optional fields where no data is available:
    Fieldnull means
    actual_departure_atFlight has not yet departed
    cancelled_atFlight is not cancelled
    aircraft_typeAircraft type unknown
    gateGate not assigned
    DANGER
    Omitting an optional field has the same effect as sending null — the existing value will be cleared. Always include every field in your payload, even if the value hasn't changed.

    Best practice#

    Build your integration to always export the full current state of each flight leg from your source system.
    Do not attempt to track deltas or send partial updates.
    Previous
    Error Handling
    Next
    Forward Compatibility
    Built with