Despegar Flights API
The Flights API from Despegar — 2 operation(s) for flights.
OpenAPI Specification
openapi: 3.0.3
info:
title: Activities Availability Flights API
version: 1.0.0
description: 'API for activities: tickets, modalities, availability, prebook, payments, and booking. Authentication via API Key.'
servers:
- url: https://api-dev.despegar.com/v3/activities-api
description: Sandbox
- url: https://apis-uat.despegar.com/v3/activities-api
description: UAT
- url: https://api.despegar.com/v3/activities-api
description: Production
security:
- ApiKeyAuth: []
tags:
- name: Flights
paths:
/flights-api/availability:
get:
tags:
- Flights
summary: Search
operationId: searchFlightsAvailability
parameters:
- name: site
in: query
required: true
schema:
type: string
minLength: 2
maxLength: 2
description: Refers to the country code and must be filled in with two alphabetical characters. The value must correspond to the POS associated with the API credentials.
example: br
- name: from
in: query
required: true
schema:
type: string
minLength: 3
maxLength: 3
description: Refers to the origin of the flight and must be filled in with the IATA code of the airport or city, containing three alphabetical digits.
example: BUE
- name: to
in: query
required: true
schema:
type: string
minLength: 3
maxLength: 3
description: Refers to the flight destination and must be filled in with the IATA code of the airport or city, containing three alphabetical digits.
example: SAO
- name: departure_date
in: query
required: true
schema:
type: string
format: date
description: Refers to the flight departure date and must be filled in the format YYYY-MM-DD.
example: '2026-11-14'
- name: return_date
in: query
required: false
schema:
type: string
format: date
description: Refers to the flight's return date and must be filled in the format YYYY-MM-DD. This parameter is only valid for round-trip flights.
example: '2026-11-16'
- name: adults
in: query
required: true
schema:
type: integer
minimum: 1
description: Refers to the number of adults on the flight and must be filled with a maximum of 9 adults, provided there are no other passengers. If there are children and infants on the flight, the total number of passengers must be 9, including adults, children, and infants.
example: 2
- name: children
in: query
required: false
schema:
type: integer
minimum: 0
default: 0
example: 0
description: Refers to the number of children on the flight, aged between 2 and 11 years old, and must be filled in with a total of 9 passengers including adults, children and infants.
example: 0
- name: infants
in: query
required: false
schema:
type: integer
minimum: 0
default: 0
example: 0
description: This field refers to the number of infants on the flight, aged between 0 and 23 months, and must be filled in with a number equal to or less than the number of adults, totaling 9 passengers including adults, children and infants.
example: 0
- name: currency
in: query
required: false
schema:
type: string
minLength: 3
maxLength: 3
description: This field determines in which currency the flight fare values will be returned in the response.
example: BRL
- name: cabin_type
in: query
required: false
schema:
type: string
enum:
- Business
- Firstclass
- Premium_business
- Premium_firstclass
- Premium_economy
- Economy
description: Allows filtering results by flight cabin type.
- name: offset
in: query
required: false
schema:
type: integer
minimum: 0
default: 0
example: 0
description: This field refers to the number of records that are ignored before starting to return results, that is, if a certain result displays 200 flights and I want to access from the 10th result, I send this parameter with 10 and thus the 11th record becomes the first of the displayed result, that is, it can be used for pagination of the result.
example: 0
- name: limit
in: query
required: false
schema:
type: integer
minimum: 1
description: Limits the number of flights returned, when not sent, 20 results are returned by default.
- in: query
name: group_by
schema:
type: string
description: 'Refers to grouping the received result. Can be filled with: No sending or ''none'': no grouping. ''flexible_penalty'': groups by final price, validating carrier, and baggage conditions.'
- in: query
name: order_by
schema:
type: string
description: 'This field determines the criteria used to sort the search results. When left blank by default, the ordering is from lowest to highest. The following are the possible values; all can be followed by ''_ascending'' or ''_descending'', with a few exceptions: - suitable (''_ascending'' only, recommended order) - total_price - stopscount - price (base price) - duration - airline - departure - arrival - fare_minus_discount - cross_selling_price - cross_selling_total_price - cabin_purity (''_descending'' only).'
- in: query
name: price
schema:
type: string
description: When sending this field with the value 'raw', the returned values will not be rounded.
- in: query
name: total_price_range
schema:
type: string
description: 'Delimits the total price returned in the response, example: 1000-2500.'
- in: query
name: stops
schema:
type: string
description: 'Refers to the number of stops on the flight. You can submit more than one option by separating them with commas. The allowed values are: - ''NONE'' (direct flights) - ''ONE'' (flights with one stop) - ''MORE_THAN_ONE'' (flights with more than one stop).'
- in: query
name: airlines
schema:
type: string
description: Delimits the airlines that will be returned in the search results, must be filled in with the airline's IATA code.
- in: query
name: alliances
schema:
type: string
description: 'This field allows you to search by airline alliance. An airline alliance is when two or more airlines cooperate so that travelers can make codeshare connections within their countries. Multiple options are allowed, separated by commas. The allowed values are: - ''OW'': One World - ''SA'': Star Alliance - ''ST'': Sky Team.'
- in: query
name: outbound_time_range
schema:
type: string
description: 'Defines the times of outbound flights within a given range. Example: 7:00-8:00.'
- in: query
name: inbound_time_range
schema:
type: string
description: Defines the return flight times within a specific range. Parameter valid only for roundtrip flights.
example: 15:00-16:00
- in: query
name: unique_airline
schema:
type: string
description: Specifies that the roundtrip flight will be the same airline when set to 'true'. When set to 'false' or not set, different airlines may be used. This parameter is only valid for roundtrip flights.
- in: query
name: unique_outbound_airport
schema:
type: string
description: When set to 'true', both the first departure and last arrival must be at the same airport. This parameter is valid only for roundtrip flights.
- in: query
name: outbound_duration_range
schema:
type: string
description: 'Refers to the duration interval in minutes of the outbound flight, the format is %d-%d. Ex.: 0-540.'
- in: query
name: inbound_duration_range
schema:
type: string
description: 'Refers to the duration interval in minutes of the return flight, the format is %d-%d. Ex.: 0-540. Parameter valid only for round-trip flights.'
- in: query
name: outbound_airports
schema:
type: string
description: This field delimits the search result to a specific airport on the way.
- in: query
name: inbound_airports
schema:
type: string
description: This field limits the search results to a specific airport on the return journey. This parameter is valid only for roundtrip flights.
- in: query
name: outbound_arrival_time_range
schema:
type: string
description: 'This field delimits the search results by filtering by the arrival time of flights on the outbound leg. Ex.: 16:00-16:30.'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
items:
type: array
items:
type: object
properties:
id:
type: string
description: ID automatically generated to identify the data sent in the search request.
outbound_choices:
type: array
description: This structure is a list and may return one or several outbound flight options.
items:
type: object
properties:
choice:
type: integer
duration:
type: string
format: time
segments:
type: array
items:
type: object
properties:
from:
type: string
to:
type: string
departure_datetime:
type: string
format: date-time
arrival_datetime:
type: string
format: date-time
duration:
type: string
format: time
airline:
type: string
description: IATA code of the marketing carrier (the airline selling the flight). This value always corresponds to a standard 2-letter IATA airline code and represents the airline under which the ticket is issued, regardless of which airline operates the flight.
operated_by:
type: string
description: IATA code of the operating carrier, i.e. the airline that physically operates the flight segment. This field is typically present in codeshare scenarios or airline groups with multiple operating certificates. When provided, it indicates the actual operator of the flight, not a list of airline affiliations.
flight_id:
type: string
description: Flight number
cabin_type:
type: string
description: Indicates the cabin class in which the flight segment is booked.
stopovers:
type: array
seats_remaining:
type: integer
equipment_code:
type: integer
ancillary:
type: object
properties:
baggages_info:
type: object
properties:
baggages:
type: array
items:
type: object
properties:
passenger_type:
type: string
quantity:
type: integer
meals:
type: array
entertainments:
type: array
booking_class:
type: string
baggage:
type: object
properties:
adult:
type: object
properties:
quantity:
type: integer
carry_on:
type: boolean
personal_item:
type: boolean
price_detail:
type: object
properties:
currency:
type: string
total:
type: integer
base:
type: integer
description: total base amount, summing the base fares for adult, child, and infant.
adult_base:
type: integer
description: base amount for an adult.
adult_total:
type: integer
description: ' total amount per adult.'
adults_subtotal:
type: integer
description: total sum for adults.
charges:
type: integer
description: total amount of taxes and fees.
net_fare:
type: object
description: this item returns the fields 'applied' (indicates whether the fare is available) and 'reference_price' (the fare amount when available).
properties:
applied:
type: boolean
reference_price:
type: number
validating_carrier:
type: string
description: identifies the airline that will issue the ticket.
booking_info:
type: array
description: this structure is a list and may return one or several booking options; the number of items returned varies with the number of flight options returned.
items:
type: object
properties:
outbound_choice:
type: integer
itinerary_id:
type: string
choice_id:
type: string
fare_basis_codes:
type: array
upselling_available:
type: boolean
description: Indicates whether the selected option supports upselling. A value of true does not guarantee the availability of upsell products, as availability is validated in real time by the Upselling service.
fare_family:
type: string
search_reason:
type: string
country:
type: string
fare_restricted_to:
type: string
flexible_policies:
type: array
booking_reservation:
type: array
items:
type: object
properties:
available:
type: boolean
alternatives_key:
type: string
public_parity_applied:
type: boolean
passenger_distribution:
type: object
properties:
adults:
type: integer
children:
type: integer
infants:
type: integer
last_minute:
type: boolean
tags:
type: array
route_type:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
oneOf:
- title: BAD_REQUEST
description: 'Possible cause: The flight search was sent with incomplete or out-of-policy inputs (one-way/round-trip with blank departure date, return beyond airline availability, origin equals destination, adults/total passengers > 9) or without the required Authorization header.'
type: object
properties:
code:
type: string
message:
type: string
description: Availability request validation/authentication error — missing or invalid fields (e.g., null departure date, dates beyond the airline sale window, same origin and destination, passenger count exceeding the maximum of 9) or missing Authorization header.
- title: INVALID_FIELD
description: 'Possible cause: The search was sent with blank or malformed values, unsupported codes, invalid ranges, or inconsistent constraints (e.g., blank/invalid site or currency; malformed/past departure/return dates or invalid intervals; invalid IATA codes for from/to/outbound/inbound airports; infants count > adults; disallowed group_by/order_by/price/with values; incorrect time/duration/price ranges; invalid airlines/alliances/stops).'
type: object
properties:
code:
type: string
message:
type: string
description: ' Availability request validation error — one or more fields are missing, invalid, out of range, or not in the allowed set (e.g., country/site, dates/intervals, origin/destination IATA, currency/price, filters/sorters, time/duration ranges, airlines/alliances/stops).'
- title: MISSING_REQUIRED_PARAMETER
description: 'Possible cause:The search was sent without the required adults parameter or with a passenger mix containing only children/infants (no adults). '
type: object
properties:
code:
type: string
message:
type: string
description: Missing required field 'adults' of type 'Integer'
- title: PARAMETER_TYPE_MISMATCH
description: 'Possible cause: The search was sent with incorrect data types: non-integer values for offset/limit and non-boolean values for unique_airline/unique_outbound_airport.'
type: object
properties:
code:
type: string
message:
type: string
description: Parameter type mismatch — expected integer/boolean values for pagination and flags.
'401':
description: Unauthorized
content:
application/json:
schema:
oneOf:
- title: UNAUTHORIZED
description: 'Possible cause:Service executed with an expired ''Authorization'' token '
type: object
properties:
code:
type: string
message:
type: string
description: Authorization token is expired.
'403':
description: FORBIDDEN
content:
application/json:
schema:
oneOf:
- title: FORBIDDEN
description: 'Possible cuase: The request was sent without the x-apikey header, with an invalid API key, or with an API key that doesn''t have permissions for the target service/method.'
type: object
properties:
code:
type: string
message:
type: string
description: API key access error — missing, invalid, or not authorized for the requested method.
'429':
description: RATE_LIMIT_EXCEEDED
content:
application/json:
schema:
oneOf:
- title: RATE_LIMIT_EXCEEDED
description: 'Possible cause:The request limit was exceeded '
type: object
properties:
code:
type: string
message:
type: string
description: The api client you have provided has exceeded its allowed quota
'500':
description: Internal Server Error
content:
application/json:
schema:
type: object
properties:
code:
type: string
example: INVALID_FILTER
message:
type: string
example: Invalid parameter
'503':
description: FLIGHT_PROVIDER_ERROR
content:
application/json:
schema:
oneOf:
- title: FLIGHT_PROVIDER_ERROR
description: 'Possible cause:Could not connect to flight providers '
type: object
properties:
code:
type: string
message:
type: string
description: Errors during connection with flight providers
/flights-api/upselling/{choice_id}:
get:
tags:
- Flights
summary: Upselling
operationId: Upselling
parameters:
- in: query
name: site
schema:
type: string
default: BR
description: site
required: true
- in: query
name: language
schema:
type: string
enum:
- PT
- ES
- EN
description: If omitted, the message is sent in English (EN) by default. If a value other than the supported ones listed below is provided, the message will not be sent.
required: false
- in: path
name: choice_id
schema:
type: string
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
oneOf:
- title: With availability
type: object
properties:
items:
type: array
items:
type: object
properties:
choice_id:
type: string
title:
type: string
fare_items:
type: array
items:
type: object
properties:
type:
type: string
enum:
- PERSONAL_ITEMS
- CARRY_ON
- BAGGAGE
- EXCHANGE
- REFUND
- SEAT_SELECTION
- SEAT_UPGRADE
- SEAT_UPGRADE_PREMIUM_ECONOMY
include:
type: boolean
inclusion_status:
type: string
enum:
- INCLUDED
- NOT_INCLUDED
price_detail:
type: object
properties:
total:
type: number
currency:
type: number
- title: No availability
type: object
properties:
items:
type: array
'400':
description: BAD_REQUEST
content:
application/json:
schema:
oneOf:
- title: BAD_REQUEST
type: object
properties:
code:
type: string
message:
type: string
description: Invalid or malformed choiceId
- title: MISSING_REQUIRED_PARAMETER
type: object
properties:
code:
type: string
message:
type: string
description: 'Missing required field ''site'' of type ''String'' '
'410':
description: UPSELLING_UNAVAILABLE
content:
application/json:
schema:
oneOf:
- title: UPSELLING_UNAVAILABLE
type: object
properties:
code:
type: string
message:
type: string
description: No upselling available for this flight
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-apikey
BearerAuth:
type: http
scheme: bearer
x-readme: {}