openapi: 3.1.0 info: title: AviationService API version: 1.0.0 security: - WorldMonitorKey: [] - ApiKeyHeader: [] servers: - url: https://api.worldmonitor.app paths: /api/aviation/v1/list-airport-delays: get: tags: - AviationService summary: ListAirportDelays description: ListAirportDelays retrieves current airport delay alerts. operationId: ListAirportDelays parameters: - name: page_size in: query description: |- Maximum items per page (1-100). Accepted but currently ignored; no-op until this handler supports the parameter. required: false example: 25 schema: type: integer format: int32 - name: cursor in: query description: |- Cursor for next page. Accepted but currently ignored; no-op until this handler supports the parameter. required: false example: next-page-token schema: type: string - name: region in: query description: |- Optional region filter. Accepted but currently ignored; no-op until this handler supports the parameter. required: false example: AIRPORT_REGION_AMERICAS schema: type: string enum: - AIRPORT_REGION_AMERICAS - AIRPORT_REGION_EUROPE - AIRPORT_REGION_APAC - AIRPORT_REGION_MENA - AIRPORT_REGION_AFRICA - name: min_severity in: query description: |- Optional minimum severity filter. Accepted but currently ignored; no-op until this handler supports the parameter. required: false example: FLIGHT_DELAY_SEVERITY_NORMAL schema: type: string 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 - name: jmespath in: query 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. required: false example: keys(@) schema: type: string responses: '200': description: Successful response 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' '400': description: Validation error content: application/json: schema: oneOf: - $ref: '#/components/schemas/ValidationError' - $ref: '#/components/schemas/JmespathProjectionError' '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' '403': description: >- API access requires an active subscription (the API key's subscription is inactive or expired). content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' '429': description: Rate limit exceeded. headers: 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 Retry-After: description: Seconds to wait before retrying the request. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/RateLimitError' default: description: Gateway or handler error response. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/GatewayError' /api/aviation/v1/get-airport-ops-summary: get: tags: - AviationService summary: GetAirportOpsSummary description: >- GetAirportOpsSummary returns operational health metrics for watched airports. operationId: GetAirportOpsSummary parameters: - name: airports in: query description: IATA airport codes to query (e.g., ["IST", "ESB", "LHR"]). required: false style: form explode: true example: - JFK schema: type: array items: type: string - name: jmespath in: query 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. required: false example: keys(@) schema: type: string responses: '200': description: Successful response content: application/json: example: cacheHit: true summaries: - avgDelayMinutes: 1 cancellationRate: 75.25 closureStatus: true delayPct: 1.5 iata: JFK schema: $ref: '#/components/schemas/GetAirportOpsSummaryResponse' '400': description: Validation error content: application/json: schema: oneOf: - $ref: '#/components/schemas/ValidationError' - $ref: '#/components/schemas/JmespathProjectionError' '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' '403': description: >- API access requires an active subscription (the API key's subscription is inactive or expired). content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' '429': description: Rate limit exceeded. headers: 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 Retry-After: description: Seconds to wait before retrying the request. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/RateLimitError' default: description: Gateway or handler error response. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/GatewayError' /api/aviation/v1/list-airport-flights: get: tags: - AviationService summary: ListAirportFlights description: ListAirportFlights retrieves recent flights at a specific airport. operationId: ListAirportFlights parameters: - name: airport in: query description: IATA airport code (e.g., "IST"). required: true example: JFK schema: type: string - name: direction in: query description: Direction filter. required: false example: FLIGHT_DIRECTION_DEPARTURE schema: type: string enum: - FLIGHT_DIRECTION_DEPARTURE - FLIGHT_DIRECTION_ARRIVAL - FLIGHT_DIRECTION_BOTH - name: limit in: query description: Maximum number of flights to return (1-100). required: false example: 25 schema: type: integer format: int32 - name: jmespath in: query 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. required: false example: keys(@) schema: type: string responses: '200': description: Successful response 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' '400': description: Validation error content: application/json: schema: oneOf: - $ref: '#/components/schemas/ValidationError' - $ref: '#/components/schemas/JmespathProjectionError' '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' '403': description: >- API access requires an active subscription (the API key's subscription is inactive or expired). content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' '429': description: Rate limit exceeded. headers: 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 Retry-After: description: Seconds to wait before retrying the request. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/RateLimitError' default: description: Gateway or handler error response. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/GatewayError' /api/aviation/v1/get-carrier-ops: get: tags: - AviationService summary: GetCarrierOps description: GetCarrierOps returns delay and cancellation metrics grouped by carrier. operationId: GetCarrierOps parameters: - name: airports in: query description: IATA airport codes to aggregate carrier metrics from. required: false style: form explode: true example: - JFK schema: type: array items: type: string - name: min_flights in: query description: >- Minimum number of flights required to include a carrier (default: 1). required: false example: 1 schema: type: integer format: int32 - name: jmespath in: query 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. required: false example: keys(@) schema: type: string responses: '200': description: Successful response 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' '400': description: Validation error content: application/json: schema: oneOf: - $ref: '#/components/schemas/ValidationError' - $ref: '#/components/schemas/JmespathProjectionError' '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' '403': description: >- API access requires an active subscription (the API key's subscription is inactive or expired). content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' '429': description: Rate limit exceeded. headers: 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 Retry-After: description: Seconds to wait before retrying the request. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/RateLimitError' default: description: Gateway or handler error response. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/GatewayError' /api/aviation/v1/get-flight-status: get: tags: - AviationService summary: GetFlightStatus description: GetFlightStatus looks up the current status of a specific flight. operationId: GetFlightStatus parameters: - name: flight_number in: query description: IATA flight number (e.g., "TK1952"). required: true example: JFK schema: type: string - name: date in: query description: Departure date in ISO 8601 format (e.g., "2026-03-05"). required: true example: '2026-01-15' schema: type: string - name: origin in: query description: Optional origin airport IATA code to disambiguate. required: false example: JFK schema: type: string - name: jmespath in: query 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. required: false example: keys(@) schema: type: string responses: '200': description: Successful response content: application/json: example: cacheHit: true flights: - actualArrival: 1 actualDeparture: 1 aircraftIcao24: a835af aircraftType: all cancelled: true source: example schema: $ref: '#/components/schemas/GetFlightStatusResponse' '400': description: Validation error content: application/json: schema: oneOf: - $ref: '#/components/schemas/ValidationError' - $ref: '#/components/schemas/JmespathProjectionError' '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' '403': description: >- API access requires an active subscription (the API key's subscription is inactive or expired). content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' '429': description: Rate limit exceeded. headers: 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 Retry-After: description: Seconds to wait before retrying the request. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/RateLimitError' default: description: Gateway or handler error response. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/GatewayError' /api/aviation/v1/track-aircraft: get: tags: - AviationService summary: TrackAircraft description: >- TrackAircraft retrieves live position stream for a specific aircraft hex. operationId: TrackAircraft parameters: - name: icao24 in: query description: ICAO 24-bit transponder address (hex, e.g., "4b1805"). required: false example: a835af schema: type: string - name: callsign in: query description: ATC callsign (e.g., "THY7CX"). required: false example: example schema: type: string - name: sw_lat in: query description: Optional bounding box south-west latitude. required: false example: 40.7128 schema: type: number format: double - name: sw_lon in: query description: Optional bounding box south-west longitude. required: false example: -74.006 schema: type: number format: double - name: ne_lat in: query description: Optional bounding box north-east latitude. required: false example: 40.7128 schema: type: number format: double - name: ne_lon in: query description: Optional bounding box north-east longitude. required: false example: -74.006 schema: type: number format: double - name: jmespath in: query 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. required: false example: keys(@) schema: type: string responses: '200': description: Successful response 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' '400': description: Validation error content: application/json: schema: oneOf: - $ref: '#/components/schemas/ValidationError' - $ref: '#/components/schemas/JmespathProjectionError' '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' '403': description: >- API access requires an active subscription (the API key's subscription is inactive or expired). content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' '429': description: Rate limit exceeded. headers: 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 Retry-After: description: Seconds to wait before retrying the request. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/RateLimitError' default: description: Gateway or handler error response. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/GatewayError' /api/aviation/v1/get-youtube-live-stream-info: get: tags: - AviationService summary: GetYoutubeLiveStreamInfo description: >- GetYoutubeLiveStreamInfo retrieves information about a YouTube live stream (status, title, etc). operationId: GetYoutubeLiveStreamInfo parameters: - name: channel in: query description: YouTube channel handle or ID. required: false example: example schema: type: string - name: video_id in: query description: Specific video ID to check. required: false example: example-id schema: type: string - name: jmespath in: query 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. required: false example: keys(@) schema: type: string responses: '200': description: Successful response content: application/json: example: channelExists: true channelName: WorldMonitor Analyst error: example hlsUrl: https://example.com/worldmonitor isLive: true schema: $ref: '#/components/schemas/GetYoutubeLiveStreamInfoResponse' '400': description: Validation error content: application/json: schema: oneOf: - $ref: '#/components/schemas/ValidationError' - $ref: '#/components/schemas/JmespathProjectionError' '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' '403': description: >- API access requires an active subscription (the API key's subscription is inactive or expired). content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' '429': description: Rate limit exceeded. headers: 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 Retry-After: description: Seconds to wait before retrying the request. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/RateLimitError' default: description: Gateway or handler error response. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/GatewayError' /api/aviation/v1/search-flight-prices: get: tags: - AviationService summary: SearchFlightPrices description: SearchFlightPrices searches for flight price offers on a route. operationId: SearchFlightPrices parameters: - name: origin in: query description: Origin airport IATA code. required: true example: JFK schema: type: string - name: destination in: query description: Destination airport IATA code. required: true example: LHR schema: type: string - name: departure_date in: query description: Outbound departure date (ISO 8601). required: true example: '2026-01-15' schema: type: string - name: return_date in: query description: Return date (ISO 8601), empty for one-way. required: false example: '2026-01-15' schema: type: string - name: adults in: query description: Number of adult passengers (1-9). required: false example: 1 schema: type: integer format: int32 - name: cabin in: query description: Desired cabin class. required: false example: CABIN_CLASS_ECONOMY schema: type: string enum: - CABIN_CLASS_ECONOMY - CABIN_CLASS_PREMIUM_ECONOMY - CABIN_CLASS_BUSINESS - CABIN_CLASS_FIRST - name: nonstop_only in: query description: Whether to restrict to nonstop flights only. required: false example: true schema: type: boolean - name: max_results in: query description: Maximum number of quotes to return (1-50). required: false example: 1 schema: type: integer format: int32 - name: currency in: query description: ISO 4217 currency code for prices (e.g., "usd", "eur", "try"). required: false example: USD schema: type: string - name: market in: query description: Market/locale code (e.g., "us", "tr"). required: false example: example schema: type: string - name: jmespath in: query 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. required: false example: keys(@) schema: type: string responses: '200': description: Successful response content: application/json: example: degraded: true error: example isDemoMode: true isIndicative: true provider: worldmonitor schema: $ref: '#/components/schemas/SearchFlightPricesResponse' '400': description: Validation error content: application/json: schema: oneOf: - $ref: '#/components/schemas/ValidationError' - $ref: '#/components/schemas/JmespathProjectionError' '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' '403': description: >- API access requires an active subscription (the API key's subscription is inactive or expired). content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' '429': description: Rate limit exceeded. headers: 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 Retry-After: description: Seconds to wait before retrying the request. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/RateLimitError' default: description: Gateway or handler error response. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/GatewayError' /api/aviation/v1/list-aviation-news: get: tags: - AviationService summary: ListAviationNews description: ListAviationNews retrieves filtered aviation news articles. operationId: ListAviationNews parameters: - name: entities in: query description: Entities to filter by (airline names, airport codes, route strings). required: false style: form explode: true example: - example schema: type: array items: type: string - name: window_hours in: query description: Time window in hours to look back (1-168). required: false example: 1 schema: type: integer format: int32 - name: max_items in: query description: Maximum number of news items to return (1-50). required: false example: 1 schema: type: integer format: int32 - name: jmespath in: query 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. required: false example: keys(@) schema: type: string responses: '200': description: Successful response 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' '400': description: Validation error content: application/json: schema: oneOf: - $ref: '#/components/schemas/ValidationError' - $ref: '#/components/schemas/JmespathProjectionError' '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' '403': description: >- API access requires an active subscription (the API key's subscription is inactive or expired). content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' '429': description: Rate limit exceeded. headers: 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 Retry-After: description: Seconds to wait before retrying the request. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/RateLimitError' default: description: Gateway or handler error response. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/GatewayError' /api/aviation/v1/search-google-flights: get: tags: - AviationService summary: SearchGoogleFlights description: >- SearchGoogleFlights searches Google Flights for available itineraries on a specific date. operationId: SearchGoogleFlights parameters: - name: origin in: query description: Departure airport IATA code (e.g. "JFK"). required: false example: JFK schema: type: string - name: destination in: query description: Arrival airport IATA code (e.g. "LHR"). required: false example: LHR schema: type: string - name: departure_date in: query description: Departure date in YYYY-MM-DD format. required: false example: '2026-01-15' schema: type: string - name: return_date in: query description: Return date in YYYY-MM-DD format; omit for one-way. required: false example: '2026-01-15' schema: type: string - name: cabin_class in: query description: 'Cabin class: ECONOMY, PREMIUM_ECONOMY, BUSINESS, or FIRST.' required: false example: ECONOMY schema: type: string - name: max_stops in: query description: 'Stop filter: ANY, NON_STOP, ONE_STOP, or TWO_PLUS_STOPS.' required: false example: ANY schema: type: string - name: departure_window in: query description: Departure time window in HH-HH format (e.g. "6-20"). required: false example: 6-20 schema: type: string - name: airlines in: query description: Airline IATA codes to filter by (e.g. ["BA", "AA"]). required: false style: form explode: true example: - BA schema: type: array items: type: string - name: sort_by in: query description: 'Sort order: CHEAPEST, DURATION, DEPARTURE_TIME, or ARRIVAL_TIME.' required: false example: CHEAPEST schema: type: string - name: passengers in: query description: Number of adult passengers (1-9). required: false example: 1 schema: type: integer format: int32 - name: jmespath in: query 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. required: false example: keys(@) schema: type: string responses: '200': description: Successful response 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' '400': description: Validation error content: application/json: schema: oneOf: - $ref: '#/components/schemas/ValidationError' - $ref: '#/components/schemas/JmespathProjectionError' '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' '403': description: >- API access requires an active subscription (the API key's subscription is inactive or expired). content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' '429': description: Rate limit exceeded. headers: 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 Retry-After: description: Seconds to wait before retrying the request. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/RateLimitError' default: description: Gateway or handler error response. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/GatewayError' /api/aviation/v1/search-google-dates: get: tags: - AviationService summary: SearchGoogleDates description: >- SearchGoogleDates finds the cheapest travel dates across a flexible date range via Google Flights. operationId: SearchGoogleDates parameters: - name: origin in: query description: Departure airport IATA code (e.g. "JFK"). required: false example: JFK schema: type: string - name: destination in: query description: Arrival airport IATA code (e.g. "LHR"). required: false example: LHR schema: type: string - name: start_date in: query description: Start of date range in YYYY-MM-DD format. required: false example: '2026-01-15' schema: type: string - name: end_date in: query description: End of date range in YYYY-MM-DD format. required: false example: '2026-01-15' schema: type: string - name: trip_duration in: query description: Trip duration in days (required for round-trip searches). required: false example: 42 schema: type: integer format: int32 - name: is_round_trip in: query description: Whether to search for round-trip flights. required: false example: true schema: type: boolean - name: cabin_class in: query description: 'Cabin class: ECONOMY, PREMIUM_ECONOMY, BUSINESS, or FIRST.' required: false example: ECONOMY schema: type: string - name: max_stops in: query description: 'Stop filter: ANY, NON_STOP, ONE_STOP, or TWO_PLUS_STOPS.' required: false example: ANY schema: type: string - name: departure_window in: query description: Departure time window in HH-HH format (e.g. "6-20"). required: false example: 6-20 schema: type: string - name: airlines in: query description: Airline IATA codes to filter by (e.g. ["BA", "AA"]). required: false style: form explode: true example: - BA schema: type: array items: type: string - name: sort_by_price in: query description: Whether to sort results by price (lowest first). required: false example: true schema: type: boolean - name: passengers in: query description: Number of adult passengers (1-9). required: false example: 1 schema: type: integer format: int32 - name: jmespath in: query 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. required: false example: keys(@) schema: type: string responses: '200': description: Successful response 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' '400': description: Validation error content: application/json: schema: oneOf: - $ref: '#/components/schemas/ValidationError' - $ref: '#/components/schemas/JmespathProjectionError' '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' '403': description: >- API access requires an active subscription (the API key's subscription is inactive or expired). content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' '429': description: Rate limit exceeded. headers: 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 Retry-After: description: Seconds to wait before retrying the request. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/RateLimitError' default: description: Gateway or handler error response. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/GatewayError' components: securitySchemes: WorldMonitorKey: type: apiKey in: header name: X-WorldMonitor-Key description: User-issued WorldMonitor API key. ApiKeyHeader: type: apiKey in: header name: X-Api-Key description: Alias header for the WorldMonitor API key (X-WorldMonitor-Key). schemas: 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 UnauthorizedError: type: object properties: error: type: string description: Human-readable error message. required: - error description: >- Returned when the API key is missing, malformed, or lacks current API access. Error: type: object properties: message: type: string description: Error message (e.g., 'user not found', 'database connection failed') description: >- Error is returned when a handler encounters an error. It contains a simple error message that the developer can customize. InvalidRequestBodyError: type: object description: Returned when a JSON POST request body is empty or malformed. properties: message: type: string description: Invalid request body required: - message GatewayError: type: object description: >- Returned by gateway infrastructure errors before an RPC handler runs, such as origin, routing, method, authentication, or quota checks. properties: error: oneOf: - type: string - type: object additionalProperties: true description: Gateway error reason or structured gateway failure details. required: - error RateLimitError: type: object description: Returned when a gateway or handler rate limit rejects the request. properties: error: type: string description: Human-readable rate-limit failure reason. required: - error ForbiddenError: type: object properties: error: type: string description: Human-readable entitlement failure reason. requiredTier: type: integer format: int32 description: Minimum entitlement tier required for this endpoint. currentTier: type: integer format: int32 description: Caller entitlement tier when known. planKey: type: string description: Caller plan key when known. required: - error 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. FieldViolation: type: object properties: field: type: string 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') description: type: string description: >- Human-readable description of the validation violation (e.g., 'must be a valid email address', 'required field missing') required: - field - description description: FieldViolation describes a single validation error for a specific field. ValidationError: type: object properties: violations: type: array items: $ref: '#/components/schemas/FieldViolation' description: List of validation violations required: - violations description: >- ValidationError is returned when request validation fails. It contains a list of field violations describing what went wrong. ListAirportDelaysRequest: type: object properties: pageSize: type: integer format: int32 description: |- Maximum items per page (1-100). Accepted but currently ignored; no-op until this handler supports the parameter. cursor: type: string description: |- Cursor for next page. Accepted but currently ignored; no-op until this handler supports the parameter. region: type: string enum: - AIRPORT_REGION_UNSPECIFIED - AIRPORT_REGION_AMERICAS - AIRPORT_REGION_EUROPE - AIRPORT_REGION_APAC - AIRPORT_REGION_MENA - AIRPORT_REGION_AFRICA description: AirportRegion represents the geographic region of an airport. minSeverity: type: string 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 description: >- FlightDelaySeverity represents the severity of flight delays at an airport. Maps to TS union: 'normal' | 'minor' | 'moderate' | 'major' | 'severe' | 'unknown'. description: >- ListAirportDelaysRequest specifies filters for retrieving airport delay alerts. ListAirportDelaysResponse: type: object properties: alerts: type: array items: $ref: '#/components/schemas/AirportDelayAlert' pagination: $ref: '#/components/schemas/PaginationResponse' description: >- ListAirportDelaysResponse contains airport delay alerts matching the request. AirportDelayAlert: type: object properties: id: type: string minLength: 1 description: Unique alert identifier. iata: type: string description: IATA airport code (e.g., "JFK"). icao: type: string description: ICAO airport code (e.g., "KJFK"). name: type: string description: Airport name. city: type: string description: City where the airport is located. country: type: string description: Country code (ISO 3166-1 alpha-2). location: $ref: '#/components/schemas/GeoCoordinates' region: type: string enum: - AIRPORT_REGION_UNSPECIFIED - AIRPORT_REGION_AMERICAS - AIRPORT_REGION_EUROPE - AIRPORT_REGION_APAC - AIRPORT_REGION_MENA - AIRPORT_REGION_AFRICA description: AirportRegion represents the geographic region of an airport. delayType: type: string 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 description: FlightDelayType represents the type of flight delay. severity: type: string 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 description: >- FlightDelaySeverity represents the severity of flight delays at an airport. Maps to TS union: 'normal' | 'minor' | 'moderate' | 'major' | 'severe' | 'unknown'. avgDelayMinutes: type: integer format: int32 description: Average delay in minutes. delayedFlightsPct: type: number format: double description: Percentage of delayed flights. cancelledFlights: type: integer format: int32 description: Number of cancelled flights. totalFlights: type: integer format: int32 description: Total flights scheduled. reason: type: string description: Human-readable reason for delays. source: type: string 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 description: FlightDelaySource represents the source of delay data. updatedAt: type: integer format: int64 description: >- Last data update time, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript required: - id description: |- AirportDelayAlert represents a flight delay advisory at an airport. Sourced from FAA and Eurocontrol. GeoCoordinates: type: object properties: latitude: type: number maximum: 90 minimum: -90 format: double description: Latitude in decimal degrees (-90 to 90). longitude: type: number maximum: 180 minimum: -180 format: double description: Longitude in decimal degrees (-180 to 180). description: GeoCoordinates represents a geographic location using WGS84 coordinates. PaginationResponse: type: object properties: nextCursor: type: string description: >- Cursor for fetching the next page. Empty string indicates no more pages. totalCount: type: integer format: int32 description: >- Total count of items matching the query, if known. Zero if the total is unknown. description: >- PaginationResponse contains pagination metadata returned alongside list results. GetAirportOpsSummaryRequest: type: object properties: airports: type: array items: type: string maxItems: 20 minItems: 1 description: IATA airport codes to query (e.g., ["IST", "ESB", "LHR"]). maxItems: 20 minItems: 1 description: GetAirportOpsSummaryRequest specifies which airports to summarize. GetAirportOpsSummaryResponse: type: object properties: summaries: type: array items: $ref: '#/components/schemas/AirportOpsSummary' cacheHit: type: boolean description: Whether the response was served from cache. description: >- GetAirportOpsSummaryResponse contains operational summaries for requested airports. AirportOpsSummary: type: object properties: iata: type: string description: IATA airport code. icao: type: string description: ICAO airport code. name: type: string description: Airport name. timezone: type: string description: IANA timezone (e.g., "Europe/Istanbul"). delayPct: type: number format: double description: Percentage of flights currently delayed (0-100). avgDelayMinutes: type: integer format: int32 description: Average delay in minutes across delayed flights. cancellationRate: type: number format: double description: Cancellation rate as a percentage (0-100). totalFlights: type: integer format: int32 description: Total flights in the observation window. closureStatus: type: boolean description: Whether the airport is currently closed. notamFlags: type: array items: type: string description: >- Active NOTAM summary flags (e.g., "RWY 06/24 CLSD", "LOW VIS OPS"). severity: type: string 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 description: >- FlightDelaySeverity represents the severity of flight delays at an airport. Maps to TS union: 'normal' | 'minor' | 'moderate' | 'major' | 'severe' | 'unknown'. topDelayReasons: type: array items: type: string description: Top reasons for delays. source: type: string description: Data source identifier. updatedAt: type: integer format: int64 description: >- Last update time as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript description: >- AirportOpsSummary contains operational health metrics for a single airport. ListAirportFlightsRequest: type: object properties: airport: type: string maxLength: 4 minLength: 3 description: IATA airport code (e.g., "IST"). direction: type: string enum: - FLIGHT_DIRECTION_UNSPECIFIED - FLIGHT_DIRECTION_DEPARTURE - FLIGHT_DIRECTION_ARRIVAL - FLIGHT_DIRECTION_BOTH description: >- FlightDirection specifies whether to retrieve departures, arrivals, or both. limit: type: integer maximum: 100 minimum: 1 format: int32 description: Maximum number of flights to return (1-100). required: - airport description: >- ListAirportFlightsRequest specifies parameters for retrieving recent flights at an airport. ListAirportFlightsResponse: type: object properties: flights: type: array items: $ref: '#/components/schemas/FlightInstance' totalAvailable: type: integer format: int32 description: Total number of flights available from the provider. source: type: string description: Data source identifier. updatedAt: type: integer format: int64 description: >- Last update time as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript description: ListAirportFlightsResponse contains recent flights at an airport. FlightInstance: type: object properties: flightNumber: type: string description: IATA flight number (e.g., "TK1952"). date: type: string description: Departure date in ISO 8601 format (e.g., "2026-03-05"). operatingCarrier: $ref: '#/components/schemas/Carrier' origin: $ref: '#/components/schemas/AirportRef' destination: $ref: '#/components/schemas/AirportRef' scheduledDeparture: type: integer format: int64 description: >- Scheduled departure time as Unix epoch milliseconds (UTC).. Warning: Values > 2^53 may lose precision in JavaScript estimatedDeparture: type: integer format: int64 description: >- Estimated departure time as Unix epoch milliseconds (UTC).. Warning: Values > 2^53 may lose precision in JavaScript actualDeparture: type: integer format: int64 description: >- Actual departure time as Unix epoch milliseconds (UTC).. Warning: Values > 2^53 may lose precision in JavaScript scheduledArrival: type: integer format: int64 description: >- Scheduled arrival time as Unix epoch milliseconds (UTC).. Warning: Values > 2^53 may lose precision in JavaScript estimatedArrival: type: integer format: int64 description: >- Estimated arrival time as Unix epoch milliseconds (UTC).. Warning: Values > 2^53 may lose precision in JavaScript actualArrival: type: integer format: int64 description: >- Actual arrival time as Unix epoch milliseconds (UTC).. Warning: Values > 2^53 may lose precision in JavaScript status: type: string 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 description: >- FlightInstanceStatus represents the operational status of a flight occurrence. delayMinutes: type: integer format: int32 description: Delay in minutes (0 if on time, negative if early). cancelled: type: boolean description: Whether the flight is cancelled. diverted: type: boolean description: Whether the flight has been diverted. gate: type: string description: Departure gate (if available). terminal: type: string description: Departure terminal (if available). aircraftIcao24: type: string description: >- ICAO 24-bit transponder address of the aircraft (hex, e.g., "4b1805"). aircraftType: type: string description: Aircraft type designator (e.g., "B738"). codeshareFlightNumbers: type: array items: type: string description: Codeshare flight numbers marketed under this operating flight. source: type: string description: Data source provider name. updatedAt: type: integer format: int64 description: >- Last update time as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript description: >- FlightInstance represents a specific occurrence of a flight on a given date. Carrier: type: object properties: iataCode: type: string description: IATA two-letter airline code (e.g., "TK"). icaoCode: type: string description: ICAO three-letter airline code (e.g., "THY"). name: type: string description: Full airline name (e.g., "Turkish Airlines"). description: Carrier represents an airline or aircraft operator. AirportRef: type: object properties: iata: type: string description: IATA airport code (e.g., "IST"). icao: type: string description: ICAO airport code (e.g., "LTFM"). name: type: string description: Airport name (e.g., "Istanbul Airport"). timezone: type: string description: IANA timezone (e.g., "Europe/Istanbul"). description: AirportRef is a lightweight reference to an airport. GetCarrierOpsRequest: type: object properties: airports: type: array items: type: string maxItems: 20 minItems: 1 description: IATA airport codes to aggregate carrier metrics from. maxItems: 20 minItems: 1 minFlights: type: integer minimum: 0 format: int32 description: >- Minimum number of flights required to include a carrier (default: 1). description: >- GetCarrierOpsRequest specifies parameters for carrier operations metrics. GetCarrierOpsResponse: type: object properties: carriers: type: array items: $ref: '#/components/schemas/CarrierOpsSummary' source: type: string description: Data source identifier. updatedAt: type: integer format: int64 description: >- Last update time as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript description: GetCarrierOpsResponse contains carrier operations metrics. CarrierOpsSummary: type: object properties: carrier: $ref: '#/components/schemas/Carrier' airport: type: string description: Airport IATA code this summary applies to. totalFlights: type: integer format: int32 description: Total flights observed. delayedCount: type: integer format: int32 description: Number of delayed flights. cancelledCount: type: integer format: int32 description: Number of cancelled flights. avgDelayMinutes: type: integer format: int32 description: Average delay in minutes across delayed flights. delayPct: type: number format: double description: Delay percentage (0-100). cancellationRate: type: number format: double description: Cancellation rate (0-100). updatedAt: type: integer format: int64 description: >- Last update time as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript description: >- CarrierOpsSummary contains delay and cancellation metrics for a carrier at an airport. GetFlightStatusRequest: type: object properties: flightNumber: type: string maxLength: 10 minLength: 3 description: IATA flight number (e.g., "TK1952"). date: type: string description: Departure date in ISO 8601 format (e.g., "2026-03-05"). origin: type: string description: Optional origin airport IATA code to disambiguate. required: - flightNumber - date description: GetFlightStatusRequest specifies a flight to look up. GetFlightStatusResponse: type: object properties: flights: type: array items: $ref: '#/components/schemas/FlightInstance' source: type: string description: Data source identifier. cacheHit: type: boolean description: Whether the response was served from cache. description: GetFlightStatusResponse contains flight status results. TrackAircraftRequest: type: object properties: icao24: type: string description: ICAO 24-bit transponder address (hex, e.g., "4b1805"). callsign: type: string description: ATC callsign (e.g., "THY7CX"). swLat: type: number format: double description: Optional bounding box south-west latitude. swLon: type: number format: double description: Optional bounding box south-west longitude. neLat: type: number format: double description: Optional bounding box north-east latitude. neLon: type: number format: double description: Optional bounding box north-east longitude. description: TrackAircraftRequest specifies an aircraft to track. TrackAircraftResponse: type: object properties: positions: type: array items: $ref: '#/components/schemas/PositionSample' source: type: string description: Data source identifier. updatedAt: type: integer format: int64 description: >- Last update time as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript description: TrackAircraftResponse contains aircraft position observations. PositionSample: type: object properties: icao24: type: string description: ICAO 24-bit transponder address (hex, e.g., "4b1805"). callsign: type: string description: ATC callsign (e.g., "THY7CX"). lat: type: number format: double description: Latitude in decimal degrees. lon: type: number format: double description: Longitude in decimal degrees. altitudeM: type: number format: double description: Barometric altitude in metres. groundSpeedKts: type: number format: double description: Ground speed in knots. trackDeg: type: number format: double description: True track over ground in degrees (0 = North, clockwise). verticalRate: type: number format: double description: Vertical rate in metres per second (positive = climbing). onGround: type: boolean description: Whether the aircraft is on the ground. source: type: string enum: - POSITION_SOURCE_UNSPECIFIED - POSITION_SOURCE_OPENSKY - POSITION_SOURCE_WINGBITS - POSITION_SOURCE_SIMULATED description: PositionSource identifies the provider of aircraft position data. observedAt: type: integer format: int64 description: >- Observation time as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript description: PositionSample represents a single aircraft position observation. GetYoutubeLiveStreamInfoRequest: type: object properties: channel: type: string description: YouTube channel handle or ID. videoId: type: string description: Specific video ID to check. description: GetYoutubeLiveStreamInfoRequest parameters for detecting live status. GetYoutubeLiveStreamInfoResponse: type: object properties: videoId: type: string description: Video ID of the live stream (if found). isLive: type: boolean description: Whether the stream is currently live. channelExists: type: boolean description: Whether the channel exists. channelName: type: string description: Human-readable channel name. hlsUrl: type: string description: HLS manifest URL (if available). title: type: string description: Stream title. error: type: string description: Optional error message. description: GetYoutubeLiveStreamInfoResponse containing detection results. SearchFlightPricesRequest: type: object properties: origin: type: string maxLength: 4 minLength: 3 description: Origin airport IATA code. destination: type: string maxLength: 4 minLength: 3 description: Destination airport IATA code. departureDate: type: string description: Outbound departure date (ISO 8601). returnDate: type: string description: Return date (ISO 8601), empty for one-way. adults: type: integer maximum: 9 minimum: 1 format: int32 description: Number of adult passengers (1-9). cabin: type: string enum: - CABIN_CLASS_UNSPECIFIED - CABIN_CLASS_ECONOMY - CABIN_CLASS_PREMIUM_ECONOMY - CABIN_CLASS_BUSINESS - CABIN_CLASS_FIRST description: CabinClass represents the travel class for a flight ticket. nonstopOnly: type: boolean description: Whether to restrict to nonstop flights only. maxResults: type: integer maximum: 50 minimum: 1 format: int32 description: Maximum number of quotes to return (1-50). currency: type: string description: ISO 4217 currency code for prices (e.g., "usd", "eur", "try"). market: type: string description: Market/locale code (e.g., "us", "tr"). required: - origin - destination - departureDate description: >- SearchFlightPricesRequest specifies parameters for a flight price search. SearchFlightPricesResponse: type: object properties: quotes: type: array items: $ref: '#/components/schemas/PriceQuote' provider: type: string description: |- Provider name: "travelpayouts_data", "demo", or "none" when no live provider is configured. isDemoMode: type: boolean description: |- Whether results are from demo/simulated mode. Requires explicit AVIATION_DEMO_PRICES=1 opt-in on the server. Never true in default self-host / production runs. See issue #3756. updatedAt: type: integer format: int64 description: >- Last update time as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript isIndicative: type: boolean description: Whether returned prices are indicative (subject to change). degraded: type: boolean description: |- True when the live provider could not satisfy the request — missing credentials, upstream failure, or zero results. Mirrors the searchGoogleFlights pattern so clients can render distinct messages for each error class. error: type: string description: |- Discriminator for the degraded state: "" (ok), "missing_credentials" (TRAVELPAYOUTS_API_TOKEN unset), "upstream_error" (provider call threw), "no_results" (provider returned empty for this route). description: SearchFlightPricesResponse contains flight price offers. PriceQuote: type: object properties: id: type: string description: Unique quote identifier. origin: type: string description: Origin airport IATA code. destination: type: string description: Destination airport IATA code. departureDate: type: string description: Outbound departure date (ISO 8601). returnDate: type: string description: Return date (ISO 8601), empty for one-way. carrier: $ref: '#/components/schemas/Carrier' priceAmount: type: number format: double description: Total price amount. currency: type: string description: ISO 4217 currency code (e.g., "EUR", "USD", "TRY"). cabin: type: string enum: - CABIN_CLASS_UNSPECIFIED - CABIN_CLASS_ECONOMY - CABIN_CLASS_PREMIUM_ECONOMY - CABIN_CLASS_BUSINESS - CABIN_CLASS_FIRST description: CabinClass represents the travel class for a flight ticket. stops: type: integer format: int32 description: Number of stops (0 = nonstop). durationMinutes: type: integer format: int32 description: Total travel duration in minutes. bookingUrl: type: string description: Booking URL or deep-link (if available). provider: type: string description: Provider name (e.g., "amadeus", "demo"). isIndicative: type: boolean description: Whether the price is indicative rather than bookable. observedAt: type: integer format: int64 description: >- Time when this quote was observed, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript checkoutRef: type: string description: Reference used during the checkout process (for follow-up actions). expiresAt: type: integer format: int64 description: >- Time when this quote expires, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript description: PriceQuote represents a single flight price offer from a provider. ListAviationNewsRequest: type: object properties: entities: type: array items: type: string maxItems: 10 minItems: 1 description: >- Entities to filter by (airline names, airport codes, route strings). maxItems: 10 minItems: 1 windowHours: type: integer maximum: 168 minimum: 1 format: int32 description: Time window in hours to look back (1-168). maxItems: type: integer maximum: 50 minimum: 1 format: int32 description: Maximum number of news items to return (1-50). description: ListAviationNewsRequest specifies filters for aviation news retrieval. ListAviationNewsResponse: type: object properties: items: type: array items: $ref: '#/components/schemas/AviationNewsItem' source: type: string description: Data source identifier. updatedAt: type: integer format: int64 description: >- Last update time as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript description: ListAviationNewsResponse contains filtered aviation news items. AviationNewsItem: type: object properties: id: type: string description: Unique item identifier (hash of URL). title: type: string description: Article title. url: type: string description: Article URL. sourceName: type: string description: Name of the news source (e.g., "FlightGlobal"). publishedAt: type: integer format: int64 description: >- Publication time as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript snippet: type: string description: Short text snippet or description. matchedEntities: type: array items: type: string description: Entities matched from the query (airport codes, airline names). imageUrl: type: string description: Article image URL (if available). description: >- AviationNewsItem represents a single aviation news article or press release. SearchGoogleFlightsRequest: type: object properties: origin: type: string description: Departure airport IATA code (e.g. "JFK"). destination: type: string description: Arrival airport IATA code (e.g. "LHR"). departureDate: type: string description: Departure date in YYYY-MM-DD format. returnDate: type: string description: Return date in YYYY-MM-DD format; omit for one-way. cabinClass: type: string description: 'Cabin class: ECONOMY, PREMIUM_ECONOMY, BUSINESS, or FIRST.' maxStops: type: string description: 'Stop filter: ANY, NON_STOP, ONE_STOP, or TWO_PLUS_STOPS.' departureWindow: type: string description: Departure time window in HH-HH format (e.g. "6-20"). airlines: type: array items: type: string description: Airline IATA codes to filter by (e.g. ["BA", "AA"]). sortBy: type: string description: 'Sort order: CHEAPEST, DURATION, DEPARTURE_TIME, or ARRIVAL_TIME.' passengers: type: integer format: int32 description: Number of adult passengers (1-9). description: >- SearchGoogleFlightsRequest specifies parameters for a Google Flights search. SearchGoogleFlightsResponse: type: object properties: flights: type: array items: $ref: '#/components/schemas/GoogleFlightResult' degraded: type: boolean error: type: string description: SearchGoogleFlightsResponse contains flight results from Google Flights. GoogleFlightResult: type: object properties: legs: type: array items: $ref: '#/components/schemas/GoogleFlightLeg' price: type: number format: double durationMinutes: type: integer format: int32 stops: type: integer format: int32 description: GoogleFlightResult represents a complete itinerary (one or more legs). GoogleFlightLeg: type: object properties: airlineCode: type: string flightNumber: type: string departureAirport: type: string arrivalAirport: type: string departureDatetime: type: string description: ISO 8601 local datetime, e.g. "2025-06-01T08:45". arrivalDatetime: type: string durationMinutes: type: integer format: int32 description: >- GoogleFlightLeg represents a single flight segment (one plane, one takeoff and landing). SearchGoogleDatesRequest: type: object properties: origin: type: string description: Departure airport IATA code (e.g. "JFK"). destination: type: string description: Arrival airport IATA code (e.g. "LHR"). startDate: type: string description: Start of date range in YYYY-MM-DD format. endDate: type: string description: End of date range in YYYY-MM-DD format. tripDuration: type: integer format: int32 description: Trip duration in days (required for round-trip searches). isRoundTrip: type: boolean description: Whether to search for round-trip flights. cabinClass: type: string description: 'Cabin class: ECONOMY, PREMIUM_ECONOMY, BUSINESS, or FIRST.' maxStops: type: string description: 'Stop filter: ANY, NON_STOP, ONE_STOP, or TWO_PLUS_STOPS.' departureWindow: type: string description: Departure time window in HH-HH format (e.g. "6-20"). airlines: type: array items: type: string description: Airline IATA codes to filter by (e.g. ["BA", "AA"]). sortByPrice: type: boolean description: Whether to sort results by price (lowest first). passengers: type: integer format: int32 description: Number of adult passengers (1-9). description: >- SearchGoogleDatesRequest specifies parameters for a Google Flights date-range price search. SearchGoogleDatesResponse: type: object properties: dates: type: array items: $ref: '#/components/schemas/DatePriceEntry' degraded: type: boolean error: type: string description: >- SearchGoogleDatesResponse contains cheapest-date results from Google Flights. DatePriceEntry: type: object properties: date: type: string description: Departure date in YYYY-MM-DD format. returnDate: type: string description: Return date in YYYY-MM-DD format; empty for one-way results. price: type: number format: double description: >- DatePriceEntry pairs a departure date (and optional return date) with its cheapest price.