PApaywithlocus
Travel routing

Search flights across selected providers

Feature-gated system-managed capability router. Locus plans eligible providers, executes them concurrently, normalizes and deduplicates itineraries, ranks offers, and returns aggregate billing. Use the preview route first when you need an estimate. A narrower request maxCredits or credential-level ceiling prevents dispatch when the aggregate estimate is too high. Retries must reuse the same Idempotency-Key and identical logical request; a 202 response means one or more child providers are still processing, so retry with the same key.

post/wrapped/credits/locus-travel/flight-search

Request

  • Base URL
    https://api.paywithlocus.com/api
  • URL
    https://api.paywithlocus.com/api/wrapped/credits/locus-travel/flight-search
  • Auth
    • HTTP bearer
    • or HTTP bearer
    • or HTTP bearer
    • or HTTP bearer

Headers

X-Locus-Session-Idstring

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.

Idempotency-Keystring required

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

X-Locus-End-Userstring

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

Optional end-user identity for a tenant secret or sandbox key. It must agree with body externalUserId when both are present.

Request body

originstring required

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

destinationstring required

Must differ from origin.

departureDatestring date required

Real calendar date in YYYY-MM-DD form.

returnDatestring date

Optional return date on or after departureDate.

adultsinteger
childreninteger
infantsinteger

Cannot exceed adults. Total travelers cannot exceed nine.

cabinClass'economy' | 'premium_economy' | 'business' | 'first'
currencystring
optimizestring[]

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

preferredAirlinesstring[]
excludedAirlinesstring[]
preferredAirportsstring[]
excludedAirportsstring[]
maxStopsinteger
minLayoverMinutesinteger
maxLayoverMinutesinteger
maxDurationMinutesinteger
maxPricenumber

Maximum itinerary price in currency.

departAfterstring
departBeforestring
arriveAfterstring
arriveBeforestring
maxResultsinteger
maxProvidersinteger
providersstring[]

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

externalUserIdstring

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

attributionobject

Optional JSON attribution copied to child calls.

Response

Normalized, ranked flight search with provider outcomes and aggregate billing

object'locus.travel_flight_search' required
capability'travel.flight_search' required
routerVersionstring required
runIdstring uuid required
appliedOptimizationsstring[] required
partialboolean required

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

warningsstring[] required
itineraryCountinteger required

Changes

No recorded changes to this operation across all 1 revision of this API.