docs/api/AviationService.openapi.yaml
Rama main · réplica de lectura del repositorio original.
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-aircraft-emergencies:
get:
tags:
- AviationService
summary: ListAircraftEmergencies
description: |-
ListAircraftEmergencies returns reported 7500, 7600 and 7700 signals independently of military classification.
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:
- 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:
"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'
"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).
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
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'
"503":
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-Validation-Mode:
description: Present with value degraded when user API-key validation is temporarily unavailable.
schema:
type: string
X-RateLimit-Mode:
description: Present with value degraded when a fail-closed rate-limit dependency is unavailable.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BillingVerificationError'
- $ref: '#/components/schemas/GatewayError'
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-delays:
get:
tags:
- AviationService
summary: ListAirportDelays
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:
- 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).
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
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'
"503":
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-Validation-Mode:
description: Present with value degraded when user API-key validation is temporarily unavailable.
schema:
type: string
X-RateLimit-Mode:
description: Present with value degraded when a fail-closed rate-limit dependency is unavailable.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BillingVerificationError'
- $ref: '#/components/schemas/GatewayError'
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 watched-airport operational health, including delay percentages, average delay minutes, cancellation rates and closure status.
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).
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
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'
"503":
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-Validation-Mode:
description: Present with value degraded when user API-key validation is temporarily unavailable.
schema:
type: string
X-RateLimit-Mode:
description: Present with value degraded when a fail-closed rate-limit dependency is unavailable.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BillingVerificationError'
- $ref: '#/components/schemas/GatewayError'
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 returns recent arrivals and departures with direction and limit filters, status and carrier. PRO-gated. Requires an active Pro subscription.
operationId: ListAirportFlights
security:
- WorldMonitorKey: []
- ApiKeyHeader: []
- BearerAuth: []
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: 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
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'
"503":
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-Validation-Mode:
description: Present with value degraded when user API-key validation is temporarily unavailable.
schema:
type: string
X-RateLimit-Mode:
description: Present with value degraded when a fail-closed rate-limit dependency is unavailable.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BillingVerificationError'
- $ref: '#/components/schemas/GatewayError'
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. PRO-gated. Requires an active Pro subscription.
operationId: GetCarrierOps
security:
- WorldMonitorKey: []
- ApiKeyHeader: []
- BearerAuth: []
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: 3).
The generated GET decoder emits 0 when the query param is absent, and 0
means "use the default" in the handler — an explicit 0 is not a usable
filter (every group has >= 1 flight).
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: 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
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'
"503":
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-Validation-Mode:
description: Present with value degraded when user API-key validation is temporarily unavailable.
schema:
type: string
X-RateLimit-Mode:
description: Present with value degraded when a fail-closed rate-limit dependency is unavailable.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BillingVerificationError'
- $ref: '#/components/schemas/GatewayError'
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. PRO-gated. Requires an active Pro subscription.
operationId: GetFlightStatus
security:
- WorldMonitorKey: []
- ApiKeyHeader: []
- BearerAuth: []
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: 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
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'
"503":
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-Validation-Mode:
description: Present with value degraded when user API-key validation is temporarily unavailable.
schema:
type: string
X-RateLimit-Mode:
description: Present with value degraded when a fail-closed rate-limit dependency is unavailable.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BillingVerificationError'
- $ref: '#/components/schemas/GatewayError'
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: 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:
- 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).
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
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'
"503":
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-Validation-Mode:
description: Present with value degraded when user API-key validation is temporarily unavailable.
schema:
type: string
X-RateLimit-Mode:
description: Present with value degraded when a fail-closed rate-limit dependency is unavailable.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BillingVerificationError'
- $ref: '#/components/schemas/GatewayError'
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 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:
- name: channel
deprecated: true
in: query
description: 'Deprecated: YouTube channel handle or ID. Channel live detection is retired; a channel-only query returns error "channel_live_detection_retired".'
required: false
example: "example"
schema:
type: string
- name: video_id
in: query
description: YouTube video ID to name.
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": "DW News"
"error": ""
"hlsUrl": ""
"isLive": false
"title": "DW News livestream"
"videoId": "LuKwFajn37U"
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).
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
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'
"503":
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-Validation-Mode:
description: Present with value degraded when user API-key validation is temporarily unavailable.
schema:
type: string
X-RateLimit-Mode:
description: Present with value degraded when a fail-closed rate-limit dependency is unavailable.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BillingVerificationError'
- $ref: '#/components/schemas/GatewayError'
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: 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
security:
- WorldMonitorKey: []
- ApiKeyHeader: []
- BearerAuth: []
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).
Accepted but currently ignored; quotes are per-person and the count does not filter.
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: 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
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'
"503":
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-Validation-Mode:
description: Present with value degraded when user API-key validation is temporarily unavailable.
schema:
type: string
X-RateLimit-Mode:
description: Present with value degraded when a fail-closed rate-limit dependency is unavailable.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BillingVerificationError'
- $ref: '#/components/schemas/GatewayError'
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 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:
- 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).
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
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'
"503":
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-Validation-Mode:
description: Present with value degraded when user API-key validation is temporarily unavailable.
schema:
type: string
X-RateLimit-Mode:
description: Present with value degraded when a fail-closed rate-limit dependency is unavailable.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BillingVerificationError'
- $ref: '#/components/schemas/GatewayError'
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: 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:
- 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).
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
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'
"503":
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-Validation-Mode:
description: Present with value degraded when user API-key validation is temporarily unavailable.
schema:
type: string
X-RateLimit-Mode:
description: Present with value degraded when a fail-closed rate-limit dependency is unavailable.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BillingVerificationError'
- $ref: '#/components/schemas/GatewayError'
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 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:
- 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).
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
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'
"503":
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-Validation-Mode:
description: Present with value degraded when user API-key validation is temporarily unavailable.
schema:
type: string
X-RateLimit-Mode:
description: Present with value degraded when a fail-closed rate-limit dependency is unavailable.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BillingVerificationError'
- $ref: '#/components/schemas/GatewayError'
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).
BearerAuth:
type: http
scheme: bearer
description: 'Bearer token: a Clerk-issued JWT for browser session flows, passed as Authorization: Bearer <token>.'
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.
BillingVerificationError:
type: object
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:
error:
type: string
description: Human-readable billing-verification failure reason.
code:
type: string
enum:
- renewal_verification_pending
- renewal_verification_failed
- entitlement_verification_unavailable
description: Machine-readable billing-verification state, mirrored in the X-Billing-Verification response header.
requiredTier:
type: integer
format: int32
description: Minimum entitlement tier required for this endpoint, when the denial came from a tier gate.
required:
- error
- code
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.
code:
type: string
enum:
- subscription_lapsed
description: Machine-readable denial code, present when the 403 is a billing-provider-confirmed subscription lapse (mirrored in the X-Billing-Verification response header).
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.
ListAircraftEmergenciesRequest:
type: object
description: ListAircraftEmergenciesRequest has no filters. Coverage is provider reception.
ListAircraftEmergenciesResponse:
type: object
properties:
observations:
type: array
items:
$ref: '#/components/schemas/EmergencyObservation'
feeds:
type: array
items:
$ref: '#/components/schemas/EmergencyFeed'
description: ListAircraftEmergenciesResponse preserves observations and per-query availability.
EmergencyObservation:
type: object
properties:
address:
type: string
description: Provider address, including a non-ICAO prefix when present.
squawk:
type: string
description: Exact four-character transponder code.
source:
type: string
description: Observation provider.
observedAt:
type: integer
format: int64
description: 'Last message time in epoch milliseconds, not squawk selection time. Zero means unknown.. Warning: Values > 2^53 may lose precision in JavaScript'
position:
$ref: '#/components/schemas/EmergencyPosition'
callsign:
type: string
description: Reported callsign, empty when unknown.
registration:
type: string
description: Provider registration, empty when unknown.
aircraftType:
type: string
description: Provider type code, empty when unknown.
description:
type: string
description: Provider aircraft description, empty when unknown.
militaryFlag:
type: string
description: Military database bit, set, not_set, or unknown. This is not admission criteria.
altitudeFt:
type: number
format: double
description: Barometric altitude in feet, absent when unknown or reported as ground.
groundSpeedKts:
type: number
format: double
description: Ground speed in knots, absent when unknown.
description: EmergencyObservation is a reported Mode A code, not a confirmed incident.
EmergencyPosition:
type: object
properties:
lat:
type: number
format: double
description: Latitude in degrees.
lon:
type: number
format: double
description: Longitude in degrees.
observedAt:
type: integer
format: int64
description: 'Provider position time in epoch milliseconds. Zero means unknown.. Warning: Values > 2^53 may lose precision in JavaScript'
description: EmergencyPosition keeps the position clock separate from last contact.
EmergencyFeed:
type: object
properties:
source:
type: string
description: Provider name.
squawk:
type: string
description: Requested squawk.
status:
type: string
description: available, unavailable, or stale.
fetchedAt:
type: integer
format: int64
description: 'Retrieval time in epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
message:
type: string
description: Safe status explanation.
description: EmergencyFeed records success and failure separately for each exact code query.
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: 3).
The generated GET decoder emits 0 when the query param is absent, and 0
means "use the default" in the handler — an explicit 0 is not a usable
filter (every group has >= 1 flight).
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_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:
deprecated: true
type: string
description: 'Deprecated: YouTube channel handle or ID. Channel live detection is retired; a channel-only query returns error "channel_live_detection_retired".'
videoId:
type: string
description: YouTube video ID to name.
description: GetYoutubeLiveStreamInfoRequest names the YouTube video to look up.
GetYoutubeLiveStreamInfoResponse:
type: object
properties:
videoId:
type: string
description: Video ID that was looked up.
isLive:
deprecated: true
type: boolean
description: 'Always false: oEmbed does not report whether a video is live.'
channelExists:
deprecated: true
type: boolean
description: 'Deprecated: true only when the oEmbed lookup succeeded, so it now carries exactly error == "".'
channelName:
type: string
description: Human-readable channel name.
hlsUrl:
deprecated: true
type: string
description: 'Always empty: YouTube manifest URLs are no longer returned.'
title:
type: string
description: Video title.
error:
type: string
description: '"channel_live_detection_retired" for a channel-only query, or why the video lookup failed.'
description: GetYoutubeLiveStreamInfoResponse containing the oEmbed lookup result.
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).
Accepted but currently ignored; quotes are per-person and the count does not filter.
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.