> ## 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-search

> Get live flight pricing — search by route, or re-price a known offer

Fetch live, bookable pricing for a specific route and date pair. Use it once the user has settled on exact travel dates, for example "Paris to New York departing June 1 returning June 8 in economy". It also reprices an offer surfaced earlier by the calendar or destination tools so you can confirm availability before adding it to a trip.

## Two modes, one endpoint

`POST /v1/flight_search` serves both modes:

* **Search mode**: filter-based live search by `origin`, `destination`, `departure_date`, and passengers. Returns priced offers, each fare carrying a `trip_item_token` you can add to a [trip](/api/trip).
* **Reprice mode**: pass an `offer_token` from discovery (`find_destination`, `flight_calendar`) to re-price that specific offer before adding it to a trip. The other route fields are ignored when `offer_token` is present.

The CLI mirrors this: pass `--offer-token` for reprice mode, omit it for search mode.


## OpenAPI

````yaml api-reference/public-api.yaml POST /v1/flight_search
openapi: 3.0.0
info:
  title: Jinko Public API
  version: 0.1.0
  description: >-
    Curated public REST surface for Jinko. Authenticated with jnk_ API keys. See
    https://docs.gojinko.com for guides.
servers: []
security: []
paths:
  /v1/flight_search:
    post:
      tags:
        - Pricing & booking
      summary: Get live flight pricing — search by route, or re-price a known offer
      description: >-
        Two modes: **search** — provide `origin` + `destination` +
        `departure_date` to price a route; or **price-check** — provide only
        `offer_token` to re-price a specific offer from a discovery endpoint.
        Exactly one mode per request.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FlightSearchRequest'
      responses:
        '200':
          description: Priced offers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlightSearchResponse'
        '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/api-reference/authentication
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: BAD_REQUEST
                  message: >-
                    origins: origins is required; trip_type: trip_type is
                    required
                  doc_url: https://docs.gojinko.com/concepts/errors
        '429':
          description: Rate limit or quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: RATE_LIMITED
                  message: Rate limit or quota exceeded.
                  doc_url: https://docs.gojinko.com/concepts/errors
        '502':
          description: Upstream service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: UPSTREAM_ERROR
                  message: Upstream travel provider returned an error. Please retry.
                  doc_url: https://docs.gojinko.com/concepts/errors
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
components:
  schemas:
    FlightSearchRequest:
      type: object
      properties:
        origin:
          type: string
          example: JFK
        destination:
          type: string
          example: LAX
        departure_date:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
        return_date:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
        trip_type:
          type: string
          enum:
            - oneway
            - roundtrip
        cabin_class:
          type: string
          enum:
            - economy
            - premium_economy
            - business
            - first
        direct_only:
          type: boolean
        max_price:
          type: number
          minimum: 0
          exclusiveMinimum: true
        include_carriers:
          type: array
          items:
            type: string
        exclude_carriers:
          type: array
          items:
            type: string
        limit:
          type: integer
          minimum: 1
          maximum: 100
          description: >-
            Max results to return (1-100). Default 20. Search mode only. Caps
            how many flights come back — only trims the set, since providers
            bound the real count.
          example: 20
        adults:
          type: integer
          minimum: 1
          default: 1
        children:
          type: integer
          minimum: 0
        infants:
          type: integer
          minimum: 0
        currency:
          type: string
        locale:
          type: string
        offer_token:
          type: string
        intent:
          $ref: '#/components/schemas/IntentInput'
      example:
        origin: JFK
        destination: CDG
        departure_date: '2026-09-01'
        return_date: '2026-09-08'
        trip_type: roundtrip
        cabin_class: economy
        adults: 1
        currency: USD
    FlightSearchResponse:
      type: object
      properties:
        offers:
          type: array
          items:
            $ref: '#/components/schemas/FlightOffer'
        exact_match_found:
          type: boolean
          example: true
      required:
        - offers
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            doc_url:
              type: string
          required:
            - code
            - message
      required:
        - error
    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
    FlightOffer:
      type: object
      properties:
        offer_id:
          type: string
          example: off_3a9f1b27c4
        provider:
          type: string
          example: sabre
        provider_name:
          type: string
          example: Sabre
        origin:
          type: object
          properties:
            code:
              type: string
            name:
              type: string
          example:
            code: JFK
            name: New York John F. Kennedy
        destination:
          type: object
          properties:
            code:
              type: string
            name:
              type: string
          example:
            code: LAX
            name: Los Angeles Intl
        is_round_trip:
          type: boolean
          example: false
        total_duration_minutes:
          type: number
          example: 385
        outbound:
          $ref: '#/components/schemas/FlightLeg'
        inbound:
          $ref: '#/components/schemas/FlightLeg'
        fares:
          type: array
          items:
            $ref: '#/components/schemas/Fare'
      required:
        - offer_id
        - origin
        - destination
        - fares
    FlightLeg:
      type: object
      properties:
        origin:
          type: string
          example: JFK
        destination:
          type: string
          example: LAX
        departure_datetime:
          type: string
          example: '2026-07-15T08:30:00-04:00'
        arrival_datetime:
          type: string
          example: '2026-07-15T11:55:00-07:00'
        duration_minutes:
          type: number
          example: 385
        airline:
          type: string
          example: AA
        airline_name:
          type: string
          example: American Airlines
        stops:
          type: number
          example: 0
    Fare:
      type: object
      properties:
        trip_item_token:
          type: string
          example: tit_5f8c1d3e9a
        cabin_class:
          type: string
          example: economy
        brand_name:
          type: string
          example: Main Cabin
        total_price:
          $ref: '#/components/schemas/Money'
        price_per_person:
          $ref: '#/components/schemas/Money'
        included_baggage:
          type: string
          example: 1 carry-on, 1 checked bag
        carry_on_baggage:
          type: string
          example: 1 carry-on included
        is_changeable:
          type: boolean
          example: true
    Money:
      type: object
      properties:
        amount:
          type: number
          example: 318.4
        value:
          type: number
        currency:
          type: string
          example: USD
        decimal_places:
          type: integer
          example: 2
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
    BearerAuth:
      type: http
      scheme: bearer

````