Skip to main content
POST
Search flights from one sentence, with follow-ups
Send the traveller’s request in one sentence. The answer comes within about 20 seconds with 200: the options, or a question to answer in the same conversation. When the search takes longer, the answer is 202 with the early reply and a Location to read until the task ends. Continue the conversation with its context_id. Every option is priced live and carries fares: book one by adding its trip_item_token with POST /v1/trip add_item before its expires_at. The JSON answer of an ended turn carries its charge; the event stream does not.

Authorizations

​
X-API-Key
string
header
required

Headers

​
Idempotency-Key
string

Makes a retried message safe: a retry with the same key answers the first message again instead of sending a second one. Keys are scoped to the caller, not to the conversation, and the retried body is not compared: a different message needs a new key. 1–200 characters.

Required string length: 1 - 200
​
Prefer
string

wait=N (RFC 7240): answer after at most N seconds, never more than 20, with 202 and the early reply if the task has not ended by then. wait=0 answers at once. Without it the wait is 20 seconds. The wait applied is returned in Preference-Applied.

Maximum string length: 200
Example:

"wait=0"

Body

application/json
​
text
string
required

The traveller's request in one sentence, or the answer to the question asked in the previous turn.

Required string length: 1 - 2000
Example:

"Paris to Tokyo 3–17 October 2027 for 4, at most one stop"

​
timezone
string
required

The traveller's IANA time zone. Relative dates such as "next weekend" or "in March" are computed in it.

Example:

"Europe/Paris"

​
context_id
string

The conversation to continue, from an earlier answer. Omit to start a new conversation.

Required string length: 1 - 100
Example:

"ctx_example"

​
task_id
string

The task of that conversation the message answers. Optional: without it, a message continues the task waiting for an answer, or starts a new one.

Required string length: 1 - 100
Example:

"atk_example"

​
currency
string

Currency of the prices (ISO 4217).

Pattern: ^[A-Za-z]{3}$
Example:

"EUR"

​
effort
enum<string>

How much the search may do before it answers. low answers soonest; high checks the most and searches the most options. Defaults to medium.

Available options:
low,
medium,
high
Example:

"medium"

Response

The task ended this turn; or, with Accept: text/event-stream, the turn as it happens.

​
context_id
string | null
required

The conversation; send it with the next message to continue.

Example:

"ctx_example"

​
task_id
string
required
Example:

"atk_example"

​
status
enum<string>
required

working: the search is still running, read the task again. input_required: the message asks a question; answer it in the same conversation. completed: the options are in the answer. failed: see error. canceled: a later message or a cancel replaced it.

Available options:
working,
input_required,
completed,
failed,
canceled
​
message
string

The reply to show the traveller, in English.

Example:

"Three round-trip options Paris–Tokyo, 3–17 Oct 2027, for 4 adults with at most one stop."

​
question
enum<string>

What the reply asks for, when status is input_required. relax: no flight met every condition of the request; the reply names them and asks which one to drop or change.

Available options:
origin,
which_place,
dates,
passengers,
group_too_large,
contradiction,
relax,
out_of_scope
​
question_options
object[]

Choices for the question, when it has some.

​
criteria
object

The search the request was understood as: trip_type, origins, destinations, departure, return, passengers, priority (only when the request says how to rank the options), currency, and the filters, in the flight_search field names. Each place of origins and destinations has code, type, name and country_code; code is null for a country, a region or a kind of trip, whose airports searched are on each option's legs. departure has weekdays when the request fixes the days of the week the trips leave on: thursday and friday for a long weekend, friday for a weekend. A field is absent when the request did not state it, except passengers and currency, which carry the values searched with.

​
notes
object[]

Assumptions and adjustments made while understanding the request and searching, each with a kind and the fields of that kind, and an optional text.

​
options
object[]

Every itinerary of the answer, each priced live.

​
groups
object[]

How to present the options; groups name them by option_id. shortlist: the options for one route and dates. per_destination: one row per destination compared. Options always meet every filter of the request; a row without one says why in empty_reason.

​
has_more
boolean

More options are available; ask for more in the same conversation.

​
error
object

Why the task failed, when status is failed.

​
superseded_by
string

The task that replaced this one, when status is canceled.

​
charge
object

What a turn was charged to the organization's balance, once the turn has ended (completed, input_required, failed or canceled); every amount is 0 when the turn cost nothing. Absent while the task is working. Carried on JSON answers only: an event stream does not carry it, so read it with GET /v1/flight_ai_search/tasks/{task_id}.