docs/api/AviationService.openapi.json

Rama main · réplica de lectura del repositorio original.

{"components":{"schemas":{"AirportDelayAlert":{"description":"AirportDelayAlert represents a flight delay advisory at an airport.\n Sourced from FAA and Eurocontrol.","properties":{"avgDelayMinutes":{"description":"Average delay in minutes.","format":"int32","type":"integer"},"cancelledFlights":{"description":"Number of cancelled flights.","format":"int32","type":"integer"},"city":{"description":"City where the airport is located.","type":"string"},"country":{"description":"Country code (ISO 3166-1 alpha-2).","type":"string"},"delayType":{"description":"FlightDelayType represents the type of flight delay.","enum":["FLIGHT_DELAY_TYPE_UNSPECIFIED","FLIGHT_DELAY_TYPE_GROUND_STOP","FLIGHT_DELAY_TYPE_GROUND_DELAY","FLIGHT_DELAY_TYPE_DEPARTURE_DELAY","FLIGHT_DELAY_TYPE_ARRIVAL_DELAY","FLIGHT_DELAY_TYPE_GENERAL","FLIGHT_DELAY_TYPE_CLOSURE"],"type":"string"},"delayedFlightsPct":{"description":"Percentage of delayed flights.","format":"double","type":"number"},"iata":{"description":"IATA airport code (e.g., \"JFK\").","type":"string"},"icao":{"description":"ICAO airport code (e.g., \"KJFK\").","type":"string"},"id":{"description":"Unique alert identifier.","minLength":1,"type":"string"},"location":{"$ref":"#/components/schemas/GeoCoordinates"},"name":{"description":"Airport name.","type":"string"},"reason":{"description":"Human-readable reason for delays.","type":"string"},"region":{"description":"AirportRegion represents the geographic region of an airport.","enum":["AIRPORT_REGION_UNSPECIFIED","AIRPORT_REGION_AMERICAS","AIRPORT_REGION_EUROPE","AIRPORT_REGION_APAC","AIRPORT_REGION_MENA","AIRPORT_REGION_AFRICA"],"type":"string"},"severity":{"description":"FlightDelaySeverity represents the severity of flight delays at an airport.\n Maps to TS union: 'normal' | 'minor' | 'moderate' | 'major' | 'severe' | 'unknown'.","enum":["FLIGHT_DELAY_SEVERITY_UNSPECIFIED","FLIGHT_DELAY_SEVERITY_NORMAL","FLIGHT_DELAY_SEVERITY_MINOR","FLIGHT_DELAY_SEVERITY_MODERATE","FLIGHT_DELAY_SEVERITY_MAJOR","FLIGHT_DELAY_SEVERITY_SEVERE","FLIGHT_DELAY_SEVERITY_UNKNOWN"],"type":"string"},"source":{"description":"FlightDelaySource represents the source of delay data.","enum":["FLIGHT_DELAY_SOURCE_UNSPECIFIED","FLIGHT_DELAY_SOURCE_FAA","FLIGHT_DELAY_SOURCE_EUROCONTROL","FLIGHT_DELAY_SOURCE_COMPUTED","FLIGHT_DELAY_SOURCE_AVIATIONSTACK","FLIGHT_DELAY_SOURCE_NOTAM"],"type":"string"},"totalFlights":{"description":"Total flights scheduled.","format":"int32","type":"integer"},"updatedAt":{"description":"Last data update time, as Unix epoch milliseconds.. Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"}},"required":["id"],"type":"object"},"AirportOpsSummary":{"description":"AirportOpsSummary contains operational health metrics for a single airport.","properties":{"avgDelayMinutes":{"description":"Average delay in minutes across delayed flights.","format":"int32","type":"integer"},"cancellationRate":{"description":"Cancellation rate as a percentage (0-100).","format":"double","type":"number"},"closureStatus":{"description":"Whether the airport is currently closed.","type":"boolean"},"delayPct":{"description":"Percentage of flights currently delayed (0-100).","format":"double","type":"number"},"iata":{"description":"IATA airport code.","type":"string"},"icao":{"description":"ICAO airport code.","type":"string"},"name":{"description":"Airport name.","type":"string"},"notamFlags":{"items":{"description":"Active NOTAM summary flags (e.g., \"RWY 06/24 CLSD\", \"LOW VIS OPS\").","type":"string"},"type":"array"},"severity":{"description":"FlightDelaySeverity represents the severity of flight delays at an airport.\n Maps to TS union: 'normal' | 'minor' | 'moderate' | 'major' | 'severe' | 'unknown'.","enum":["FLIGHT_DELAY_SEVERITY_UNSPECIFIED","FLIGHT_DELAY_SEVERITY_NORMAL","FLIGHT_DELAY_SEVERITY_MINOR","FLIGHT_DELAY_SEVERITY_MODERATE","FLIGHT_DELAY_SEVERITY_MAJOR","FLIGHT_DELAY_SEVERITY_SEVERE","FLIGHT_DELAY_SEVERITY_UNKNOWN"],"type":"string"},"source":{"description":"Data source identifier.","type":"string"},"timezone":{"description":"IANA timezone (e.g., \"Europe/Istanbul\").","type":"string"},"topDelayReasons":{"items":{"description":"Top reasons for delays.","type":"string"},"type":"array"},"totalFlights":{"description":"Total flights in the observation window.","format":"int32","type":"integer"},"updatedAt":{"description":"Last update time as Unix epoch milliseconds.. Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"}},"type":"object"},"AirportRef":{"description":"AirportRef is a lightweight reference to an airport.","properties":{"iata":{"description":"IATA airport code (e.g., \"IST\").","type":"string"},"icao":{"description":"ICAO airport code (e.g., \"LTFM\").","type":"string"},"name":{"description":"Airport name (e.g., \"Istanbul Airport\").","type":"string"},"timezone":{"description":"IANA timezone (e.g., \"Europe/Istanbul\").","type":"string"}},"type":"object"},"AviationNewsItem":{"description":"AviationNewsItem represents a single aviation news article or press release.","properties":{"id":{"description":"Unique item identifier (hash of URL).","type":"string"},"imageUrl":{"description":"Article image URL (if available).","type":"string"},"matchedEntities":{"items":{"description":"Entities matched from the query (airport codes, airline names).","type":"string"},"type":"array"},"publishedAt":{"description":"Publication time as Unix epoch milliseconds.. Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"},"snippet":{"description":"Short text snippet or description.","type":"string"},"sourceName":{"description":"Name of the news source (e.g., \"FlightGlobal\").","type":"string"},"title":{"description":"Article title.","type":"string"},"url":{"description":"Article URL.","type":"string"}},"type":"object"},"BillingVerificationError":{"description":"Returned with HTTP 503 when paid access cannot be confirmed right now: the billing provider is re-verifying a recently expired subscription, or the entitlement backend is unreachable. Retryable — honor Retry-After.","properties":{"code":{"description":"Machine-readable billing-verification state, mirrored in the X-Billing-Verification response header.","enum":["renewal_verification_pending","renewal_verification_failed","entitlement_verification_unavailable"],"type":"string"},"error":{"description":"Human-readable billing-verification failure reason.","type":"string"},"requiredTier":{"description":"Minimum entitlement tier required for this endpoint, when the denial came from a tier gate.","format":"int32","type":"integer"}},"required":["error","code"],"type":"object"},"Carrier":{"description":"Carrier represents an airline or aircraft operator.","properties":{"iataCode":{"description":"IATA two-letter airline code (e.g., \"TK\").","type":"string"},"icaoCode":{"description":"ICAO three-letter airline code (e.g., \"THY\").","type":"string"},"name":{"description":"Full airline name (e.g., \"Turkish Airlines\").","type":"string"}},"type":"object"},"CarrierOpsSummary":{"description":"CarrierOpsSummary contains delay and cancellation metrics for a carrier at an airport.","properties":{"airport":{"description":"Airport IATA code this summary applies to.","type":"string"},"avgDelayMinutes":{"description":"Average delay in minutes across delayed flights.","format":"int32","type":"integer"},"cancellationRate":{"description":"Cancellation rate (0-100).","format":"double","type":"number"},"cancelledCount":{"description":"Number of cancelled flights.","format":"int32","type":"integer"},"carrier":{"$ref":"#/components/schemas/Carrier"},"delayPct":{"description":"Delay percentage (0-100).","format":"double","type":"number"},"delayedCount":{"description":"Number of delayed flights.","format":"int32","type":"integer"},"totalFlights":{"description":"Total flights observed.","format":"int32","type":"integer"},"updatedAt":{"description":"Last update time as Unix epoch milliseconds.. Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"}},"type":"object"},"DatePriceEntry":{"description":"DatePriceEntry pairs a departure date (and optional return date) with its cheapest price.","properties":{"date":{"description":"Departure date in YYYY-MM-DD format.","type":"string"},"price":{"format":"double","type":"number"},"returnDate":{"description":"Return date in YYYY-MM-DD format; empty for one-way results.","type":"string"}},"type":"object"},"EmergencyFeed":{"description":"EmergencyFeed records success and failure separately for each exact code query.","properties":{"fetchedAt":{"description":"Retrieval time in epoch milliseconds.. Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"},"message":{"description":"Safe status explanation.","type":"string"},"source":{"description":"Provider name.","type":"string"},"squawk":{"description":"Requested squawk.","type":"string"},"status":{"description":"available, unavailable, or stale.","type":"string"}},"type":"object"},"EmergencyObservation":{"description":"EmergencyObservation is a reported Mode A code, not a confirmed incident.","properties":{"address":{"description":"Provider address, including a non-ICAO prefix when present.","type":"string"},"aircraftType":{"description":"Provider type code, empty when unknown.","type":"string"},"altitudeFt":{"description":"Barometric altitude in feet, absent when unknown or reported as ground.","format":"double","type":"number"},"callsign":{"description":"Reported callsign, empty when unknown.","type":"string"},"description":{"description":"Provider aircraft description, empty when unknown.","type":"string"},"groundSpeedKts":{"description":"Ground speed in knots, absent when unknown.","format":"double","type":"number"},"militaryFlag":{"description":"Military database bit, set, not_set, or unknown. This is not admission criteria.","type":"string"},"observedAt":{"description":"Last message time in epoch milliseconds, not squawk selection time. Zero means unknown.. Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"},"position":{"$ref":"#/components/schemas/EmergencyPosition"},"registration":{"description":"Provider registration, empty when unknown.","type":"string"},"source":{"description":"Observation provider.","type":"string"},"squawk":{"description":"Exact four-character transponder code.","type":"string"}},"type":"object"},"EmergencyPosition":{"description":"EmergencyPosition keeps the position clock separate from last contact.","properties":{"lat":{"description":"Latitude in degrees.","format":"double","type":"number"},"lon":{"description":"Longitude in degrees.","format":"double","type":"number"},"observedAt":{"description":"Provider position time in epoch milliseconds. Zero means unknown.. Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"}},"type":"object"},"Error":{"description":"Error is returned when a handler encounters an error. It contains a simple error message that the developer can customize.","properties":{"message":{"description":"Error message (e.g., 'user not found', 'database connection failed')","type":"string"}},"type":"object"},"FieldViolation":{"description":"FieldViolation describes a single validation error for a specific field.","properties":{"description":{"description":"Human-readable description of the validation violation (e.g., 'must be a valid email address', 'required field missing')","type":"string"},"field":{"description":"The field path that failed validation (e.g., 'user.email' for nested fields). For header validation, this will be the header name (e.g., 'X-API-Key')","type":"string"}},"required":["field","description"],"type":"object"},"FlightInstance":{"description":"FlightInstance represents a specific occurrence of a flight on a given date.","properties":{"actualArrival":{"description":"Actual arrival time as Unix epoch milliseconds (UTC).. Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"},"actualDeparture":{"description":"Actual departure time as Unix epoch milliseconds (UTC).. Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"},"aircraftIcao24":{"description":"ICAO 24-bit transponder address of the aircraft (hex, e.g., \"4b1805\").","type":"string"},"aircraftType":{"description":"Aircraft type designator (e.g., \"B738\").","type":"string"},"cancelled":{"description":"Whether the flight is cancelled.","type":"boolean"},"codeshareFlightNumbers":{"items":{"description":"Codeshare flight numbers marketed under this operating flight.","type":"string"},"type":"array"},"date":{"description":"Departure date in ISO 8601 format (e.g., \"2026-03-05\").","type":"string"},"delayMinutes":{"description":"Delay in minutes (0 if on time, negative if early).","format":"int32","type":"integer"},"destination":{"$ref":"#/components/schemas/AirportRef"},"diverted":{"description":"Whether the flight has been diverted.","type":"boolean"},"estimatedArrival":{"description":"Estimated arrival time as Unix epoch milliseconds (UTC).. Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"},"estimatedDeparture":{"description":"Estimated departure time as Unix epoch milliseconds (UTC).. Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"},"flightNumber":{"description":"IATA flight number (e.g., \"TK1952\").","type":"string"},"gate":{"description":"Departure gate (if available).","type":"string"},"operatingCarrier":{"$ref":"#/components/schemas/Carrier"},"origin":{"$ref":"#/components/schemas/AirportRef"},"scheduledArrival":{"description":"Scheduled arrival time as Unix epoch milliseconds (UTC).. Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"},"scheduledDeparture":{"description":"Scheduled departure time as Unix epoch milliseconds (UTC).. Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"},"source":{"description":"Data source provider name.","type":"string"},"status":{"description":"FlightInstanceStatus represents the operational status of a flight occurrence.","enum":["FLIGHT_INSTANCE_STATUS_UNSPECIFIED","FLIGHT_INSTANCE_STATUS_SCHEDULED","FLIGHT_INSTANCE_STATUS_BOARDING","FLIGHT_INSTANCE_STATUS_DEPARTED","FLIGHT_INSTANCE_STATUS_AIRBORNE","FLIGHT_INSTANCE_STATUS_LANDED","FLIGHT_INSTANCE_STATUS_ARRIVED","FLIGHT_INSTANCE_STATUS_CANCELLED","FLIGHT_INSTANCE_STATUS_DIVERTED","FLIGHT_INSTANCE_STATUS_UNKNOWN"],"type":"string"},"terminal":{"description":"Departure terminal (if available).","type":"string"},"updatedAt":{"description":"Last update time as Unix epoch milliseconds.. Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"}},"type":"object"},"ForbiddenError":{"description":"Returned when a PRO-gated endpoint denies access because the caller has no resolved authenticated user, entitlements cannot be verified, or the caller lacks the required entitlement tier.","properties":{"code":{"description":"Machine-readable denial code, present when the 403 is a billing-provider-confirmed subscription lapse (mirrored in the X-Billing-Verification response header).","enum":["subscription_lapsed"],"type":"string"},"currentTier":{"description":"Caller entitlement tier when known.","format":"int32","type":"integer"},"error":{"description":"Human-readable entitlement failure reason.","type":"string"},"planKey":{"description":"Caller plan key when known.","type":"string"},"requiredTier":{"description":"Minimum entitlement tier required for this endpoint.","format":"int32","type":"integer"}},"required":["error"],"type":"object"},"GatewayError":{"description":"Returned by gateway infrastructure errors before an RPC handler runs, such as origin, routing, method, authentication, or quota checks.","properties":{"error":{"description":"Gateway error reason or structured gateway failure details.","oneOf":[{"type":"string"},{"additionalProperties":true,"type":"object"}]}},"required":["error"],"type":"object"},"GeoCoordinates":{"description":"GeoCoordinates represents a geographic location using WGS84 coordinates.","properties":{"latitude":{"description":"Latitude in decimal degrees (-90 to 90).","format":"double","maximum":90,"minimum":-90,"type":"number"},"longitude":{"description":"Longitude in decimal degrees (-180 to 180).","format":"double","maximum":180,"minimum":-180,"type":"number"}},"type":"object"},"GetAirportOpsSummaryRequest":{"description":"GetAirportOpsSummaryRequest specifies which airports to summarize.","properties":{"airports":{"items":{"description":"IATA airport codes to query (e.g., [\"IST\", \"ESB\", \"LHR\"]).","maxItems":20,"minItems":1,"type":"string"},"maxItems":20,"minItems":1,"type":"array"}},"type":"object"},"GetAirportOpsSummaryResponse":{"description":"GetAirportOpsSummaryResponse contains operational summaries for requested airports.","properties":{"cacheHit":{"description":"Whether the response was served from cache.","type":"boolean"},"summaries":{"items":{"$ref":"#/components/schemas/AirportOpsSummary"},"type":"array"}},"type":"object"},"GetCarrierOpsRequest":{"description":"GetCarrierOpsRequest specifies parameters for carrier operations metrics.","properties":{"airports":{"items":{"description":"IATA airport codes to aggregate carrier metrics from.","maxItems":20,"minItems":1,"type":"string"},"maxItems":20,"minItems":1,"type":"array"},"minFlights":{"description":"Minimum number of flights required to include a carrier (default: 3).\n The generated GET decoder emits 0 when the query param is absent, and 0\n means \"use the default\" in the handler — an explicit 0 is not a usable\n filter (every group has \u003e= 1 flight).","format":"int32","minimum":0,"type":"integer"}},"type":"object"},"GetCarrierOpsResponse":{"description":"GetCarrierOpsResponse contains carrier operations metrics.","properties":{"carriers":{"items":{"$ref":"#/components/schemas/CarrierOpsSummary"},"type":"array"},"source":{"description":"Data source identifier.","type":"string"},"updatedAt":{"description":"Last update time as Unix epoch milliseconds.. Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"}},"type":"object"},"GetFlightStatusRequest":{"description":"GetFlightStatusRequest specifies a flight to look up.","properties":{"date":{"description":"Departure date in ISO 8601 format (e.g., \"2026-03-05\").","type":"string"},"flightNumber":{"description":"IATA flight number (e.g., \"TK1952\").","maxLength":10,"minLength":3,"type":"string"},"origin":{"description":"Optional origin airport IATA code to disambiguate.","type":"string"}},"required":["flightNumber","date"],"type":"object"},"GetFlightStatusResponse":{"description":"GetFlightStatusResponse contains flight status results.","properties":{"cacheHit":{"description":"Whether the response was served from cache.","type":"boolean"},"flights":{"items":{"$ref":"#/components/schemas/FlightInstance"},"type":"array"},"source":{"description":"Data source identifier.","type":"string"}},"type":"object"},"GetYoutubeLiveStreamInfoRequest":{"description":"GetYoutubeLiveStreamInfoRequest names the YouTube video to look up.","properties":{"channel":{"deprecated":true,"description":"Deprecated: YouTube channel handle or ID. Channel live detection is retired; a channel-only query returns error \"channel_live_detection_retired\".","type":"string"},"videoId":{"description":"YouTube video ID to name.","type":"string"}},"type":"object"},"GetYoutubeLiveStreamInfoResponse":{"description":"GetYoutubeLiveStreamInfoResponse containing the oEmbed lookup result.","properties":{"channelExists":{"deprecated":true,"description":"Deprecated: true only when the oEmbed lookup succeeded, so it now carries exactly error == \"\".","type":"boolean"},"channelName":{"description":"Human-readable channel name.","type":"string"},"error":{"description":"\"channel_live_detection_retired\" for a channel-only query, or why the video lookup failed.","type":"string"},"hlsUrl":{"deprecated":true,"description":"Always empty: YouTube manifest URLs are no longer returned.","type":"string"},"isLive":{"deprecated":true,"description":"Always false: oEmbed does not report whether a video is live.","type":"boolean"},"title":{"description":"Video title.","type":"string"},"videoId":{"description":"Video ID that was looked up.","type":"string"}},"type":"object"},"GoogleFlightLeg":{"description":"GoogleFlightLeg represents a single flight segment (one plane, one takeoff and landing).","properties":{"airlineCode":{"type":"string"},"arrivalAirport":{"type":"string"},"arrivalDatetime":{"type":"string"},"departureAirport":{"type":"string"},"departureDatetime":{"description":"ISO 8601 local datetime, e.g. \"2025-06-01T08:45\".","type":"string"},"durationMinutes":{"format":"int32","type":"integer"},"flightNumber":{"type":"string"}},"type":"object"},"GoogleFlightResult":{"description":"GoogleFlightResult represents a complete itinerary (one or more legs).","properties":{"durationMinutes":{"format":"int32","type":"integer"},"legs":{"items":{"$ref":"#/components/schemas/GoogleFlightLeg"},"type":"array"},"price":{"format":"double","type":"number"},"stops":{"format":"int32","type":"integer"}},"type":"object"},"InvalidRequestBodyError":{"description":"Returned when a JSON POST request body is empty or malformed.","properties":{"message":{"description":"Invalid request body","type":"string"}},"required":["message"],"type":"object"},"JmespathProjectionError":{"description":"Returned when a REST jmespath projection is invalid or exceeds the expression/output byte limits.","properties":{"_jmespath_error":{"description":"Projection error discriminator and details.","type":"string"},"original_keys":{"description":"Top-level keys or shape of the unprojected response.","items":{"type":"string"},"type":"array"}},"required":["_jmespath_error","original_keys"],"type":"object"},"ListAircraftEmergenciesRequest":{"description":"ListAircraftEmergenciesRequest has no filters. Coverage is provider reception.","type":"object"},"ListAircraftEmergenciesResponse":{"description":"ListAircraftEmergenciesResponse preserves observations and per-query availability.","properties":{"feeds":{"items":{"$ref":"#/components/schemas/EmergencyFeed"},"type":"array"},"observations":{"items":{"$ref":"#/components/schemas/EmergencyObservation"},"type":"array"}},"type":"object"},"ListAirportDelaysRequest":{"description":"ListAirportDelaysRequest specifies filters for retrieving airport delay alerts.","properties":{"cursor":{"description":"Cursor for next page.\n Accepted but currently ignored; no-op until this handler supports the parameter.","type":"string"},"minSeverity":{"description":"FlightDelaySeverity represents the severity of flight delays at an airport.\n Maps to TS union: 'normal' | 'minor' | 'moderate' | 'major' | 'severe' | 'unknown'.","enum":["FLIGHT_DELAY_SEVERITY_UNSPECIFIED","FLIGHT_DELAY_SEVERITY_NORMAL","FLIGHT_DELAY_SEVERITY_MINOR","FLIGHT_DELAY_SEVERITY_MODERATE","FLIGHT_DELAY_SEVERITY_MAJOR","FLIGHT_DELAY_SEVERITY_SEVERE","FLIGHT_DELAY_SEVERITY_UNKNOWN"],"type":"string"},"pageSize":{"description":"Maximum items per page (1-100).\n Accepted but currently ignored; no-op until this handler supports the parameter.","format":"int32","type":"integer"},"region":{"description":"AirportRegion represents the geographic region of an airport.","enum":["AIRPORT_REGION_UNSPECIFIED","AIRPORT_REGION_AMERICAS","AIRPORT_REGION_EUROPE","AIRPORT_REGION_APAC","AIRPORT_REGION_MENA","AIRPORT_REGION_AFRICA"],"type":"string"}},"type":"object"},"ListAirportDelaysResponse":{"description":"ListAirportDelaysResponse contains airport delay alerts matching the request.","properties":{"alerts":{"items":{"$ref":"#/components/schemas/AirportDelayAlert"},"type":"array"},"pagination":{"$ref":"#/components/schemas/PaginationResponse"}},"type":"object"},"ListAirportFlightsRequest":{"description":"ListAirportFlightsRequest specifies parameters for retrieving recent flights at an airport.","properties":{"airport":{"description":"IATA airport code (e.g., \"IST\").","maxLength":4,"minLength":3,"type":"string"},"direction":{"description":"FlightDirection specifies whether to retrieve departures, arrivals, or both.","enum":["FLIGHT_DIRECTION_UNSPECIFIED","FLIGHT_DIRECTION_DEPARTURE","FLIGHT_DIRECTION_ARRIVAL","FLIGHT_DIRECTION_BOTH"],"type":"string"},"limit":{"description":"Maximum number of flights to return (1-100).","format":"int32","maximum":100,"minimum":1,"type":"integer"}},"required":["airport"],"type":"object"},"ListAirportFlightsResponse":{"description":"ListAirportFlightsResponse contains recent flights at an airport.","properties":{"flights":{"items":{"$ref":"#/components/schemas/FlightInstance"},"type":"array"},"source":{"description":"Data source identifier.","type":"string"},"totalAvailable":{"description":"Total number of flights available from the provider.","format":"int32","type":"integer"},"updatedAt":{"description":"Last update time as Unix epoch milliseconds.. Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"}},"type":"object"},"ListAviationNewsRequest":{"description":"ListAviationNewsRequest specifies filters for aviation news retrieval.","properties":{"entities":{"items":{"description":"Entities to filter by (airline names, airport codes, route strings).","maxItems":10,"minItems":1,"type":"string"},"maxItems":10,"minItems":1,"type":"array"},"maxItems":{"description":"Maximum number of news items to return (1-50).","format":"int32","maximum":50,"minimum":1,"type":"integer"},"windowHours":{"description":"Time window in hours to look back (1-168).","format":"int32","maximum":168,"minimum":1,"type":"integer"}},"type":"object"},"ListAviationNewsResponse":{"description":"ListAviationNewsResponse contains filtered aviation news items.","properties":{"items":{"items":{"$ref":"#/components/schemas/AviationNewsItem"},"type":"array"},"source":{"description":"Data source identifier.","type":"string"},"updatedAt":{"description":"Last update time as Unix epoch milliseconds.. Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"}},"type":"object"},"PaginationResponse":{"description":"PaginationResponse contains pagination metadata returned alongside list results.","properties":{"nextCursor":{"description":"Cursor for fetching the next page. Empty string indicates no more pages.","type":"string"},"totalCount":{"description":"Total count of items matching the query, if known. Zero if the total is unknown.","format":"int32","type":"integer"}},"type":"object"},"PositionSample":{"description":"PositionSample represents a single aircraft position observation.","properties":{"altitudeM":{"description":"Barometric altitude in metres.","format":"double","type":"number"},"callsign":{"description":"ATC callsign (e.g., \"THY7CX\").","type":"string"},"groundSpeedKts":{"description":"Ground speed in knots.","format":"double","type":"number"},"icao24":{"description":"ICAO 24-bit transponder address (hex, e.g., \"4b1805\").","type":"string"},"lat":{"description":"Latitude in decimal degrees.","format":"double","type":"number"},"lon":{"description":"Longitude in decimal degrees.","format":"double","type":"number"},"observedAt":{"description":"Observation time as Unix epoch milliseconds.. Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"},"onGround":{"description":"Whether the aircraft is on the ground.","type":"boolean"},"source":{"description":"PositionSource identifies the provider of aircraft position data.","enum":["POSITION_SOURCE_UNSPECIFIED","POSITION_SOURCE_WINGBITS","POSITION_SOURCE_SIMULATED"],"type":"string"},"trackDeg":{"description":"True track over ground in degrees (0 = North, clockwise).","format":"double","type":"number"},"verticalRate":{"description":"Vertical rate in metres per second (positive = climbing).","format":"double","type":"number"}},"type":"object"},"PriceQuote":{"description":"PriceQuote represents a single flight price offer from a provider.","properties":{"bookingUrl":{"description":"Booking URL or deep-link (if available).","type":"string"},"cabin":{"description":"CabinClass represents the travel class for a flight ticket.","enum":["CABIN_CLASS_UNSPECIFIED","CABIN_CLASS_ECONOMY","CABIN_CLASS_PREMIUM_ECONOMY","CABIN_CLASS_BUSINESS","CABIN_CLASS_FIRST"],"type":"string"},"carrier":{"$ref":"#/components/schemas/Carrier"},"checkoutRef":{"description":"Reference used during the checkout process (for follow-up actions).","type":"string"},"currency":{"description":"ISO 4217 currency code (e.g., \"EUR\", \"USD\", \"TRY\").","type":"string"},"departureDate":{"description":"Outbound departure date (ISO 8601).","type":"string"},"destination":{"description":"Destination airport IATA code.","type":"string"},"durationMinutes":{"description":"Total travel duration in minutes.","format":"int32","type":"integer"},"expiresAt":{"description":"Time when this quote expires, as Unix epoch milliseconds.. Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"},"id":{"description":"Unique quote identifier.","type":"string"},"isIndicative":{"description":"Whether the price is indicative rather than bookable.","type":"boolean"},"observedAt":{"description":"Time when this quote was observed, as Unix epoch milliseconds.. Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"},"origin":{"description":"Origin airport IATA code.","type":"string"},"priceAmount":{"description":"Total price amount.","format":"double","type":"number"},"provider":{"description":"Provider name (e.g., \"amadeus\", \"demo\").","type":"string"},"returnDate":{"description":"Return date (ISO 8601), empty for one-way.","type":"string"},"stops":{"description":"Number of stops (0 = nonstop).","format":"int32","type":"integer"}},"type":"object"},"RateLimitError":{"description":"Returned when a gateway or handler rate limit rejects the request.","properties":{"error":{"description":"Human-readable rate-limit failure reason.","type":"string"}},"required":["error"],"type":"object"},"SearchFlightPricesRequest":{"description":"SearchFlightPricesRequest specifies parameters for a flight price search.","properties":{"adults":{"description":"Number of adult passengers (1-9).\n Accepted but currently ignored; quotes are per-person and the count does not filter.","format":"int32","maximum":9,"minimum":1,"type":"integer"},"cabin":{"description":"CabinClass represents the travel class for a flight ticket.","enum":["CABIN_CLASS_UNSPECIFIED","CABIN_CLASS_ECONOMY","CABIN_CLASS_PREMIUM_ECONOMY","CABIN_CLASS_BUSINESS","CABIN_CLASS_FIRST"],"type":"string"},"currency":{"description":"ISO 4217 currency code for prices (e.g., \"usd\", \"eur\", \"try\").","type":"string"},"departureDate":{"description":"Outbound departure date (ISO 8601).","type":"string"},"destination":{"description":"Destination airport IATA code.","maxLength":4,"minLength":3,"type":"string"},"market":{"description":"Market/locale code (e.g., \"us\", \"tr\").","type":"string"},"maxResults":{"description":"Maximum number of quotes to return (1-50).","format":"int32","maximum":50,"minimum":1,"type":"integer"},"nonstopOnly":{"description":"Whether to restrict to nonstop flights only.","type":"boolean"},"origin":{"description":"Origin airport IATA code.","maxLength":4,"minLength":3,"type":"string"},"returnDate":{"description":"Return date (ISO 8601), empty for one-way.","type":"string"}},"required":["origin","destination","departureDate"],"type":"object"},"SearchFlightPricesResponse":{"description":"SearchFlightPricesResponse contains flight price offers.","properties":{"degraded":{"description":"True when the live provider could not satisfy the request — missing\n credentials, upstream failure, or zero results. Mirrors the\n searchGoogleFlights pattern so clients can render distinct messages\n for each error class.","type":"boolean"},"error":{"description":"Discriminator for the degraded state: \"\" (ok), \"missing_credentials\"\n (TRAVELPAYOUTS_API_TOKEN unset), \"upstream_error\" (provider call\n threw), \"no_results\" (provider returned empty for this route).","type":"string"},"isDemoMode":{"description":"Whether results are from demo/simulated mode. Requires explicit\n AVIATION_DEMO_PRICES=1 opt-in on the server. Never true in default\n self-host / production runs. See issue #3756.","type":"boolean"},"isIndicative":{"description":"Whether returned prices are indicative (subject to change).","type":"boolean"},"provider":{"description":"Provider name: \"travelpayouts_data\", \"demo\", or \"none\" when no live\n provider is configured.","type":"string"},"quotes":{"items":{"$ref":"#/components/schemas/PriceQuote"},"type":"array"},"updatedAt":{"description":"Last update time as Unix epoch milliseconds.. Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"}},"type":"object"},"SearchGoogleDatesRequest":{"description":"SearchGoogleDatesRequest specifies parameters for a Google Flights date-range price search.","properties":{"airlines":{"items":{"description":"Airline IATA codes to filter by (e.g. [\"BA\", \"AA\"]).","type":"string"},"type":"array"},"cabinClass":{"description":"Cabin class: ECONOMY, PREMIUM_ECONOMY, BUSINESS, or FIRST.","type":"string"},"departureWindow":{"description":"Departure time window in HH-HH format (e.g. \"6-20\").","type":"string"},"destination":{"description":"Arrival airport IATA code (e.g. \"LHR\").","type":"string"},"endDate":{"description":"End of date range in YYYY-MM-DD format.","type":"string"},"isRoundTrip":{"description":"Whether to search for round-trip flights.","type":"boolean"},"maxStops":{"description":"Stop filter: ANY, NON_STOP, ONE_STOP, or TWO_PLUS_STOPS.","type":"string"},"origin":{"description":"Departure airport IATA code (e.g. \"JFK\").","type":"string"},"passengers":{"description":"Number of adult passengers (1-9).","format":"int32","type":"integer"},"sortByPrice":{"description":"Whether to sort results by price (lowest first).","type":"boolean"},"startDate":{"description":"Start of date range in YYYY-MM-DD format.","type":"string"},"tripDuration":{"description":"Trip duration in days (required for round-trip searches).","format":"int32","type":"integer"}},"type":"object"},"SearchGoogleDatesResponse":{"description":"SearchGoogleDatesResponse contains cheapest-date results from Google Flights.","properties":{"dates":{"items":{"$ref":"#/components/schemas/DatePriceEntry"},"type":"array"},"degraded":{"type":"boolean"},"error":{"type":"string"}},"type":"object"},"SearchGoogleFlightsRequest":{"description":"SearchGoogleFlightsRequest specifies parameters for a Google Flights search.","properties":{"airlines":{"items":{"description":"Airline IATA codes to filter by (e.g. [\"BA\", \"AA\"]).","type":"string"},"type":"array"},"cabinClass":{"description":"Cabin class: ECONOMY, PREMIUM_ECONOMY, BUSINESS, or FIRST.","type":"string"},"departureDate":{"description":"Departure date in YYYY-MM-DD format.","type":"string"},"departureWindow":{"description":"Departure time window in HH-HH format (e.g. \"6-20\").","type":"string"},"destination":{"description":"Arrival airport IATA code (e.g. \"LHR\").","type":"string"},"maxStops":{"description":"Stop filter: ANY, NON_STOP, ONE_STOP, or TWO_PLUS_STOPS.","type":"string"},"origin":{"description":"Departure airport IATA code (e.g. \"JFK\").","type":"string"},"passengers":{"description":"Number of adult passengers (1-9).","format":"int32","type":"integer"},"returnDate":{"description":"Return date in YYYY-MM-DD format; omit for one-way.","type":"string"},"sortBy":{"description":"Sort order: CHEAPEST, DURATION, DEPARTURE_TIME, or ARRIVAL_TIME.","type":"string"}},"type":"object"},"SearchGoogleFlightsResponse":{"description":"SearchGoogleFlightsResponse contains flight results from Google Flights.","properties":{"degraded":{"type":"boolean"},"error":{"type":"string"},"flights":{"items":{"$ref":"#/components/schemas/GoogleFlightResult"},"type":"array"}},"type":"object"},"TrackAircraftRequest":{"description":"TrackAircraftRequest specifies an aircraft to track.","properties":{"callsign":{"description":"ATC callsign (e.g., \"THY7CX\").","type":"string"},"icao24":{"description":"ICAO 24-bit transponder address (hex, e.g., \"4b1805\").","type":"string"},"neLat":{"description":"Optional bounding box north-east latitude.","format":"double","type":"number"},"neLon":{"description":"Optional bounding box north-east longitude.","format":"double","type":"number"},"swLat":{"description":"Optional bounding box south-west latitude.","format":"double","type":"number"},"swLon":{"description":"Optional bounding box south-west longitude.","format":"double","type":"number"}},"type":"object"},"TrackAircraftResponse":{"description":"TrackAircraftResponse contains aircraft position observations.","properties":{"positions":{"items":{"$ref":"#/components/schemas/PositionSample"},"type":"array"},"source":{"description":"Data source identifier.","type":"string"},"updatedAt":{"description":"Last update time as Unix epoch milliseconds.. Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"}},"type":"object"},"UnauthorizedError":{"description":"Returned when the API key is missing, malformed, or lacks current API access.","properties":{"error":{"description":"Human-readable error message.","type":"string"}},"required":["error"],"type":"object"},"ValidationError":{"description":"ValidationError is returned when request validation fails. It contains a list of field violations describing what went wrong.","properties":{"violations":{"description":"List of validation violations","items":{"$ref":"#/components/schemas/FieldViolation"},"type":"array"}},"required":["violations"],"type":"object"}},"securitySchemes":{"ApiKeyHeader":{"description":"Alias header for the WorldMonitor API key (X-WorldMonitor-Key).","in":"header","name":"X-Api-Key","type":"apiKey"},"BearerAuth":{"description":"Bearer token: a Clerk-issued JWT for browser session flows, passed as Authorization: Bearer \u003ctoken\u003e.","scheme":"bearer","type":"http"},"WorldMonitorKey":{"description":"User-issued WorldMonitor API key.","in":"header","name":"X-WorldMonitor-Key","type":"apiKey"}}},"info":{"title":"AviationService API","version":"1.0.0"},"openapi":"3.1.0","paths":{"/api/aviation/v1/get-airport-ops-summary":{"get":{"description":"GetAirportOpsSummary returns watched-airport operational health, including delay percentages, average delay minutes, cancellation rates and closure status.","operationId":"GetAirportOpsSummary","parameters":[{"description":"IATA airport codes to query (e.g., [\"IST\", \"ESB\", \"LHR\"]).","example":["JFK"],"explode":true,"in":"query","name":"airports","required":false,"schema":{"items":{"type":"string"},"type":"array"},"style":"form"},{"description":"Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.","example":"keys(@)","in":"query","name":"jmespath","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"cacheHit":true,"summaries":[{"avgDelayMinutes":1,"cancellationRate":75.25,"closureStatus":true,"delayPct":1.5,"iata":"JFK"}]},"schema":{"$ref":"#/components/schemas/GetAirportOpsSummaryResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/JmespathProjectionError"}]}}},"description":"Validation error"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"description":"Missing or invalid API key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenError"}}},"description":"API access requires an active subscription (the API key's subscription is inactive or expired).","headers":{"X-Billing-Verification":{"description":"Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).","schema":{"type":"string"}}}},"429":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/RateLimitError"}]}}},"description":"Rate limit exceeded.","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Maximum requests allowed in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix epoch milliseconds when the active rate-limit window resets.","schema":{"type":"string"}}}},"503":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/BillingVerificationError"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (1-60).","schema":{"type":"string"}},"X-Billing-Verification":{"description":"Billing-verification state that produced this response (matches the body `code`).","schema":{"type":"string"}},"X-RateLimit-Mode":{"description":"Present with value degraded when a fail-closed rate-limit dependency is unavailable.","schema":{"type":"string"}},"X-Validation-Mode":{"description":"Present with value degraded when user API-key validation is temporarily unavailable.","schema":{"type":"string"}}}},"default":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Gateway or handler error response."}},"summary":"GetAirportOpsSummary","tags":["AviationService"]}},"/api/aviation/v1/get-carrier-ops":{"get":{"description":"GetCarrierOps returns delay and cancellation metrics grouped by carrier. PRO-gated. Requires an active Pro subscription.","operationId":"GetCarrierOps","parameters":[{"description":"IATA airport codes to aggregate carrier metrics from.","example":["JFK"],"explode":true,"in":"query","name":"airports","required":false,"schema":{"items":{"type":"string"},"type":"array"},"style":"form"},{"description":"Minimum number of flights required to include a carrier (default: 3).\n The generated GET decoder emits 0 when the query param is absent, and 0\n means \"use the default\" in the handler — an explicit 0 is not a usable\n filter (every group has \u003e= 1 flight).","example":1,"in":"query","name":"min_flights","required":false,"schema":{"format":"int32","type":"integer"}},{"description":"Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.","example":"keys(@)","in":"query","name":"jmespath","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"carriers":[{"airport":"JFK","avgDelayMinutes":1,"cancellationRate":75.25,"cancelledCount":1,"carrier":{"iataCode":"JFK","icaoCode":"example","name":"WorldMonitor Analyst"}}],"source":"example","updatedAt":1717200000000},"schema":{"$ref":"#/components/schemas/GetCarrierOpsResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/JmespathProjectionError"}]}}},"description":"Validation error"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"description":"Missing or invalid API key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenError"}}},"description":"Pro subscription required.","headers":{"X-Billing-Verification":{"description":"Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).","schema":{"type":"string"}}}},"429":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/RateLimitError"}]}}},"description":"Rate limit exceeded.","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Maximum requests allowed in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix epoch milliseconds when the active rate-limit window resets.","schema":{"type":"string"}}}},"503":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/BillingVerificationError"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (1-60).","schema":{"type":"string"}},"X-Billing-Verification":{"description":"Billing-verification state that produced this response (matches the body `code`).","schema":{"type":"string"}},"X-RateLimit-Mode":{"description":"Present with value degraded when a fail-closed rate-limit dependency is unavailable.","schema":{"type":"string"}},"X-Validation-Mode":{"description":"Present with value degraded when user API-key validation is temporarily unavailable.","schema":{"type":"string"}}}},"default":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Gateway or handler error response."}},"security":[{"WorldMonitorKey":[]},{"ApiKeyHeader":[]},{"BearerAuth":[]}],"summary":"GetCarrierOps","tags":["AviationService"]}},"/api/aviation/v1/get-flight-status":{"get":{"description":"GetFlightStatus looks up the current status of a specific flight. PRO-gated. Requires an active Pro subscription.","operationId":"GetFlightStatus","parameters":[{"description":"IATA flight number (e.g., \"TK1952\").","example":"JFK","in":"query","name":"flight_number","required":true,"schema":{"type":"string"}},{"description":"Departure date in ISO 8601 format (e.g., \"2026-03-05\").","example":"2026-01-15","in":"query","name":"date","required":true,"schema":{"type":"string"}},{"description":"Optional origin airport IATA code to disambiguate.","example":"JFK","in":"query","name":"origin","required":false,"schema":{"type":"string"}},{"description":"Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.","example":"keys(@)","in":"query","name":"jmespath","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"cacheHit":true,"flights":[{"actualArrival":1,"actualDeparture":1,"aircraftIcao24":"a835af","aircraftType":"all","cancelled":true}],"source":"example"},"schema":{"$ref":"#/components/schemas/GetFlightStatusResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/JmespathProjectionError"}]}}},"description":"Validation error"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"description":"Missing or invalid API key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenError"}}},"description":"Pro subscription required.","headers":{"X-Billing-Verification":{"description":"Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).","schema":{"type":"string"}}}},"429":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/RateLimitError"}]}}},"description":"Rate limit exceeded.","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Maximum requests allowed in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix epoch milliseconds when the active rate-limit window resets.","schema":{"type":"string"}}}},"503":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/BillingVerificationError"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (1-60).","schema":{"type":"string"}},"X-Billing-Verification":{"description":"Billing-verification state that produced this response (matches the body `code`).","schema":{"type":"string"}},"X-RateLimit-Mode":{"description":"Present with value degraded when a fail-closed rate-limit dependency is unavailable.","schema":{"type":"string"}},"X-Validation-Mode":{"description":"Present with value degraded when user API-key validation is temporarily unavailable.","schema":{"type":"string"}}}},"default":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Gateway or handler error response."}},"security":[{"WorldMonitorKey":[]},{"ApiKeyHeader":[]},{"BearerAuth":[]}],"summary":"GetFlightStatus","tags":["AviationService"]}},"/api/aviation/v1/get-youtube-live-stream-info":{"get":{"description":"GetYoutubeLiveStreamInfo names a YouTube video (title and channel name) through YouTube oEmbed. Channel live detection is retired: a channel-only query returns error \"channel_live_detection_retired\", and the channel, is_live and hls_url fields are deprecated.","operationId":"GetYoutubeLiveStreamInfo","parameters":[{"deprecated":true,"description":"Deprecated: YouTube channel handle or ID. Channel live detection is retired; a channel-only query returns error \"channel_live_detection_retired\".","example":"example","in":"query","name":"channel","required":false,"schema":{"type":"string"}},{"description":"YouTube video ID to name.","example":"example-id","in":"query","name":"video_id","required":false,"schema":{"type":"string"}},{"description":"Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.","example":"keys(@)","in":"query","name":"jmespath","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"channelExists":true,"channelName":"DW News","error":"","hlsUrl":"","isLive":false,"title":"DW News livestream","videoId":"LuKwFajn37U"},"schema":{"$ref":"#/components/schemas/GetYoutubeLiveStreamInfoResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/JmespathProjectionError"}]}}},"description":"Validation error"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"description":"Missing or invalid API key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenError"}}},"description":"API access requires an active subscription (the API key's subscription is inactive or expired).","headers":{"X-Billing-Verification":{"description":"Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).","schema":{"type":"string"}}}},"429":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/RateLimitError"}]}}},"description":"Rate limit exceeded.","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Maximum requests allowed in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix epoch milliseconds when the active rate-limit window resets.","schema":{"type":"string"}}}},"503":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/BillingVerificationError"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (1-60).","schema":{"type":"string"}},"X-Billing-Verification":{"description":"Billing-verification state that produced this response (matches the body `code`).","schema":{"type":"string"}},"X-RateLimit-Mode":{"description":"Present with value degraded when a fail-closed rate-limit dependency is unavailable.","schema":{"type":"string"}},"X-Validation-Mode":{"description":"Present with value degraded when user API-key validation is temporarily unavailable.","schema":{"type":"string"}}}},"default":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Gateway or handler error response."}},"summary":"GetYoutubeLiveStreamInfo","tags":["AviationService"]}},"/api/aviation/v1/list-aircraft-emergencies":{"get":{"description":"ListAircraftEmergencies returns reported 7500, 7600 and 7700 signals independently of military classification.\n The 200 schema describes the unprojected response. With jmespath, the result may instead be any JSON value, including an array, scalar, or null.","operationId":"ListAircraftEmergencies","parameters":[{"description":"Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.","example":"keys(@)","in":"query","name":"jmespath","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"feeds":[{"fetchedAt":1717200000000,"message":"Synthetic example.","source":"adsb.lol","squawk":"7500","status":"available"},{"fetchedAt":1717200000000,"message":"Synthetic example.","source":"adsb.lol","squawk":"7600","status":"available"},{"fetchedAt":1717200000000,"message":"Synthetic example.","source":"adsb.lol","squawk":"7700","status":"available"}],"observations":[{"address":"a00001","callsign":"SYNTHETIC","description":"Synthetic example. No observed incident.","militaryFlag":"unknown","observedAt":0,"source":"adsb.lol","squawk":"7500"}]},"schema":{"$ref":"#/components/schemas/ListAircraftEmergenciesResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/JmespathProjectionError"}]}}},"description":"Validation error"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"description":"Missing or invalid API key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenError"}}},"description":"API access requires an active subscription (the API key's subscription is inactive or expired).","headers":{"X-Billing-Verification":{"description":"Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).","schema":{"type":"string"}}}},"429":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/RateLimitError"}]}}},"description":"Rate limit exceeded.","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Maximum requests allowed in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix epoch milliseconds when the active rate-limit window resets.","schema":{"type":"string"}}}},"503":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/BillingVerificationError"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (1-60).","schema":{"type":"string"}},"X-Billing-Verification":{"description":"Billing-verification state that produced this response (matches the body `code`).","schema":{"type":"string"}},"X-RateLimit-Mode":{"description":"Present with value degraded when a fail-closed rate-limit dependency is unavailable.","schema":{"type":"string"}},"X-Validation-Mode":{"description":"Present with value degraded when user API-key validation is temporarily unavailable.","schema":{"type":"string"}}}},"default":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Gateway or handler error response."}},"summary":"ListAircraftEmergencies","tags":["AviationService"]}},"/api/aviation/v1/list-airport-delays":{"get":{"description":"ListAirportDelays returns delay status for each monitored airport from seeded FAA and AviationStack data plus NOTAM closures, marking unreported hubs unknown.","operationId":"ListAirportDelays","parameters":[{"description":"Maximum items per page (1-100).\n Accepted but currently ignored; no-op until this handler supports the parameter.","example":25,"in":"query","name":"page_size","required":false,"schema":{"format":"int32","type":"integer"}},{"description":"Cursor for next page.\n Accepted but currently ignored; no-op until this handler supports the parameter.","example":"next-page-token","in":"query","name":"cursor","required":false,"schema":{"type":"string"}},{"description":"Optional region filter.\n Accepted but currently ignored; no-op until this handler supports the parameter.","example":"AIRPORT_REGION_AMERICAS","in":"query","name":"region","required":false,"schema":{"enum":["AIRPORT_REGION_AMERICAS","AIRPORT_REGION_EUROPE","AIRPORT_REGION_APAC","AIRPORT_REGION_MENA","AIRPORT_REGION_AFRICA"],"type":"string"}},{"description":"Optional minimum severity filter.\n Accepted but currently ignored; no-op until this handler supports the parameter.","example":"FLIGHT_DELAY_SEVERITY_NORMAL","in":"query","name":"min_severity","required":false,"schema":{"enum":["FLIGHT_DELAY_SEVERITY_NORMAL","FLIGHT_DELAY_SEVERITY_MINOR","FLIGHT_DELAY_SEVERITY_MODERATE","FLIGHT_DELAY_SEVERITY_MAJOR","FLIGHT_DELAY_SEVERITY_SEVERE","FLIGHT_DELAY_SEVERITY_UNKNOWN"],"type":"string"}},{"description":"Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.","example":"keys(@)","in":"query","name":"jmespath","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"alerts":[{"avgDelayMinutes":1,"cancelledFlights":1,"city":"example","country":"US","delayType":"FLIGHT_DELAY_TYPE_GROUND_STOP","id":"example-id"}],"pagination":{"nextCursor":"next-page-token","totalCount":1}},"schema":{"$ref":"#/components/schemas/ListAirportDelaysResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/JmespathProjectionError"}]}}},"description":"Validation error"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"description":"Missing or invalid API key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenError"}}},"description":"API access requires an active subscription (the API key's subscription is inactive or expired).","headers":{"X-Billing-Verification":{"description":"Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).","schema":{"type":"string"}}}},"429":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/RateLimitError"}]}}},"description":"Rate limit exceeded.","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Maximum requests allowed in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix epoch milliseconds when the active rate-limit window resets.","schema":{"type":"string"}}}},"503":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/BillingVerificationError"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (1-60).","schema":{"type":"string"}},"X-Billing-Verification":{"description":"Billing-verification state that produced this response (matches the body `code`).","schema":{"type":"string"}},"X-RateLimit-Mode":{"description":"Present with value degraded when a fail-closed rate-limit dependency is unavailable.","schema":{"type":"string"}},"X-Validation-Mode":{"description":"Present with value degraded when user API-key validation is temporarily unavailable.","schema":{"type":"string"}}}},"default":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Gateway or handler error response."}},"summary":"ListAirportDelays","tags":["AviationService"]}},"/api/aviation/v1/list-airport-flights":{"get":{"description":"ListAirportFlights returns recent arrivals and departures with direction and limit filters, status and carrier. PRO-gated. Requires an active Pro subscription.","operationId":"ListAirportFlights","parameters":[{"description":"IATA airport code (e.g., \"IST\").","example":"JFK","in":"query","name":"airport","required":true,"schema":{"type":"string"}},{"description":"Direction filter.","example":"FLIGHT_DIRECTION_DEPARTURE","in":"query","name":"direction","required":false,"schema":{"enum":["FLIGHT_DIRECTION_DEPARTURE","FLIGHT_DIRECTION_ARRIVAL","FLIGHT_DIRECTION_BOTH"],"type":"string"}},{"description":"Maximum number of flights to return (1-100).","example":25,"in":"query","name":"limit","required":false,"schema":{"format":"int32","type":"integer"}},{"description":"Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.","example":"keys(@)","in":"query","name":"jmespath","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"flights":[{"actualArrival":1,"actualDeparture":1,"aircraftIcao24":"a835af","aircraftType":"all","cancelled":true}],"source":"example","totalAvailable":1,"updatedAt":1717200000000},"schema":{"$ref":"#/components/schemas/ListAirportFlightsResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/JmespathProjectionError"}]}}},"description":"Validation error"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"description":"Missing or invalid API key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenError"}}},"description":"Pro subscription required.","headers":{"X-Billing-Verification":{"description":"Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).","schema":{"type":"string"}}}},"429":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/RateLimitError"}]}}},"description":"Rate limit exceeded.","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Maximum requests allowed in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix epoch milliseconds when the active rate-limit window resets.","schema":{"type":"string"}}}},"503":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/BillingVerificationError"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (1-60).","schema":{"type":"string"}},"X-Billing-Verification":{"description":"Billing-verification state that produced this response (matches the body `code`).","schema":{"type":"string"}},"X-RateLimit-Mode":{"description":"Present with value degraded when a fail-closed rate-limit dependency is unavailable.","schema":{"type":"string"}},"X-Validation-Mode":{"description":"Present with value degraded when user API-key validation is temporarily unavailable.","schema":{"type":"string"}}}},"default":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Gateway or handler error response."}},"security":[{"WorldMonitorKey":[]},{"ApiKeyHeader":[]},{"BearerAuth":[]}],"summary":"ListAirportFlights","tags":["AviationService"]}},"/api/aviation/v1/list-aviation-news":{"get":{"description":"ListAviationNews returns articles from nine aviation RSS feeds such as FlightGlobal and Aviation Week, filtered by up to 10 entities over a 1-168 hour window.","operationId":"ListAviationNews","parameters":[{"description":"Entities to filter by (airline names, airport codes, route strings).","example":["example"],"explode":true,"in":"query","name":"entities","required":false,"schema":{"items":{"type":"string"},"type":"array"},"style":"form"},{"description":"Time window in hours to look back (1-168).","example":1,"in":"query","name":"window_hours","required":false,"schema":{"format":"int32","type":"integer"}},{"description":"Maximum number of news items to return (1-50).","example":1,"in":"query","name":"max_items","required":false,"schema":{"format":"int32","type":"integer"}},{"description":"Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.","example":"keys(@)","in":"query","name":"jmespath","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"items":[{"id":"example-id","imageUrl":"https://example.com/worldmonitor","matchedEntities":["example"],"publishedAt":1717200000000,"snippet":"example"}],"source":"example","updatedAt":1717200000000},"schema":{"$ref":"#/components/schemas/ListAviationNewsResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/JmespathProjectionError"}]}}},"description":"Validation error"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"description":"Missing or invalid API key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenError"}}},"description":"API access requires an active subscription (the API key's subscription is inactive or expired).","headers":{"X-Billing-Verification":{"description":"Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).","schema":{"type":"string"}}}},"429":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/RateLimitError"}]}}},"description":"Rate limit exceeded.","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Maximum requests allowed in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix epoch milliseconds when the active rate-limit window resets.","schema":{"type":"string"}}}},"503":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/BillingVerificationError"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (1-60).","schema":{"type":"string"}},"X-Billing-Verification":{"description":"Billing-verification state that produced this response (matches the body `code`).","schema":{"type":"string"}},"X-RateLimit-Mode":{"description":"Present with value degraded when a fail-closed rate-limit dependency is unavailable.","schema":{"type":"string"}},"X-Validation-Mode":{"description":"Present with value degraded when user API-key validation is temporarily unavailable.","schema":{"type":"string"}}}},"default":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Gateway or handler error response."}},"summary":"ListAviationNews","tags":["AviationService"]}},"/api/aviation/v1/search-flight-prices":{"get":{"description":"Search per-person flight price offers by route, dates and cabin, with indicative-price and provider status. PRO-gated. Requires an active Pro subscription.","operationId":"SearchFlightPrices","parameters":[{"description":"Origin airport IATA code.","example":"JFK","in":"query","name":"origin","required":true,"schema":{"type":"string"}},{"description":"Destination airport IATA code.","example":"LHR","in":"query","name":"destination","required":true,"schema":{"type":"string"}},{"description":"Outbound departure date (ISO 8601).","example":"2026-01-15","in":"query","name":"departure_date","required":true,"schema":{"type":"string"}},{"description":"Return date (ISO 8601), empty for one-way.","example":"2026-01-15","in":"query","name":"return_date","required":false,"schema":{"type":"string"}},{"description":"Number of adult passengers (1-9).\n Accepted but currently ignored; quotes are per-person and the count does not filter.","example":1,"in":"query","name":"adults","required":false,"schema":{"format":"int32","type":"integer"}},{"description":"Desired cabin class.","example":"CABIN_CLASS_ECONOMY","in":"query","name":"cabin","required":false,"schema":{"enum":["CABIN_CLASS_ECONOMY","CABIN_CLASS_PREMIUM_ECONOMY","CABIN_CLASS_BUSINESS","CABIN_CLASS_FIRST"],"type":"string"}},{"description":"Whether to restrict to nonstop flights only.","example":true,"in":"query","name":"nonstop_only","required":false,"schema":{"type":"boolean"}},{"description":"Maximum number of quotes to return (1-50).","example":1,"in":"query","name":"max_results","required":false,"schema":{"format":"int32","type":"integer"}},{"description":"ISO 4217 currency code for prices (e.g., \"usd\", \"eur\", \"try\").","example":"USD","in":"query","name":"currency","required":false,"schema":{"type":"string"}},{"description":"Market/locale code (e.g., \"us\", \"tr\").","example":"example","in":"query","name":"market","required":false,"schema":{"type":"string"}},{"description":"Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.","example":"keys(@)","in":"query","name":"jmespath","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"degraded":true,"error":"example","isDemoMode":true,"isIndicative":true,"provider":"worldmonitor"},"schema":{"$ref":"#/components/schemas/SearchFlightPricesResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/JmespathProjectionError"}]}}},"description":"Validation error"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"description":"Missing or invalid API key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenError"}}},"description":"Pro subscription required.","headers":{"X-Billing-Verification":{"description":"Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).","schema":{"type":"string"}}}},"429":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/RateLimitError"}]}}},"description":"Rate limit exceeded.","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Maximum requests allowed in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix epoch milliseconds when the active rate-limit window resets.","schema":{"type":"string"}}}},"503":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/BillingVerificationError"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (1-60).","schema":{"type":"string"}},"X-Billing-Verification":{"description":"Billing-verification state that produced this response (matches the body `code`).","schema":{"type":"string"}},"X-RateLimit-Mode":{"description":"Present with value degraded when a fail-closed rate-limit dependency is unavailable.","schema":{"type":"string"}},"X-Validation-Mode":{"description":"Present with value degraded when user API-key validation is temporarily unavailable.","schema":{"type":"string"}}}},"default":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Gateway or handler error response."}},"security":[{"WorldMonitorKey":[]},{"ApiKeyHeader":[]},{"BearerAuth":[]}],"summary":"SearchFlightPrices","tags":["AviationService"]}},"/api/aviation/v1/search-google-dates":{"get":{"description":"SearchGoogleDates returns the cheapest Google Flights fare per departure date over up to 31 days, one-way or round trip, with cabin and stop filters.","operationId":"SearchGoogleDates","parameters":[{"description":"Departure airport IATA code (e.g. \"JFK\").","example":"JFK","in":"query","name":"origin","required":false,"schema":{"type":"string"}},{"description":"Arrival airport IATA code (e.g. \"LHR\").","example":"LHR","in":"query","name":"destination","required":false,"schema":{"type":"string"}},{"description":"Start of date range in YYYY-MM-DD format.","example":"2026-01-15","in":"query","name":"start_date","required":false,"schema":{"type":"string"}},{"description":"End of date range in YYYY-MM-DD format.","example":"2026-01-15","in":"query","name":"end_date","required":false,"schema":{"type":"string"}},{"description":"Trip duration in days (required for round-trip searches).","example":42,"in":"query","name":"trip_duration","required":false,"schema":{"format":"int32","type":"integer"}},{"description":"Whether to search for round-trip flights.","example":true,"in":"query","name":"is_round_trip","required":false,"schema":{"type":"boolean"}},{"description":"Cabin class: ECONOMY, PREMIUM_ECONOMY, BUSINESS, or FIRST.","example":"ECONOMY","in":"query","name":"cabin_class","required":false,"schema":{"type":"string"}},{"description":"Stop filter: ANY, NON_STOP, ONE_STOP, or TWO_PLUS_STOPS.","example":"ANY","in":"query","name":"max_stops","required":false,"schema":{"type":"string"}},{"description":"Departure time window in HH-HH format (e.g. \"6-20\").","example":"6-20","in":"query","name":"departure_window","required":false,"schema":{"type":"string"}},{"description":"Airline IATA codes to filter by (e.g. [\"BA\", \"AA\"]).","example":["BA"],"explode":true,"in":"query","name":"airlines","required":false,"schema":{"items":{"type":"string"},"type":"array"},"style":"form"},{"description":"Whether to sort results by price (lowest first).","example":true,"in":"query","name":"sort_by_price","required":false,"schema":{"type":"boolean"}},{"description":"Number of adult passengers (1-9).","example":1,"in":"query","name":"passengers","required":false,"schema":{"format":"int32","type":"integer"}},{"description":"Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.","example":"keys(@)","in":"query","name":"jmespath","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"dates":[{"date":"2026-01-15","price":75.25,"returnDate":"2026-01-15"}],"degraded":true,"error":"example"},"schema":{"$ref":"#/components/schemas/SearchGoogleDatesResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/JmespathProjectionError"}]}}},"description":"Validation error"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"description":"Missing or invalid API key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenError"}}},"description":"API access requires an active subscription (the API key's subscription is inactive or expired).","headers":{"X-Billing-Verification":{"description":"Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).","schema":{"type":"string"}}}},"429":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/RateLimitError"}]}}},"description":"Rate limit exceeded.","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Maximum requests allowed in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix epoch milliseconds when the active rate-limit window resets.","schema":{"type":"string"}}}},"503":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/BillingVerificationError"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (1-60).","schema":{"type":"string"}},"X-Billing-Verification":{"description":"Billing-verification state that produced this response (matches the body `code`).","schema":{"type":"string"}},"X-RateLimit-Mode":{"description":"Present with value degraded when a fail-closed rate-limit dependency is unavailable.","schema":{"type":"string"}},"X-Validation-Mode":{"description":"Present with value degraded when user API-key validation is temporarily unavailable.","schema":{"type":"string"}}}},"default":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Gateway or handler error response."}},"summary":"SearchGoogleDates","tags":["AviationService"]}},"/api/aviation/v1/search-google-flights":{"get":{"description":"Search Google Flights itineraries by route and dates, with cabin, stops, airline and passenger filters, returning flight legs, duration and availability status.","operationId":"SearchGoogleFlights","parameters":[{"description":"Departure airport IATA code (e.g. \"JFK\").","example":"JFK","in":"query","name":"origin","required":false,"schema":{"type":"string"}},{"description":"Arrival airport IATA code (e.g. \"LHR\").","example":"LHR","in":"query","name":"destination","required":false,"schema":{"type":"string"}},{"description":"Departure date in YYYY-MM-DD format.","example":"2026-01-15","in":"query","name":"departure_date","required":false,"schema":{"type":"string"}},{"description":"Return date in YYYY-MM-DD format; omit for one-way.","example":"2026-01-15","in":"query","name":"return_date","required":false,"schema":{"type":"string"}},{"description":"Cabin class: ECONOMY, PREMIUM_ECONOMY, BUSINESS, or FIRST.","example":"ECONOMY","in":"query","name":"cabin_class","required":false,"schema":{"type":"string"}},{"description":"Stop filter: ANY, NON_STOP, ONE_STOP, or TWO_PLUS_STOPS.","example":"ANY","in":"query","name":"max_stops","required":false,"schema":{"type":"string"}},{"description":"Departure time window in HH-HH format (e.g. \"6-20\").","example":"6-20","in":"query","name":"departure_window","required":false,"schema":{"type":"string"}},{"description":"Airline IATA codes to filter by (e.g. [\"BA\", \"AA\"]).","example":["BA"],"explode":true,"in":"query","name":"airlines","required":false,"schema":{"items":{"type":"string"},"type":"array"},"style":"form"},{"description":"Sort order: CHEAPEST, DURATION, DEPARTURE_TIME, or ARRIVAL_TIME.","example":"CHEAPEST","in":"query","name":"sort_by","required":false,"schema":{"type":"string"}},{"description":"Number of adult passengers (1-9).","example":1,"in":"query","name":"passengers","required":false,"schema":{"format":"int32","type":"integer"}},{"description":"Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.","example":"keys(@)","in":"query","name":"jmespath","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"degraded":true,"error":"example","flights":[{"durationMinutes":42,"legs":[{"airlineCode":"example","arrivalAirport":"example","arrivalDatetime":"2026-01-15","departureAirport":"example","departureDatetime":"2026-01-15"}],"price":75.25,"stops":1}]},"schema":{"$ref":"#/components/schemas/SearchGoogleFlightsResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/JmespathProjectionError"}]}}},"description":"Validation error"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"description":"Missing or invalid API key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenError"}}},"description":"API access requires an active subscription (the API key's subscription is inactive or expired).","headers":{"X-Billing-Verification":{"description":"Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).","schema":{"type":"string"}}}},"429":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/RateLimitError"}]}}},"description":"Rate limit exceeded.","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Maximum requests allowed in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix epoch milliseconds when the active rate-limit window resets.","schema":{"type":"string"}}}},"503":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/BillingVerificationError"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (1-60).","schema":{"type":"string"}},"X-Billing-Verification":{"description":"Billing-verification state that produced this response (matches the body `code`).","schema":{"type":"string"}},"X-RateLimit-Mode":{"description":"Present with value degraded when a fail-closed rate-limit dependency is unavailable.","schema":{"type":"string"}},"X-Validation-Mode":{"description":"Present with value degraded when user API-key validation is temporarily unavailable.","schema":{"type":"string"}}}},"default":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Gateway or handler error response."}},"summary":"SearchGoogleFlights","tags":["AviationService"]}},"/api/aviation/v1/track-aircraft":{"get":{"description":"Track an aircraft by ICAO24 hex or callsign within map bounds, returning position observations, altitude, speed, source and update time for flight monitoring.","operationId":"TrackAircraft","parameters":[{"description":"ICAO 24-bit transponder address (hex, e.g., \"4b1805\").","example":"a835af","in":"query","name":"icao24","required":false,"schema":{"type":"string"}},{"description":"ATC callsign (e.g., \"THY7CX\").","example":"example","in":"query","name":"callsign","required":false,"schema":{"type":"string"}},{"description":"Optional bounding box south-west latitude.","example":40.7128,"in":"query","name":"sw_lat","required":false,"schema":{"format":"double","type":"number"}},{"description":"Optional bounding box south-west longitude.","example":-74.006,"in":"query","name":"sw_lon","required":false,"schema":{"format":"double","type":"number"}},{"description":"Optional bounding box north-east latitude.","example":40.7128,"in":"query","name":"ne_lat","required":false,"schema":{"format":"double","type":"number"}},{"description":"Optional bounding box north-east longitude.","example":-74.006,"in":"query","name":"ne_lon","required":false,"schema":{"format":"double","type":"number"}},{"description":"Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.","example":"keys(@)","in":"query","name":"jmespath","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"positions":[{"altitudeM":1.5,"callsign":"example","groundSpeedKts":1.5,"icao24":"a835af","lat":40.7128}],"source":"example","updatedAt":1717200000000},"schema":{"$ref":"#/components/schemas/TrackAircraftResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/JmespathProjectionError"}]}}},"description":"Validation error"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"description":"Missing or invalid API key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenError"}}},"description":"API access requires an active subscription (the API key's subscription is inactive or expired).","headers":{"X-Billing-Verification":{"description":"Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).","schema":{"type":"string"}}}},"429":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/RateLimitError"}]}}},"description":"Rate limit exceeded.","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Maximum requests allowed in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the active rate-limit window.","schema":{"type":"string"}},"X-RateLimit-Reset":{"description":"Unix epoch milliseconds when the active rate-limit window resets.","schema":{"type":"string"}}}},"503":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/BillingVerificationError"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (1-60).","schema":{"type":"string"}},"X-Billing-Verification":{"description":"Billing-verification state that produced this response (matches the body `code`).","schema":{"type":"string"}},"X-RateLimit-Mode":{"description":"Present with value degraded when a fail-closed rate-limit dependency is unavailable.","schema":{"type":"string"}},"X-Validation-Mode":{"description":"Present with value degraded when user API-key validation is temporarily unavailable.","schema":{"type":"string"}}}},"default":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/GatewayError"}]}}},"description":"Gateway or handler error response."}},"summary":"TrackAircraft","tags":["AviationService"]}}},"security":[{"WorldMonitorKey":[]},{"ApiKeyHeader":[]}],"servers":[{"url":"https://api.worldmonitor.app"}]}