> ## 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-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.
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: number
          example: 412.5
        currency:
          type: string
          example: USD
        decimal_places:
          type: integer
          example: 2
      required:
        - value
        - currency
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
    BearerAuth:
      type: http
      scheme: bearer

````