---
title: "Book a flight"
url: "https://kongair.terwilligar.com/apis/llm-flight-booking-assistant-1-0-0/versions/76f089d9-b12c-4dd8-a400-e4c611faf544/operations/bookFlight"
---

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

# Book a flight

`POST` `/flights/book`

Operation ID: `bookFlight`

Books a flight and returns booking confirmation.

## Header parameters

- `X-Correlation-ID` (string, uuid, optional) - Correlation identifier for tracing

## Request body (required)

Content types: `application/json`

## Responses

- `201` - Booking created
- `400` - Invalid request
- `401` - Authentication required
- `402` - Payment required
- `409` - Conflict
- `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/book:
    post:
      tags:
        - flights
      summary: Book a flight
      description: |
        Books a flight and returns booking confirmation.
      operationId: bookFlight
      parameters:
        - $ref: "#/components/parameters/CorrelationId"
      requestBody:
        $ref: "#/components/requestBodies/BookingRequestBody"
      responses:
        "201":
          description: Booking created
          headers:
            Location:
              description: URL of the created booking
              schema:
                type: string
                format: uri
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BookingResponse"
              examples:
                default:
                  $ref: "#/components/examples/BookingResponseExample"
          links:
            GetBookingById:
              $ref: "#/components/links/GetBookingById"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "409":
          $ref: "#/components/responses/Conflict"
        "500":
          $ref: "#/components/responses/InternalError"
      security:
        - OAuth2Auth:
            - flight.write
        - ApiKeyAuth: []
      deprecated: false
security:
  - OAuth2Auth:
      - flight.write
  - ApiKeyAuth: []
components:
  parameters:
    CorrelationId:
      name: X-Correlation-ID
      in: header
      description: Correlation identifier for tracing
      schema:
        type: string
        format: uuid
  requestBodies:
    BookingRequestBody:
      description: Booking request body
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/BookingRequest"
  schemas:
    BookingResponse:
      allOf:
        - $ref: "#/components/schemas/BookingRequest"
        - type: object
          properties:
            bookingId:
              type: string
              format: uuid
            status:
              type: string
              enum:
                - pending
                - confirmed
                - cancelled
            totalPrice:
              $ref: "#/components/schemas/Price"
          required:
            - bookingId
            - status
    BookingRequest:
      type: object
      properties:
        flightId:
          type: string
          format: uuid
        passengers:
          type: array
          items:
            $ref: "#/components/schemas/Passenger"
        payment:
          $ref: "#/components/schemas/PaymentMethod"
      required:
        - flightId
        - passengers
        - payment
    Price:
      type: object
      properties:
        amount:
          type: number
          format: float
        currency:
          type: string
          pattern: ^[A-Z]{3}$
      required:
        - amount
        - currency
    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
        details:
          type: array
          items:
            type: string
      required:
        - code
        - message
    Passenger:
      type: object
      properties:
        firstName:
          type: string
        lastName:
          type: string
        dateOfBirth:
          type: string
          format: date
        passportNumber:
          type: string
        nationality:
          type: string
      required:
        - firstName
        - lastName
        - dateOfBirth
    PaymentMethod:
      type: object
      discriminator:
        propertyName: type
      oneOf:
        - $ref: "#/components/schemas/CreditCard"
        - $ref: "#/components/schemas/PayPal"
    CreditCard:
      type: object
      properties:
        type:
          type: string
          enum:
            - credit_card
        cardNumber:
          type: string
        expiryMonth:
          type: integer
          minimum: 1
          maximum: 12
        expiryYear:
          type: integer
          minimum: 2025
        cvv:
          type: string
      required:
        - type
        - cardNumber
        - expiryMonth
        - expiryYear
        - cvv
    PayPal:
      type: object
      properties:
        type:
          type: string
          enum:
            - paypal
        email:
          type: string
          format: email
      required:
        - type
        - email
  examples:
    BookingResponseExample:
      summary: Example booking response
      value:
        bookingId: b1234567-89ab-cdef-0123-456789abcdef
        flightId: f7d5d7c8-9b3e-4a0e-93e0-3bb08f75df0f
        passengers:
          - firstName: John
            lastName: Doe
            dateOfBirth: 1990-01-01
        status: confirmed
        totalPrice:
          amount: 199.99
          currency: USD
  links:
    GetBookingById:
      operationId: getBooking
      parameters:
        bookingId: $response.body#/bookingId
      description: Get the newly created booking using its ID
  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"
    PaymentRequired:
      description: Payment required
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    Conflict:
      description: Conflict
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
  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
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
```