> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gojinko.com/llms.txt
> Use this file to discover all available pages before exploring further.

# flight-calendar

> Search flights between a known origin and destination for flexible dates

Find priced itineraries between a known origin and destination using cached results, ideal when the user is flexible on dates. It answers questions like "cheapest week to fly Paris to Barcelona in June" or "best Friday to Sunday options from JFK to LAX next month". Each result includes an offer token you can pass into a live price check or directly into a trip.


## OpenAPI

````yaml api-reference/public-api.yaml POST /v1/flight_calendar
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.


    ### 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. WorkOS-shaped values (prefixed `user_` or `org_`) are rejected.
servers: []
security: []
paths:
  /v1/flight_calendar:
    post:
      tags:
        - Discovery
      summary: Search flights between a known origin and destination for flexible dates
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FlightDiscoveryRequest'
      responses:
        '200':
          description: Matching itineraries
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlightCalendarResponse'
        '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:
    FlightDiscoveryRequest:
      type: object
      properties:
        origins:
          type: array
          items:
            type: string
          minItems: 1
          example:
            - NYC
        destinations:
          type: array
          items:
            type: string
          example:
            - PAR
        origin_type:
          type: string
          enum:
            - city
            - airport
          default: city
        destination_type:
          type: string
          enum:
            - city
            - airport
          default: city
        departure_dates:
          type: array
          items:
            type: string
            pattern: ^\d{4}-\d{2}-\d{2}$
          example:
            - '2026-07-15'
        departure_date_ranges:
          type: array
          items:
            $ref: '#/components/schemas/DateRange'
        return_dates:
          type: array
          items:
            type: string
            pattern: ^\d{4}-\d{2}-\d{2}$
          example:
            - '2026-07-22'
        return_date_ranges:
          type: array
          items:
            $ref: '#/components/schemas/DateRange'
        stay_days:
          type: integer
          minimum: 0
          exclusiveMinimum: true
          example: 7
        stay_days_range:
          type: object
          properties:
            min:
              type: integer
            max:
              type: integer
          required:
            - min
            - max
        trip_type:
          type: string
          enum:
            - oneway
            - roundtrip
          example: roundtrip
        cabin_class:
          type: string
          enum:
            - economy
            - premium_economy
            - business
            - first
          example: economy
        direct_only:
          type: boolean
          example: false
        adults:
          type: integer
          minimum: 0
          example: 1
        children:
          type: integer
          minimum: 0
        infants_in_lap:
          type: integer
          minimum: 0
        infants_in_seat:
          type: integer
          minimum: 0
        youth:
          type: integer
          minimum: 0
        student:
          type: integer
          minimum: 0
        ages:
          type: array
          items:
            type: integer
            minimum: 0
        residency_country:
          type: string
          minLength: 2
          maxLength: 2
        max_total:
          type: number
          minimum: 0
          exclusiveMinimum: true
          example: 800
        currency:
          type: string
          example: USD
        locale:
          type: string
          example: en-US
        limit:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
        offset:
          type: integer
          minimum: 0
          default: 0
        sort_by:
          type: string
          enum:
            - lowest
            - recommendation
          default: lowest
        intent:
          $ref: '#/components/schemas/IntentInput'
      required:
        - origins
        - trip_type
      example:
        origins:
          - NYC
        destinations:
          - PAR
        trip_type: roundtrip
        departure_date_ranges:
          - start: '2026-09-01'
            end: '2026-09-30'
        stay_days: 7
        cabin_class: economy
        adults: 1
        currency: USD
    FlightCalendarResponse:
      type: object
      properties:
        itineraries:
          type: array
          items:
            $ref: '#/components/schemas/Itinerary'
        next_page_token:
          type: string
          example: eyJvZmZzZXQiOjIwfQ==
      required:
        - itineraries
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            doc_url:
              type: string
          required:
            - code
            - message
      required:
        - error
    DateRange:
      type: object
      properties:
        start:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
        end:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
      required:
        - start
        - end
      example:
        start: '2026-06-01'
        end: '2026-06-30'
    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
    Itinerary:
      type: object
      properties:
        id:
          type: string
          example: itin_9f3b2a17
        origin:
          type: object
          properties:
            code:
              type: string
            name:
              type: string
          required:
            - code
          example:
            code: JFK
            name: New York John F. Kennedy
        destination:
          type: object
          properties:
            code:
              type: string
            name:
              type: string
          required:
            - code
          example:
            code: CDG
            name: Paris Charles de Gaulle
        total:
          $ref: '#/components/schemas/Amount'
        cabin_class:
          type: string
          example: economy
      required:
        - id
        - origin
        - destination
    Amount:
      type: object
      properties:
        value:
          type: integer
          description: >-
            Integer amount in MINOR units, always paired with decimal_places —
            divide by 10 ** decimal_places to display. Example: value 15977 with
            decimal_places 2 is 159.77 USD. Rendering this field directly shows
            prices 100x too high for 2-decimal currencies.
          example: 41250
        currency:
          type: string
          description: ISO 4217 currency code.
          example: USD
        decimal_places:
          type: integer
          description: >-
            Scale of the integer value/amount: display = integer / 10 **
            decimal_places. Always sent alongside minor-unit amounts. Usually
            the ISO 4217 digits of the currency (2 for USD/EUR/GBP, 0 for
            JPY/KRW, 3 for BHD/JOD/KWD) but currency-converted prices can carry
            a different scale — ALWAYS use the decimal_places sent with the
            amount, never a hardcoded 2. Only if the field is genuinely absent
            on a value-shaped object, fall back to the ISO digits for the
            currency.
          example: 2
      required:
        - value
        - currency
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
    BearerAuth:
      type: http
      scheme: bearer

````