---
title: "Search for available flights"
url: "https://kongair.terwilligar.com/apis/llm-flight-booking-assistant-1-0-0/versions/76f089d9-b12c-4dd8-a400-e4c611faf544/operations/searchFlights"
---

> Full API specification: https://kongair.terwilligar.com/apis/llm-flight-booking-assistant-1-0-0/versions/76f089d9-b12c-4dd8-a400-e4c611faf544.md

# Search for available flights

`GET` `/flights/search`

Operation ID: `searchFlights`

Returns a list of available flights matching the criteria.

## Query parameters

- `origin` (string, required) - IATA code of origin airport
- `destination` (string, required)
- `departureDate` (string, date, required)
- `returnDate` (string, date, optional)
- `cabinClass` (string, optional)
- `limit` (integer, optional) - Page size
- `offset` (integer, optional) - Pagination offset

## Header parameters

- `Accept-Language` (string, optional) - Preferred language for response
- `X-Correlation-ID` (string, uuid, optional) - Correlation identifier for tracing

## Cookie parameters

- `session_id` (string, optional) - Session identifier

## Responses

- `200` - Successful search
- `400` - Invalid request
- `401` - Authentication required
- `500` - Internal server error

## OpenAPI definition

```yaml
openapi: 3.1.0
info:
  title: Flight LLM Booking API
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
    description: Production server
    variables:
      version:
        enum:
          - v1
          - v2
        default: v1
      region:
        enum:
          - us
          - eu
          - asia
        default: us
        description: Geographic region
  - url: https://sandbox.example.com/{version}
    description: Sandbox server
    variables:
      version:
        default: v1
paths:
  /flights/search:
    get:
      tags:
        - flights
      summary: Search for available flights
      description: Returns a list of available flights matching the criteria.
      operationId: searchFlights
      parameters:
        - $ref: "#/components/parameters/AcceptLanguage"
        - $ref: "#/components/parameters/CorrelationId"
        - in: query
          name: origin
          required: true
          schema:
            $ref: "#/components/schemas/IATACode"
          description: IATA code of origin airport
        - in: query
          name: destination
          required: true
          schema:
            $ref: "#/components/schemas/IATACode"
        - in: query
          name: departureDate
          required: true
          schema:
            type: string
            format: date
        - in: query
          name: returnDate
          schema:
            type: string
            format: date
        - in: query
          name: cabinClass
          schema:
            type: string
            enum:
              - economy
              - premium_economy
              - business
              - first
        - $ref: "#/components/parameters/PageLimit"
        - $ref: "#/components/parameters/PageOffset"
        - $ref: "#/components/parameters/SessionIdCookie"
      responses:
        "200":
          description: Successful search
          headers:
            RateLimit-Limit:
              $ref: "#/components/headers/RateLimitLimit"
            RateLimit-Remaining:
              $ref: "#/components/headers/RateLimitRemaining"
            Set-Cookie:
              description: Session cookie
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FlightSearchResponse"
              examples:
                default:
                  $ref: "#/components/examples/FlightSearchResponseExample"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"
      callbacks:
        flightStatusCallback:
          $ref: "#/components/callbacks/FlightStatusCallback"
      security:
        - OAuth2Auth:
            - flight.read
      deprecated: false
      servers:
        - url: https://api.example.com/{version}/flights
          variables:
            version:
              default: v1
security:
  - OAuth2Auth:
      - flight.read
components:
  parameters:
    AcceptLanguage:
      name: Accept-Language
      in: header
      description: Preferred language for response
      schema:
        type: string
    CorrelationId:
      name: X-Correlation-ID
      in: header
      description: Correlation identifier for tracing
      schema:
        type: string
        format: uuid
    PageLimit:
      name: limit
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 100
      description: Page size
    PageOffset:
      name: offset
      in: query
      schema:
        type: integer
        minimum: 0
      description: Pagination offset
    SessionIdCookie:
      name: session_id
      in: cookie
      schema:
        type: string
      description: Session identifier
  schemas:
    IATACode:
      type: string
      pattern: ^[A-Z]{3}$
      description: IATA airport code
      examples:
        - DEN
    FlightSearchResponse:
      type: object
      properties:
        flights:
          type: array
          items:
            $ref: "#/components/schemas/Flight"
        pagination:
          type: object
          properties:
            limit:
              type: integer
            offset:
              type: integer
            total:
              type: integer
      required:
        - flights
    Flight:
      type: object
      properties:
        id:
          type: string
          format: uuid
        airline:
          type: string
        flightNumber:
          type: string
        origin:
          $ref: "#/components/schemas/Airport"
        destination:
          $ref: "#/components/schemas/Airport"
        departureTime:
          type: string
          format: date-time
        arrivalTime:
          type: string
          format: date-time
        durationMinutes:
          type: integer
          minimum: 0
        aircraft:
          type: string
        seatsAvailable:
          type: integer
      required:
        - id
        - airline
        - flightNumber
        - origin
        - destination
        - departureTime
        - arrivalTime
      example:
        id: f7d5d7c8-9b3e-4a0e-93e0-3bb08f75df0f
        airline: Example Air
        flightNumber: EA123
        origin:
          code: DEN
          name: Denver International Airport
          city: Denver
          country: USA
        destination:
          code: LAX
          name: Los Angeles International Airport
          city: Los Angeles
          country: USA
        departureTime: 2025-06-01T08:00:00Z
        arrivalTime: 2025-06-01T10:00:00Z
        durationMinutes: 120
        aircraft: Boeing 737
        seatsAvailable: 42
    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
        details:
          type: array
          items:
            type: string
      required:
        - code
        - message
    FlightStatusUpdate:
      type: object
      properties:
        flightId:
          type: string
          format: uuid
        status:
          type: string
          enum:
            - scheduled
            - boarding
            - departed
            - delayed
            - arrived
            - cancelled
        timestamp:
          type: string
          format: date-time
      required:
        - flightId
        - status
        - timestamp
    Airport:
      type: object
      properties:
        code:
          $ref: "#/components/schemas/IATACode"
        name:
          type: string
        city:
          type: string
        country:
          type: string
  headers:
    RateLimitLimit:
      description: The number of allowed requests in the current period
      schema:
        type: integer
    RateLimitRemaining:
      description: The number of remaining requests in the current period
      schema:
        type: integer
  examples:
    FlightSearchResponseExample:
      summary: Example flight search response
      value:
        flights:
          - id: f7d5d7c8-9b3e-4a0e-93e0-3bb08f75df0f
            airline: Example Air
            flightNumber: EA123
            origin:
              code: DEN
              name: Denver International Airport
              city: Denver
              country: USA
            destination:
              code: LAX
              name: Los Angeles International Airport
              city: Los Angeles
              country: USA
            departureTime: 2025-06-01T08:00:00Z
            arrivalTime: 2025-06-01T10:00:00Z
            durationMinutes: 120
            aircraft: Boeing 737
            seatsAvailable: 42
        pagination:
          limit: 10
          offset: 0
          total: 1
  responses:
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
  callbacks:
    FlightStatusCallback:
      "{$request.body#/callbackUrl}":
        post:
          summary: Flight status update
          requestBody:
            required: true
            content:
              application/json:
                schema:
                  $ref: "#/components/schemas/FlightStatusUpdate"
          responses:
            "204":
              description: Received
  securitySchemes:
    OAuth2Auth:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://example.com/oauth/authorize
          tokenUrl: https://example.com/oauth/token
          scopes:
            flight.read: Read flight data
            flight.write: Modify flight data
        clientCredentials:
          tokenUrl: https://example.com/oauth/token
          scopes:
            flight.admin: Administrative access
        implicit:
          authorizationUrl: https://example.com/oauth/authorize
          scopes:
            flight.read: Read flight data
        password:
          tokenUrl: https://example.com/oauth/token
          scopes:
            flight.read: Read flight data
            flight.write: Modify flight data
```