> ## Documentation Index > Fetch the complete documentation index at: https://docs.dev.gojinko.com/llms.txt > Use this file to discover all available pages before exploring further. # flight-award-search (preview) > Search award (miles) availability across airline loyalty programs > [!WARNING] > > Flight award search is a preview. It is not yet stable, and its fields and behavior may change. > It returns award prices only: it creates no offer, quote or booking, and results cannot be added > to a trip. Award fares carry no `trip_item_token`. See > [Flight award search](https://docs.dev.gojinko.com/guides/flight-booking.md#flight-award-search-preview). ## OpenAPI ````yaml api-reference/public-api-dev.yaml POST /v1/flight_award_search openapi: 3.0.0 info: title: Jinko Public API version: 0.111.0 description: >- Curated public REST surface for Jinko. Authenticated with jnk_ API keys. See https://docs.gojinko.com for guides. ### Per-end-user attribution On booking calls you may send an optional `X-End-User-Id` request header to attribute the booking to one of your own end users (for per-end-user attribution and rate-limiting). The value is an **opaque, tenant-scoped** identifier that you choose — not a Jinko account id. Omit it to book as the tenant. Values prefixed `user_` or `org_` are rejected. servers: - url: https://api.dev.gojinko.com description: Development preview security: [] paths: /v1/flight_award_search: post: tags: - Discovery summary: Search award (miles) availability across airline loyalty programs description: >- Preview: this endpoint is not yet stable, and its fields and behaviour may change. Search the award seats airline loyalty programs offer on a route and date, one way or round trip, priced in miles plus taxes. Every filter is applied as sent. Returns award prices only: it creates no offer, quote or booking, and the results cannot be added to a trip. An award flight has no `trip_item_token` and is booked with the loyalty program. Use `flight_search` for cash prices and booking. requestBody: content: application/json: schema: $ref: '#/components/schemas/FlightAwardSearchRequest' responses: '200': description: Award flights matching the filters content: application/json: schema: $ref: '#/components/schemas/FlightAwardSearchResponse' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: BAD_REQUEST message: Malformed JSON in request body. doc_url: https://docs.gojinko.com/concepts/errors '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: AUTH_REQUIRED message: Invalid or expired API key. doc_url: https://docs.gojinko.com/authentication/api-keys '402': description: Payment required — organization balance exhausted content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: PAYMENT_REQUIRED message: >- Insufficient balance — this call costs $0.0150 and your organization has $0.0000 available. Top up at https://dashboard.gojinko.com/developers/billing/topup doc_url: https://docs.gojinko.com/concepts/errors '404': description: Resource not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: NOT_FOUND message: Resource not found. doc_url: https://docs.gojinko.com/concepts/errors '409': description: The operation conflicts with the current state of the resource content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: CONFLICT message: >- The operation conflicts with the current state of the resource. doc_url: https://docs.gojinko.com/concepts/errors '410': description: The resource this request names no longer exists content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: GONE message: The resource no longer exists. doc_url: https://docs.gojinko.com/concepts/errors '422': description: Validation error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: BAD_REQUEST message: A required field is missing or invalid. doc_url: https://docs.gojinko.com/concepts/errors '429': description: Rate limit or quota exceeded headers: Retry-After: description: >- Seconds to wait before retrying. Absent when no interval applies. schema: type: string content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: RATE_LIMITED message: Too many requests. Retry after the Retry-After delay. doc_url: https://docs.gojinko.com/concepts/errors '502': description: The travel provider rejected the request, or an upstream call failed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: UPSTREAM_REJECTED message: The request was declined for this offer. Try another offer. doc_url: https://docs.gojinko.com/concepts/errors '503': description: No travel provider can serve the request right now headers: Retry-After: description: >- Seconds to wait before retrying. Absent when no interval applies. schema: type: string content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: UPSTREAM_UNAVAILABLE message: >- The service is temporarily unavailable. Retry after the Retry-After delay. doc_url: https://docs.gojinko.com/concepts/errors '504': description: The travel provider did not answer in time content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: UPSTREAM_TIMEOUT message: >- The request timed out before a result was available. Retry the request. doc_url: https://docs.gojinko.com/concepts/errors security: - ApiKeyAuth: [] - BearerAuth: [] components: schemas: FlightAwardSearchRequest: type: object properties: origin: type: string pattern: ^[A-Za-z]{3}$ description: >- 3-letter IATA airport code. Each search covers this one departure airport; search other airports separately. example: LHR destination: type: string pattern: ^[A-Za-z]{3}$ description: >- 3-letter IATA airport code. Each search covers this one arrival airport; search other airports separately. example: JFK departure_date: type: string pattern: ^\d{4}-\d{2}-\d{2}$ description: Outbound date, `YYYY-MM-DD`, from today up to 361 days ahead. example: '2026-11-20' return_date: type: string pattern: ^\d{4}-\d{2}-\d{2}$ description: >- Return date, `YYYY-MM-DD`, on or after `departure_date`. Required when `trip_type` is `roundtrip`; refused when it is `oneway`. example: '2026-11-27' trip_type: type: string enum: - oneway - roundtrip description: >- `oneway` or `roundtrip`. `roundtrip` requires `return_date`. `oneway` refuses `return_date`, `return_departure_time_range` and `return_arrival_time_range`. example: roundtrip cabin_class: type: string enum: - economy - premium_economy - business - first description: Cabin to search. Omit it to search every cabin. example: business adults: type: integer minimum: 1 maximum: 9 default: 1 description: >- Travellers, 1–9. Every returned fare has at least this many award seats in its cabin. Count every traveller here: award seats are not priced by passenger type. max_stops: type: integer minimum: 0 maximum: 2 description: >- Maximum stops in each direction: `0` non-stop, `1` one connection, `2` two connections. example: 1 include_carriers: type: array items: type: string pattern: ^[A-Za-z0-9]{2}$ description: >- Keep only itineraries whose every segment is marketed by one of these IATA carriers. example: - AF - KL exclude_carriers: type: array items: type: string pattern: ^[A-Za-z0-9]{2}$ description: >- Drop itineraries with any segment marketed by one of these IATA carriers. example: - NK single_carrier_only: type: boolean description: Keep only itineraries marketed end-to-end by one carrier. via_airports: type: array items: type: string pattern: ^[A-Za-z]{3}$ description: Keep only itineraries that connect at one of these airports. example: - AMS exclude_via_airports: type: array items: type: string pattern: ^[A-Za-z]{3}$ description: Drop itineraries that connect at any of these airports. example: - CDG aircraft_types: type: array items: type: string pattern: ^[A-Za-z0-9]{3}$ description: >- Keep only itineraries flown on these IATA aircraft (equipment) codes. example: - '359' - 77W departure_time_range: allOf: - $ref: '#/components/schemas/TimeRange' - description: Filter the outbound journey by local departure time-of-day. arrival_time_range: allOf: - $ref: '#/components/schemas/TimeRange' - description: Filter the outbound journey by local arrival time-of-day. return_departure_time_range: allOf: - $ref: '#/components/schemas/TimeRange' - description: >- Filter the return journey by local departure time-of-day (round trip only). return_arrival_time_range: allOf: - $ref: '#/components/schemas/TimeRange' - description: >- Filter the return journey by local arrival time-of-day (round trip only). connection_time_min_minutes: type: integer minimum: 0 description: >- Shortest acceptable connection, in minutes. Must not exceed `connection_time_max_minutes`. example: 60 connection_time_max_minutes: type: integer minimum: 1 description: Longest acceptable connection, in minutes. example: 240 max_total_duration_minutes: type: integer minimum: 1 description: Longest acceptable journey time in each direction, in minutes. example: 900 same_connection_airport_only: type: boolean description: >- Keep only itineraries whose connections leave from the airport they arrived at (no change of airport). limit: type: integer minimum: 1 maximum: 100 default: 50 description: >- Maximum number of flights returned, 1–100. `total` in the response counts every match. programs: type: array items: type: string enum: - aadvantage - atmos_rewards - skymiles - flying_blue - flying_club - trueblue - qantas_frequent_flyer - eurobonus - miles_and_smiles - mileageplus - velocity - etihad_guest - finnair_plus - aeromexico_rewards - azul_fidelidade - smiles_br - smiles_ar minItems: 1 maxItems: 17 description: Loyalty programs to search, by code. Omit it to search all 17. example: - flying_blue - flying_club max_miles: type: integer minimum: 1 description: >- Highest miles per traveller in the requested cabin. On a round trip the cap applies to outbound plus return together. example: 120000 saver_only: type: boolean default: false description: >- Keep only saver-level awards. Programs that have no saver level are not affected. max_mixed_cabin_share: type: number minimum: 0 maximum: 1 description: >- Largest share of the flying time that may be in a cabin lower than `cabin_class`, from 0 to 1. `0` keeps only journeys flown entirely in the requested cabin. example: 0.2 sort: type: string enum: - miles - departure - duration default: miles description: >- Order of `flights`: `miles` (fewest miles first), `departure` (earliest first) or `duration` (shortest first). intent: $ref: '#/components/schemas/IntentInput' required: - origin - destination - departure_date - trip_type example: origin: LHR destination: JFK departure_date: '2026-11-20' trip_type: roundtrip return_date: '2026-11-27' cabin_class: business adults: 1 programs: - flying_blue - flying_club - aadvantage max_stops: 1 FlightAwardSearchResponse: type: object properties: status: type: string enum: - complete - partial description: >- `complete` when every requested loyalty program was checked. `partial` when some loyalty programs were still being checked; call again to get their prices. trip_type: type: string enum: - oneway - roundtrip searched_at: type: string format: date-time total: type: integer description: Flights that match the filters; can be more than `flights` returns. flights: type: array items: $ref: '#/components/schemas/AwardFlight' instruction: type: string description: >- Guidance to show with the results: miles prices are reference information, cannot be added to a trip and are booked with the loyalty program; on a round trip, miles are outbound plus return. required: - status - trip_type - searched_at - total - flights - instruction description: >- Preview: this endpoint is not yet stable, and its fields and behaviour may change. Award flights for the requested route and dates. Returns award prices only: it creates no offer, quote or booking, and the results cannot be added to a trip. ErrorResponse: type: object properties: error: type: object properties: code: type: string enum: - INVALID_SEGMENTS_TO_EXCHANGE - PARTIAL_EXCHANGE_UNSUPPORTED - LEG_ALREADY_DEPARTED - DEPARTURE_DATE_IN_PAST - LEG_DATES_OUT_OF_ORDER - INVALID_EXCHANGE_REQUEST - NOT_EXCHANGEABLE - CREDENTIAL_FORMAT_INVALID - PAYMENT_TYPE_NOT_ENABLED - PAYMENT_CREDENTIAL_INVALID - TRIP_OWNED_BY_OTHER_PAYMENT - IDEMPOTENCY_KEY_REUSED - ATTEMPT_IN_PROGRESS - ATTEMPT_TERMINAL - TEMPORARILY_UNAVAILABLE - AUTH_REQUIRED - PAYMENT_REQUIRED - RATE_LIMITED - BAD_REQUEST - FORBIDDEN - NOT_FOUND - CONFLICT - GONE - QUOTE_PENDING - QUOTE_EXPIRED - TRIP_EXPIRED - TRIP_STATE_CONFLICT - OFFER_EXPIRED - OFFER_UNAVAILABLE - MISSING_CUSTOMER_DETAILS - INVALID_PHONE_NUMBER - INVALID_FLIGHT_NUMBER - CURRENCY_UNSUPPORTED - HOTEL_NAME_LOW_CONFIDENCE - DESTINATION_LOW_CONFIDENCE - UPSTREAM_REJECTED - UPSTREAM_UNAVAILABLE - UPSTREAM_TIMEOUT - UPSTREAM_ERROR - INTERNAL description: >- What went wrong, as a stable machine-readable code. This is a closed set — branch on it rather than on `message`, which is prose and may change. New codes arrive in a minor version, so treat an unknown one as its HTTP status. A code can also stop being emitted: it leaves this set in a minor version, named in the changelog, and a branch you wrote for it goes unreached rather than wrong. example: BAD_REQUEST message: type: string description: >- What went wrong, in prose. These codes always carry the same message, and it never includes text from a supplier: `RATE_LIMITED` — "Too many requests. Retry after the Retry-After delay."; `OFFER_EXPIRED` — "This offer has expired. Search again."; `OFFER_UNAVAILABLE` — "This offer is no longer available. Search again."; `UPSTREAM_REJECTED` — "The request was declined for this offer. Try another offer."; `UPSTREAM_UNAVAILABLE` — "The service is temporarily unavailable. Retry after the Retry-After delay."; `UPSTREAM_TIMEOUT` — "The request timed out before a result was available. Retry the request."; `UPSTREAM_ERROR` — "The request could not be completed.". doc_url: type: string field: type: string description: >- On a 400 `BAD_REQUEST` that names one refused input: the path of that field in your request, e.g. `selections[1].quantity` for the second selection of a `select_ancillaries` call. Absent when the refusal names no single field. example: selections[1].quantity required: - code - message required: - error TimeRange: type: object properties: earliest: type: string pattern: ^([01]\d|2[0-3]):[0-5]\d$ example: '08:00' latest: type: string pattern: ^([01]\d|2[0-3]):[0-5]\d$ example: '12:00' description: >- Inclusive local time-of-day window, 24-hour "HH:MM". Either bound may be omitted: only `earliest` means "at or after", only `latest` means "at or before". IntentInput: type: object properties: user_intent: type: string nullable: true description: >- The user's natural-language intent: the Alpic PII-stripped paraphrase when available, else a best-effort fallback to the client-provided NL query. example: find a cheap flight to Tokyo AwardFlight: type: object properties: flight_id: type: string description: >- Identifies this flight within this response only. It is not a `trip_item_token` and cannot be added to a trip. outbound: $ref: '#/components/schemas/AwardItinerary' inbound: allOf: - $ref: '#/components/schemas/AwardItinerary' - nullable: true fares: type: array items: $ref: '#/components/schemas/AwardFare' description: Award fares, fewest miles first. required: - flight_id - outbound - inbound - fares description: >- A one-way journey, or an outbound and return pair on a round trip, with the award fares of every program that has seats on it. `inbound` is null on a one-way search. AwardItinerary: type: object properties: departure: type: string description: Departure from the first airport, local time there, ISO 8601. example: '2026-11-20T11:40:00' arrival: type: string description: Arrival at the last airport, local time there, ISO 8601. example: '2026-11-20T14:55:00' duration_minutes: type: integer example: 495 stops: type: integer example: 0 segments: type: array items: $ref: '#/components/schemas/AwardSegment' required: - departure - arrival - duration_minutes - stops - segments description: The flights of one direction, in order. AwardFare: type: object properties: program: $ref: '#/components/schemas/LoyaltyProgram' cabin_class: type: string enum: - economy - premium_economy - business - first miles: type: integer description: Miles per traveller. On a round trip, outbound plus return. example: 100000 taxes: allOf: - $ref: '#/components/schemas/MoneyValue' - description: >- Taxes and fees per traveller in the program’s own currency. Absent when the program publishes no tax currency; the miles price still applies. by_direction: type: object nullable: true properties: outbound: $ref: '#/components/schemas/DirectionPrice' inbound: $ref: '#/components/schemas/DirectionPrice' required: - outbound - inbound description: >- On a round trip, the price of each direction; null on a one-way search. seats_available: type: integer description: >- Award seats available. On a round trip, the smaller of the two directions. example: 2 saver: type: boolean nullable: true description: >- Whether this is a saver-level award; null when the program has no saver level. mixed_cabin_share: type: number description: >- Share of the flying time in a cabin lower than `cabin_class`, from 0 to 1. example: 0 required: - program - cabin_class - miles - by_direction - seats_available - saver - mixed_cabin_share description: >- One program’s award price for a flight in one cabin. On a round trip, `miles` and `taxes` are outbound plus return. AwardSegment: type: object properties: marketing_carrier: type: string example: VS operating_carrier: type: string example: VS flight_number: type: string example: VS45 origin: type: string example: LHR destination: type: string example: JFK departure: type: string description: Departure, local time at `origin`, ISO 8601. example: '2026-11-20T11:40:00' arrival: type: string description: Arrival, local time at `destination`, ISO 8601. example: '2026-11-20T14:55:00' aircraft: type: string example: '351' required: - marketing_carrier - operating_carrier - flight_number - origin - destination - departure - arrival - aircraft description: One flight of an award itinerary. LoyaltyProgram: type: object properties: code: type: string description: 'Program code: one of the values `programs` accepts.' example: flying_blue name: type: string example: Flying Blue airline: type: string description: IATA code of the airline that runs the program. example: AF required: - code - name - airline description: An airline loyalty program. MoneyValue: type: object properties: value: type: integer description: >- Integer amount in MINOR units at the ISO 4217 digits of `currency`: divide by 10 ** decimal_places to get the amount. Signed where the field says so (a price change delta). example: 41250 currency: type: string pattern: ^[A-Z]{3}$ description: ISO 4217 currency code. example: USD decimal_places: type: integer description: >- The ISO 4217 digits of `currency` (2 for USD/EUR, 0 for JPY/KRW, 3 for BHD/KWD), and the scale of `value`. example: 2 display: type: string description: >- The same figure as a string ready to show: the ISO 4217 code, a space, then the amount at `decimal_places`, e.g. "USD 412.50". Show this; compute with `value`. example: USD 412.50 required: - value - currency - decimal_places - display description: >- Money as every new field carries it: `value` is an INTEGER in minor units at the ISO 4217 digits of `currency` (`decimal_places`), and `display` is the same figure ready to show. All four members are always present; a figure the platform does not know is absent, never `{value: 0}`. New integrations read the `*_money` fields (and `value` on the objects that carry it); the two-scale rule described on `Money` applies only to the deprecated fields. DirectionPrice: type: object properties: miles: type: integer example: 50000 taxes: allOf: - $ref: '#/components/schemas/MoneyValue' - description: >- Taxes and fees per traveller in the program’s own currency. Absent when the program publishes no tax currency; the miles price still applies. seats_available: type: integer example: 2 saver: type: boolean nullable: true required: - miles - seats_available - saver description: >- The award price of one direction of a round trip, per traveller. `saver` is null when the program has no saver level. securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key BearerAuth: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.