Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Wego Flights API
description: 'Wego''s travel API: places, flights, hotels and fares. Please see https://docs.wego.com for more details.'
version: 0.19.0
servers:
- url: https://api.wego.com
security:
- oauth2: []
- bearerAuth: []
tags:
- name: Flights
description: 'The flight funnel: `createFlightSearch` starts an async search, `getFlightSearchResults` reads ranked snapshots while providers answer, `getFlightTrip` opens one trip with every fare. Fares with `kind: "wego"` continue into `getFareOptions` and `getFareBookingLink`; airline and partner fares carry their own handoff URL instead. Ids expire; a `404` means search again. `getFlightSchedules` sits outside the funnel – a published timetable with no prices and no search to settle.'
paths:
/v1/flights/searches:
post:
operationId: createFlightSearch
tags:
- Flights
summary: Create a flight search
description: Creates a metasearch for the given route/dates/passengers and returns its searchId. Results accrue asynchronously – poll getFlightSearchResults with the returned searchId to read ranked trips.
responses:
'201':
description: Search created.
content:
application/json:
schema:
type: object
properties:
searchId:
type: string
description: The id of the created search; pass it to the results and trip reads.
siteCode:
type: string
description: The site code (Wego market) the search was created for.
siteCodeSource:
type: string
enum:
- explicit
- default
description: 'How the API resolved siteCode: explicit (caller-supplied – including a market a client derived and passed) or default (US, no site supplied).'
required:
- searchId
- siteCode
- siteCodeSource
description: The created search id and the market it was created for.
'400':
description: Invalid request body/query/path parameters.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
'401':
description: Missing or invalid bearer token.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
'429':
description: Rate limit exceeded; retry after the `Retry-After` seconds.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
'502':
description: The upstream flights service returned an invalid response.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
'503':
description: The flights service is temporarily unavailable (`upstream_unavailable`) or rate-limited upstream (`upstream_rate_limited`); retry after the `Retry-After` seconds.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
from:
type: string
pattern: ^[A-Z]{3}$
example: DXB
description: Origin airport or city IATA code, e.g. DXB.
to:
type: string
pattern: ^[A-Z]{3}$
example: LHR
description: Destination airport or city IATA code, e.g. LHR.
fromDate:
type: string
pattern: ^\d{4}-\d{2}-\d{2}$
description: Outbound departure date, YYYY-MM-DD. Not in the past, within a year.
toDate:
type: string
pattern: ^\d{4}-\d{2}-\d{2}$
description: Return date, YYYY-MM-DD. Omit for a one-way search.
cabin:
default: economy
description: Cabin class requested for all passengers.
type: string
enum:
- economy
- premium_economy
- business
- first
adults:
default: 1
description: Adult passengers (1-9). Defaults to 1. Note the hotel search defaults adults to 2, since a room sleeps two.
type: integer
minimum: 1
maximum: 9
children:
default: 0
description: Child passengers (0-8). Defaults to 0.
type: integer
minimum: 0
maximum: 8
infants:
default: 0
description: Infant passengers (0-8). Must not exceed adults. Defaults to 0.
type: integer
minimum: 0
maximum: 8
currency:
default: USD
description: Pricing currency as a 3-letter ISO 4217 code. Defaults to USD.
type: string
pattern: ^[A-Z]{3}$
locale:
default: en
description: Response language tag (e.g. en, ar). Defaults to en.
type: string
minLength: 1
maxLength: 35
siteCode:
type: string
pattern: ^[A-Z]{2}$
description: 'Wego market (point of sale) as a 2-letter code, e.g. AE. Optional: if omitted the API defaults to US. A client that knows the user''s market (the wego CLI derives it from the id_token) passes it as an explicit siteCode; the response always reports the siteCode used.'
required:
- from
- to
- fromDate
additionalProperties: false
/v1/flights/schedules:
get:
operationId: getFlightSchedules
tags:
- Flights
summary: Published timetable for a route
description: What actually flies a route – times, duration, aircraft, and the weekdays each flight runs – with no prices and no search to settle. Nonstop flights only. Airport codes resolve to their parent city (LHR to LON), and metadata echoes what each side resolved to.
responses:
'200':
description: Scheduled flights, plus the resolved route and the market used.
content:
application/json:
schema:
type: object
properties:
results:
type: array
items:
type: object
properties:
airlineCode:
type: string
description: Marketing carrier code – what `airline` filters on.
departureAirportCode:
type: string
description: Departure airport IATA code.
arrivalAirportCode:
type: string
description: Arrival airport IATA code.
departureTime:
type: string
description: Local HH:MM at the departure airport.
arrivalTime:
type: string
description: Local HH:MM at the arrival airport.
durationMinutes:
type: number
description: Total scheduled duration in minutes.
stopsCount:
type: number
description: Stops on the route, as the timetable reports them; 0 is nonstop. This read covers nonstop scheduled flights, so a connecting itinerary is absent rather than listed with a stop.
arrivalDayOffset:
type: number
description: Days the arrival falls after departure; 1 means next-day.
segments:
type: array
items:
type: object
properties:
departureAirportCode:
type: string
description: Departure airport IATA code.
arrivalAirportCode:
type: string
description: Arrival airport IATA code.
departureTime:
type: string
description: Local HH:MM at the departure airport.
arrivalTime:
type: string
description: Local HH:MM at the arrival airport.
airlineCode:
type: string
description: Marketing carrier IATA code.
airlineName:
description: Marketing carrier display name, when resolved.
type: string
durationMinutes:
description: Segment duration in minutes, when reported.
type: number
flightNumber:
description: The marketed designator, e.g. `TR 610`.
type: string
aircraftCode:
description: Aircraft type code, when reported.
type: string
aircraftName:
description: Aircraft type name, when reported.
type: string
required:
- departureAirportCode
- arrivalAirportCode
- departureTime
- arrivalTime
- airlineCode
description: The individual flights that make up this schedule.
operatingPeriods:
type: array
items:
type: object
properties:
weekdays:
description: Days of the week the flight operates, 1 Monday to 7 Sunday. Absent means the upstream published no recurrence for this period.
type: array
items:
type: integer
minimum: 1
maximum: 7
startDate:
description: First date this recurrence is published for, as YYYY-MM-DD.
type: string
endDate:
description: Last date this recurrence is published for, as YYYY-MM-DD.
type: string
description: 'A published operating period: which weekdays the flight runs, and the date window that applies to.'
description: When this flight runs – one entry per published operating period. Empty when the upstream states no recurrence, which means unknown, never daily.
flightNumber:
description: The marketed designator, present on a single-segment schedule.
type: string
aircraftCode:
description: Aircraft type code, when reported.
type: string
required:
- airlineCode
- departureAirportCode
- arrivalAirportCode
- departureTime
- arrivalTime
- durationMinutes
- stopsCount
- arrivalDayOffset
- segments
- operatingPeriods
description: The scheduled flights for this route, a timetable with no prices.
metadata:
type: object
properties:
page:
type: integer
minimum: 1
maximum: 9007199254740991
description: The 1-based page returned.
pageSize:
type: integer
minimum: 1
maximum: 9007199254740991
description: Rows requested per page.
resultCount:
type: integer
minimum: 0
maximum: 9007199254740991
description: Scheduled flights on this page (always <= pageSize).
totalCandidates:
type: integer
minimum: 0
maximum: 9007199254740991
description: Scheduled flights the upstream held for this route, pre-pagination – the ceiling paging can reach. 0 means the upstream publishes no timetable for this route, NOT that nothing flies it.
hasMore:
type: boolean
description: True when a further page exists.
coverage:
type: string
enum:
- complete
- truncated
description: complete when the upstream returned its whole set for this route, truncated when it filled the API's upstream ceiling and may hold more. While truncated, read totalCandidates as a floor rather than a total.
from:
type: object
properties:
requested:
type: string
description: Exactly what the caller sent, uppercased.
resolvedCityCode:
type: string
description: The city code sent upstream – LHR resolves to LON.
required:
- requested
- resolvedCityCode
description: 'Departure route endpoint: what the caller sent and the city code it resolved to.'
to:
type: object
properties:
requested:
type: string
description: Exactly what the caller sent, uppercased.
resolvedCityCode:
type: string
description: The city code sent upstream – LHR resolves to LON.
required:
- requested
- resolvedCityCode
description: 'Arrival route endpoint: what the caller sent and the city code it resolved to.'
siteCode:
type: string
description: The market this request resolved to, as a 2-letter code. Echoed for consistency with the priced reads – a published timetable does not vary by market, so it does not change these rows.
siteCodeSource:
type: string
enum:
- explicit
- default
description: explicit when the caller supplied siteCode, default when the API applied the US floor.
required:
- page
- pageSize
- resultCount
- totalCandidates
- hasMore
- coverage
- from
- to
- siteCode
- siteCodeSource
description: The page returned, how much the upstream held, the resolved route endpoints, and the market echoed.
required:
- results
- metadata
'400':
description: Malformed code, a code that resolves to no city, or a page or pageSize outside its range – an out-of-range paging value is rejected, never clamped.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
'401':
description: Missing or invalid bearer token.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
'429':
description: Rate limit exceeded; retry after the `Retry-After` seconds.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
'502':
description: The upstream schedules service returned an invalid response.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
'503':
description: The schedules service is temporarily unavailable (`upstream_unavailable`) or rate-limited upstream (`upstream_rate_limited`); retry after the `Retry-After` seconds.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
parameters:
- in: query
name: from
schema:
type: string
pattern: ^[A-Z]{3}$
example: DXB
required: true
description: Departure city or airport code; an airport resolves to its city.
- in: query
name: to
schema:
type: string
pattern: ^[A-Z]{3}$
example: LHR
required: true
description: Arrival city or airport code; an airport resolves to its city.
- in: query
name: airline
schema:
type: string
pattern: ^[A-Z0-9]{2}$
description: Filter to one marketing carrier (e.g. SQ).
- in: query
name: siteCode
schema:
type: string
pattern: ^[A-Z]{2}$
description: Wego market as a 2-letter code. Omitted, the API defaults to US and says so in metadata.siteCodeSource.
- in: query
name: locale
schema:
default: en
type: string
minLength: 1
maxLength: 35
example: en
description: Response language tag.
- in: query
name: page
schema:
default: 1
type: integer
minimum: 1
maximum: 20
description: Page number, 1-based (max 20). Defaults to 1. A timetable is a bounded list the API reads whole, so paging is rarely needed and the cap is low by design.
- in: query
name: pageSize
schema:
default: 200
type: integer
minimum: 1
maximum: 200
description: Rows per page (1-200). Defaults to 200, which is also the maximum, so most routes return whole on one page. A busier route exceeds it and says so with hasMore. pageSize exists to narrow a long answer, never to force paging.
/v1/flights/searches/{searchId}/results:
get:
operationId: getFlightSearchResults
tags:
- Flights
summary: Read ranked flight results
description: 'Ranked trips as lean list cards (default 10, max 50 per page; out-of-range rejected 400), filters + sort applied. No completion flag: re-read (300ms→3s) until snapshotFareCount holds steady across two reads AND snapshotTripCount > 0. No fares[] on a card – read the trip for fares.'
responses:
'200':
description: The current ranked-trip snapshot, as list cards.
content:
application/json:
schema:
type: object
properties:
searchId:
type: string
description: The id of the search this snapshot belongs to.
currencyCode:
type: string
description: The currency the prices in this snapshot actually came back in, read off the fares themselves – so this, not metadata.currencyCode, is what a displayed number is denominated in. metadata.currencyCode reports what the read asked for and carries currencyCodeSource beside it; the two agree unless upstream declined to reprice into the requested currency.
metadata:
type: object
properties:
page:
type: integer
minimum: 1
maximum: 9007199254740991
description: 1-based page number of this snapshot.
pageSize:
type: integer
minimum: 1
maximum: 9007199254740991
description: Trips requested per page.
resultCount:
type: integer
minimum: 0
maximum: 9007199254740991
description: Trips on this page. The page only – judge a filter on totalCandidates, not this.
totalCandidates:
type: integer
minimum: 0
maximum: 9007199254740991
description: 'Trips matching this read''s filters across the whole snapshot – the count that judges a filter, never the page (results). Flights have no completion flag: settle on snapshotFareCount steady across two reads with snapshotTripCount above 0.'
hasMore:
type: boolean
description: Another page of trips follows.
filterOptions:
type: object
properties:
alliances:
type: array
items:
type: object
properties:
code:
type: string
description: The code the matching filter query param accepts.
name:
description: Display label for the code, when the snapshot dictionary resolves one.
type: string
count:
type: integer
minimum: 0
maximum: 9007199254740991
description: Trips carrying this value, deduped per trip and matched on any leg.
required:
- code
- count
description: Alliance codes present in this snapshot, by descending count.
airlines:
type: array
items:
type: object
properties:
code:
type: string
description: The code the matching filter query param accepts.
name:
description: Display label for the code, when the snapshot dictionary resolves one.
type: string
count:
type: integer
minimum: 0
maximum: 9007199254740991
description: Trips carrying this value, deduped per trip and matched on any leg.
required:
- code
- count
description: Airline codes present in this snapshot, by descending count.
bookingSites:
type: array
items:
type: object
properties:
code:
type: string
description: The code the matching filter query param accepts.
name:
description: Display label for the code, when the snapshot dictionary resolves one.
type: string
count:
type: integer
minimum: 0
maximum: 9007199254740991
description: Trips carrying this value, deduped per trip and matched on any leg.
required:
- code
- count
description: Booking provider codes present in this snapshot, by descending count.
stopoverAirports:
type: array
items:
type: object
properties:
code:
type: string
description: The code the matching filter query param accepts.
name:
description: Display label for the code, when the snapshot dictionary resolves one.
type: string
count:
type: integer
minimum: 0
maximum: 9007199254740991
description: Trips carrying this value, deduped per trip and matched on any leg.
required:
- code
- count
description: Stopover airport codes present in this snapshot, by descending count.
aircraft:
type: array
items:
type: object
properties:
code:
type: string
description: The code the matching filter query param accepts.
name:
description: Display label for the code, when the snapshot dictionary resolves one.
type: string
count:
type: integer
minimum: 0
maximum: 9007199254740991
description: Trips carrying this value, deduped per trip and matched on any leg.
required:
- code
- count
description: 'Aircraft type codes present in this snapshot, by descending count. name is the display label the results card publishes (A380, A320 Neo), and is NOT unique: several codes can carry the same label, so filter on code. Includes any non-aircraft equipment upstream reports on a leg, such as BUS for a surface segment.'
stopoverDurations:
description: 'The layover span this snapshot carries, in minutes, measured the way min-stopover-duration and max-stopover-duration are judged: per trip, the LARGEST leg total across its legs. Use it to bound a slider. Both ends are reachable - sending the published min or max with no other filter keeps at least the trip that set it. min is 0 whenever the snapshot holds one direct trip, which is the usual case. A range, not a count list, so it has no name or count. Absent when nothing here is measurable: an empty snapshot, or one where every trip carries a connecting leg whose layover upstream never stated.'
type: object
properties:
min:
type: number
minimum: 0
description: Shortest layover any trip in this snapshot carries, in minutes. 0 whenever one trip is direct. Echoes the upstream figure, so it is a whole number of minutes wherever upstream states one.
max:
type: number
minimum: 0
description: Longest layover any trip in this snapshot carries, in minutes.
required:
- min
- max
required:
- alliances
- airlines
- bookingSites
- stopoverAirports
- aircraft
description: 'The filter values this snapshot actually carries, ordered by count, over the same trips as snapshotTripCount. Codes are what the matching query param accepts, so pick from here rather than guessing: sending one listed code with no other filter makes metadata.totalCandidates equal that count exactly. It does NOT bound results, which stays the requested page, so compare against totalCandidates and not resultCount. Counts assume the default matching, so airlines-match=all or same-airline=true can keep fewer trips than the airlines count promises. count is trips, not legs or fares, and a trip is counted once however many of its legs or fares carry the value, including when only its return leg does. name is the display label: always present on bookingSites, where the provider code is its own fallback, present on airlines and stopoverAirports only when the snapshot dictionary resolves the code, and never present on alliances, which upstream gives no label. Still growing while the search aggregates, so judge an ABSENT code only once snapshotFareCount holds steady across two reads.'
snapshotTripCount:
type: integer
minimum: 0
maximum: 9007199254740991
description: Renderable trips before filter/sort/page. 0 means upstream has produced none yet; above 0 beside an empty `results` means a filter or page range excluded everything. Settling needs `snapshotFareCount` steady across two reads AND this above 0.
snapshotFareCount:
type: integer
minimum: 0
maximum: 9007199254740991
description: Upstream progress counter, for cross-read comparison only. Runs ahead of the fares returned and stays non-zero over an empty page, so read `resultCount`/`totalCandidates` for display. Settled = equal non-zero across two reads with `snapshotTripCount` above 0.
createdAt:
# --- truncated at 32 KB (160 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/wego/refs/heads/main/openapi/wego-flights-api-openapi.yml