Skip to main content
POST
Search flights across selected providers

Authorizations

​
Authorization
string
header
required

Tenant secret key (lcr_…). Server-side only.

Headers

​
X-Locus-Session-Id
string

Required only when the end-user JWT carries sid. Send the original high-entropy session value; sid is its SHA-256 fingerprint. Ignored for secret-key authentication.

Required string length: 16 - 128
Pattern: ^[A-Za-z0-9][A-Za-z0-9._:-]{15,127}$
​
Idempotency-Key
string
required

One key per logical travel search. Reuse it with an identical request to replay or finish the run.

​
X-Locus-End-User
string

Optional end-user identity for a tenant secret or sandbox key. It must agree with body externalUserId when both are present. Case-sensitive immutable ID in the tenant namespace. Prefer an identity-provider subject, not an email address.

Required string length: 1 - 200
Pattern: ^[A-Za-z0-9][A-Za-z0-9._:@/-]{0,199}$

Body

application/json

Preferred and excluded values cannot overlap. minLayoverMinutes cannot exceed maxLayoverMinutes. Defaults are selected from optimize when optional depth controls are absent.

​
origin
string
required

IATA code or place name. Three-letter codes are normalized to uppercase.

Required string length: 2 - 120
​
destination
string
required

Must differ from origin.

Required string length: 2 - 120
​
departureDate
string<date>
required

Real calendar date in YYYY-MM-DD form.

​
returnDate
string<date>

Optional return date on or after departureDate.

​
adults
integer
default:1
Required range: 1 <= x <= 9
​
children
integer
default:0
Required range: 0 <= x <= 8
​
infants
integer
default:0

Cannot exceed adults. Total travelers cannot exceed nine.

Required range: 0 <= x <= 4
​
cabinClass
enum<string>
default:economy
Available options:
economy,
premium_economy,
business,
first
​
currency
string
default:USD
Pattern: ^[A-Za-z]{3}$
​
optimize
enum<string>[]

Cost favors fewer inexpensive sources, quality increases depth, and context favors compact agent-readable output.

Maximum array length: 3
Available options:
cost,
quality,
context
​
preferredAirlines
string[]
Maximum array length: 20
Required string length: 1 - 100
​
excludedAirlines
string[]
Maximum array length: 20
Required string length: 1 - 100
​
preferredAirports
string[]
Maximum array length: 20
Required string length: 1 - 100
​
excludedAirports
string[]
Maximum array length: 20
Required string length: 1 - 100
​
maxStops
integer
Required range: 0 <= x <= 3
​
minLayoverMinutes
integer
Required range: 0 <= x <= 1440
​
maxLayoverMinutes
integer
Required range: 0 <= x <= 2880
​
maxDurationMinutes
integer
Required range: 30 <= x <= 10080
​
maxPrice
number

Maximum itinerary price in currency.

Required range: x <= 10000000
​
departAfter
string
Pattern: ^(?:[01]\d|2[0-3]):[0-5]\d$
​
departBefore
string
Pattern: ^(?:[01]\d|2[0-3]):[0-5]\d$
​
arriveAfter
string
Pattern: ^(?:[01]\d|2[0-3]):[0-5]\d$
​
arriveBefore
string
Pattern: ^(?:[01]\d|2[0-3]):[0-5]\d$
​
maxResults
integer
Required range: 1 <= x <= 50
​
maxProviders
integer
Required range: 1 <= x <= 11
​
providers
enum<string>[]

Optional explicit provider selection, still narrowed by credential, catalog, availability, and request compatibility.

Maximum array length: 11
Available options:
aircanada,
duffel,
stabletravel,
almosafer,
flightconnections,
justfly,
kayak_hk,
skyscanner,
skiplagged,
trip,
united
​
maxCredits

Aggregate no-dispatch ceiling for all selected child calls, in account credits.

Pattern: ^(?:0*[1-9]\d*)(?:\.\d{1,6})?$|^0*\.0*[1-9]\d{0,5}$
​
externalUserId
string

Case-sensitive immutable ID in the tenant namespace. Prefer an identity-provider subject, not an email address.

Required string length: 1 - 200
Pattern: ^[A-Za-z0-9][A-Za-z0-9._:@/-]{0,199}$
​
attribution
object

Optional JSON attribution copied to child calls.

Response

Normalized, ranked flight search with provider outcomes and aggregate billing

​
object
any
required
​
capability
any
required
​
routerVersion
string
required
​
runId
string<uuid>
required
​
search
object
required

Preferred and excluded values cannot overlap. minLayoverMinutes cannot exceed maxLayoverMinutes. Defaults are selected from optimize when optional depth controls are absent.

​
appliedOptimizations
enum<string>[]
required
Available options:
cost,
quality,
context
​
partial
boolean
required

True when at least one selected provider did not produce a complete successful result.

​
warnings
string[]
required
​
providers
object[]
required
​
itineraries
object[]
required
​
itineraryCount
integer
required
Required range: x >= 0
​
bookability
object
required
​
feedback
object
required
​
billing
object
required