You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Note. It is a bit rich in context compared to Petstore. This OAS docs has bit of some of the components I find important to add. Please advice. Companion specs will be generated after this one is settled.
openapi: 3.2.0info:
title: Flights APIsummary: A sample Flights API to replace the Swagger Petstoredescription: | The **Flights API** is a reference API for demonstrating OpenAPI 3.2 features and [Arazzo](https://spec.openapis.org/arazzo/v1.0.1.html) workflow orchestration. It provides operations for searching flights, checking real-time status, managing bookings, rebooking cancelled flights, and passenger management. ### Arazzo Workflow Support This API is designed to be consumed by an Arazzo description that models the *"check flight status → rebook if cancelled"* workflow. Key `operationId` values are stable contracts for workflow step references. ### Authentication Use the `api_key` header or OAuth 2.0 bearer token for authenticated endpoints. For testing, you can use the API key `demo-key-flights-2026`.version: 1.0.0termsOfService: https://flights-api.example.com/termscontact:
name: Flights API Teamemail: api-team@flights-api.example.comurl: https://flights-api.example.com/supportlicense:
name: Apache 2.0url: https://www.apache.org/licenses/LICENSE-2.0.htmlexternalDocs:
description: Flights API Developer Portalurl: https://flights-api.example.com/docsservers:
- url: https://api.flights-api.example.com/v1description: Production
- url: https://sandbox.flights-api.example.com/v1description: Sandbox – free to experiment, data resets nightlytags:
- name: flightssummary: Flightsdescription: Search for flights and retrieve real-time flight status.externalDocs:
description: Flight data sourcesurl: https://flights-api.example.com/docs/flights
- name: bookingssummary: Bookingsdescription: Create, retrieve, cancel, and rebook flight bookings.externalDocs:
description: Booking lifecycle guideurl: https://flights-api.example.com/docs/bookings
- name: passengerssummary: Passengersdescription: Manage passenger profiles and retrieve passenger details.externalDocs:
description: Passenger data guideurl: https://flights-api.example.com/docs/passengers# ---------------------------------------------------------------------------# Paths# ---------------------------------------------------------------------------paths:
# ==========================================================================# Flights# ==========================================================================/flights:
get:
operationId: searchFlightstags:
- flightssummary: Search flightsdescription: | Search for available flights by origin, destination, and departure date. Returns a paginated list of matching flights.parameters:
- $ref: '#/components/parameters/OriginQuery'
- $ref: '#/components/parameters/DestinationQuery'
- $ref: '#/components/parameters/DepartureDateQuery'
- $ref: '#/components/parameters/LimitQuery'
- $ref: '#/components/parameters/OffsetQuery'responses:
'200':
description: A paginated list of flights matching the search criteria.content:
application/json:
schema:
$ref: '#/components/schemas/FlightSearchResults'examples:
twoFlights:
$ref: '#/components/examples/FlightSearchResultsExample''400':
$ref: '#/components/responses/BadRequest''500':
$ref: '#/components/responses/InternalServerError'security:
- api_key: []
- oauth2: [read:flights]/flights/{flightId}:
get:
operationId: getFlightByIdtags:
- flightssummary: Get flight detailsdescription: Retrieve full details for a specific flight by its unique identifier.parameters:
- $ref: '#/components/parameters/FlightIdPath'responses:
'200':
description: Flight details.content:
application/json:
schema:
$ref: '#/components/schemas/Flight'examples:
scheduledFlight:
$ref: '#/components/examples/FlightScheduledExample'cancelledFlight:
$ref: '#/components/examples/FlightCancelledExample''400':
$ref: '#/components/responses/BadRequest''404':
$ref: '#/components/responses/NotFound''500':
$ref: '#/components/responses/InternalServerError'security:
- api_key: []
- oauth2: [read:flights]/flights/{flightId}/status:
get:
operationId: getFlightStatustags:
- flightssummary: Get flight statusdescription: | Retrieve the real-time status of a specific flight. This is the primary entry point for the Arazzo *check-and-rebook* workflow.parameters:
- $ref: '#/components/parameters/FlightIdPath'responses:
'200':
description: Current flight status.content:
application/json:
schema:
$ref: '#/components/schemas/FlightStatus'examples:
onTime:
$ref: '#/components/examples/FlightStatusOnTimeExample'cancelled:
$ref: '#/components/examples/FlightStatusCancelledExample'delayed:
$ref: '#/components/examples/FlightStatusDelayedExample''404':
$ref: '#/components/responses/NotFound''500':
$ref: '#/components/responses/InternalServerError'security:
- api_key: []
- oauth2: [read:flights]# ==========================================================================# Bookings# ==========================================================================/bookings:
post:
operationId: createBookingtags:
- bookingssummary: Create a bookingdescription: | Book one or more passengers on a specific flight. Returns the newly created booking with a confirmation number.requestBody:
$ref: '#/components/requestBodies/CreateBookingBody'responses:
'201':
description: Booking created successfully.content:
application/json:
schema:
$ref: '#/components/schemas/Booking'examples:
newBooking:
$ref: '#/components/examples/BookingConfirmedExample''400':
$ref: '#/components/responses/BadRequest''404':
$ref: '#/components/responses/NotFound''500':
$ref: '#/components/responses/InternalServerError'security:
- oauth2: [write:bookings]/bookings/{bookingId}:
get:
operationId: getBookingByIdtags:
- bookingssummary: Get booking detailsdescription: Retrieve a booking by its unique identifier or confirmation number.parameters:
- $ref: '#/components/parameters/BookingIdPath'responses:
'200':
description: Booking details.content:
application/json:
schema:
$ref: '#/components/schemas/Booking'examples:
confirmedBooking:
$ref: '#/components/examples/BookingConfirmedExample''404':
$ref: '#/components/responses/NotFound''500':
$ref: '#/components/responses/InternalServerError'security:
- api_key: []
- oauth2: [read:bookings]delete:
operationId: cancelBookingtags:
- bookingssummary: Cancel a bookingdescription: | Cancel an existing booking. The booking status transitions to `cancelled`. Cancellation policies and refund eligibility depend on fare class.parameters:
- $ref: '#/components/parameters/BookingIdPath'responses:
'200':
description: Booking cancelled successfully.content:
application/json:
schema:
$ref: '#/components/schemas/Booking'examples:
cancelledBooking:
$ref: '#/components/examples/BookingCancelledExample''400':
$ref: '#/components/responses/BadRequest''404':
$ref: '#/components/responses/NotFound''500':
$ref: '#/components/responses/InternalServerError'security:
- oauth2: [write:bookings]/bookings/{bookingId}/rebook:
post:
operationId: rebookFlighttags:
- bookingssummary: Rebook a cancelled or disrupted flightdescription: | Rebook passengers from a cancelled or disrupted flight onto an alternative flight. The original booking must have a status of `cancelled` or be linked to a flight whose status is `cancelled` or `diverted`. This is the second step in the Arazzo *check-and-rebook* workflow.parameters:
- $ref: '#/components/parameters/BookingIdPath'requestBody:
$ref: '#/components/requestBodies/RebookBody'responses:
'201':
description: Rebooked successfully – new booking created.content:
application/json:
schema:
$ref: '#/components/schemas/Booking'examples:
rebookedBooking:
$ref: '#/components/examples/BookingRebookedExample''400':
$ref: '#/components/responses/BadRequest''404':
$ref: '#/components/responses/NotFound''500':
$ref: '#/components/responses/InternalServerError'security:
- oauth2: [write:bookings]/bookings/{bookingId}/payment:
post:
operationId: processPaymenttags:
- bookingssummary: Process payment for a bookingdescription: | Submit payment for an unpaid or partially paid booking. Supports credit card and voucher payment methods.parameters:
- $ref: '#/components/parameters/BookingIdPath'requestBody:
$ref: '#/components/requestBodies/PaymentBody'responses:
'200':
description: Payment processed successfully.content:
application/json:
schema:
$ref: '#/components/schemas/PaymentReceipt'examples:
paidReceipt:
$ref: '#/components/examples/PaymentReceiptExample''400':
$ref: '#/components/responses/BadRequest''404':
$ref: '#/components/responses/NotFound''500':
$ref: '#/components/responses/InternalServerError'security:
- oauth2: [write:bookings]# ==========================================================================# Passengers# ==========================================================================/passengers:
post:
operationId: createPassengertags:
- passengerssummary: Create a passenger profiledescription: Register a new passenger profile for use in bookings.requestBody:
$ref: '#/components/requestBodies/CreatePassengerBody'responses:
'201':
description: Passenger profile created.content:
application/json:
schema:
$ref: '#/components/schemas/Passenger'examples:
newPassenger:
$ref: '#/components/examples/PassengerExample''400':
$ref: '#/components/responses/BadRequest''500':
$ref: '#/components/responses/InternalServerError'security:
- oauth2: [write:passengers]/passengers/{passengerId}:
get:
operationId: getPassengerByIdtags:
- passengerssummary: Get passenger detailsdescription: Retrieve a passenger profile by its unique identifier.parameters:
- $ref: '#/components/parameters/PassengerIdPath'responses:
'200':
description: Passenger profile.content:
application/json:
schema:
$ref: '#/components/schemas/Passenger'examples:
existingPassenger:
$ref: '#/components/examples/PassengerExample''404':
$ref: '#/components/responses/NotFound''500':
$ref: '#/components/responses/InternalServerError'security:
- api_key: []
- oauth2: [read:passengers]put:
operationId: updatePassengertags:
- passengerssummary: Update a passenger profiledescription: Replace an existing passenger profile with the provided data.parameters:
- $ref: '#/components/parameters/PassengerIdPath'requestBody:
$ref: '#/components/requestBodies/CreatePassengerBody'responses:
'200':
description: Passenger profile updated.content:
application/json:
schema:
$ref: '#/components/schemas/Passenger'examples:
updatedPassenger:
$ref: '#/components/examples/PassengerExample''400':
$ref: '#/components/responses/BadRequest''404':
$ref: '#/components/responses/NotFound''500':
$ref: '#/components/responses/InternalServerError'security:
- oauth2: [write:passengers]delete:
operationId: deletePassengertags:
- passengerssummary: Delete a passenger profiledescription: | Remove a passenger profile. Existing bookings referencing this passenger are not affected.parameters:
- $ref: '#/components/parameters/PassengerIdPath'responses:
'200':
description: Passenger profile deleted.content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'examples:
deleted:
summary: Passenger deletedvalue:
code: 200type: successmessage: Passenger pax-101 deleted successfully'404':
$ref: '#/components/responses/NotFound''500':
$ref: '#/components/responses/InternalServerError'security:
- oauth2: [write:passengers]# ---------------------------------------------------------------------------# Components# ---------------------------------------------------------------------------components:
# ==========================================================================# Schemas# ==========================================================================schemas:
# --- Core domain objects ------------------------------------------------Flight:
type: objectdescription: A commercial flight between two airports, including schedule, status, aircraft assignment, and available fare classes.required:
- flightId
- flightNumber
- airline
- origin
- destination
- scheduledDeparture
- scheduledArrival
- statusproperties:
flightId:
type: stringdescription: Unique flight identifier.examples:
- fl-8840flightNumber:
type: stringdescription: IATA flight number.examples:
- DL-1024airline:
$ref: '#/components/schemas/Airline'origin:
$ref: '#/components/schemas/Airport'destination:
$ref: '#/components/schemas/Airport'scheduledDeparture:
type: stringformat: date-timedescription: Scheduled departure time (ISO 8601).examples:
- '2026-06-15T08:30:00Z'scheduledArrival:
type: stringformat: date-timedescription: Scheduled arrival time (ISO 8601).examples:
- '2026-06-15T11:45:00Z'actualDeparture:
type: stringformat: date-timedescription: Actual departure time, if departed.actualArrival:
type: stringformat: date-timedescription: Actual arrival time, if arrived.status:
$ref: '#/components/schemas/FlightStatusEnum'aircraft:
$ref: '#/components/schemas/Aircraft'fareClasses:
type: arraydescription: Available fare classes and pricing.items:
$ref: '#/components/schemas/FareClass'FlightStatus:
type: objectdescription: Real-time operational status of a flight, including delay information, gate assignment, and cancellation details when applicable.required:
- flightId
- flightNumber
- status
- updatedAtproperties:
flightId:
type: stringexamples:
- fl-8840flightNumber:
type: stringexamples:
- DL-1024status:
$ref: '#/components/schemas/FlightStatusEnum'delayMinutes:
type: integerformat: int32description: Delay in minutes (0 if on time, null if cancelled).examples:
- 0cancellationReason:
type: stringdescription: Reason for cancellation, if applicable.examples:
- Severe weather at destination airportgate:
type: stringdescription: Departure gate.examples:
- B42terminal:
type: stringdescription: Departure terminal.examples:
- T-SouthupdatedAt:
type: stringformat: date-timedescription: Timestamp of the last status update.examples:
- '2026-06-15T07:55:00Z'FlightStatusEnum:
type: stringdescription: Current operational status of the flight.enum:
- scheduled
- on_time
- delayed
- boarding
- departed
- in_air
- landed
- arrived
- cancelled
- divertedexamples:
- on_timeFlightSearchResults:
type: objectdescription: Paginated response containing flights matching the search criteria.required:
- data
- paginationproperties:
data:
type: arrayitems:
$ref: '#/components/schemas/Flight'pagination:
$ref: '#/components/schemas/Pagination'Airline:
type: objectdescription: An airline carrier identified by its IATA code and display name.required:
- code
- nameproperties:
code:
type: stringdescription: IATA airline code.examples:
- DLname:
type: stringdescription: Airline display name.examples:
- Delta Air LinesAirport:
type: objectdescription: An airport identified by its IATA code, including city, country, and timezone information.required:
- iataCode
- name
- cityproperties:
iataCode:
type: stringdescription: IATA airport code.examples:
- ATLname:
type: stringdescription: Airport name.examples:
- Hartsfield-Jackson Atlanta International Airportcity:
type: stringexamples:
- Atlantacountry:
type: stringexamples:
- UStimezone:
type: stringdescription: IANA timezone identifier.examples:
- America/New_YorkAircraft:
type: objectdescription: An aircraft assigned to a flight, identified by model and registration number.properties:
model:
type: stringexamples:
- Boeing 737-900ERregistration:
type: stringexamples:
- N801DZFareClass:
type: objectdescription: A fare class representing a cabin tier, booking code, price, and seat availability for a specific flight.required:
- cabin
- code
- priceproperties:
cabin:
type: stringenum:
- economy
- premium_economy
- business
- firstexamples:
- economycode:
type: stringdescription: Fare class letter code.examples:
- Yprice:
$ref: '#/components/schemas/Money'seatsAvailable:
type: integerformat: int32examples:
- 42Money:
type: objectdescription: A monetary amount with its ISO 4217 currency code. Used for pricing, payments, and refunds.required:
- amount
- currencyproperties:
amount:
type: numberformat: doubleexamples:
- 349.99currency:
type: stringdescription: ISO 4217 currency code.examples:
- USD# --- Booking objects ----------------------------------------------------Booking:
type: objectdescription: A flight reservation linking one or more passengers to a specific flight, fare class, and payment. Tracks lifecycle from pending through confirmed, cancelled, rebooked, or completed.required:
- bookingId
- confirmationNumber
- status
- flight
- passengers
- createdAtproperties:
bookingId:
type: stringexamples:
- bk-220401confirmationNumber:
type: stringdescription: Human-readable 6-character confirmation code.examples:
- XKCD42status:
$ref: '#/components/schemas/BookingStatusEnum'flight:
$ref: '#/components/schemas/Flight'passengers:
type: arrayitems:
$ref: '#/components/schemas/Passenger'minItems: 1fareClass:
$ref: '#/components/schemas/FareClass'totalPrice:
$ref: '#/components/schemas/Money'payment:
$ref: '#/components/schemas/PaymentSummary'originalBookingId:
type: stringdescription: Reference to the original booking when this is a rebooking.examples:
- bk-220400createdAt:
type: stringformat: date-timeexamples:
- '2026-06-10T14:22:00Z'updatedAt:
type: stringformat: date-timeBookingStatusEnum:
type: stringdescription: Current status of the booking.enum:
- pending
- confirmed
- cancelled
- rebooked
- completedexamples:
- confirmedCreateBookingRequest:
type: objectdescription: Request payload for creating a new flight booking, specifying the flight, passengers, fare class, and optional seat preferences.required:
- flightId
- passengerIds
- fareClassCodeproperties:
flightId:
type: stringdescription: ID of the flight to book.examples:
- fl-8840passengerIds:
type: arraydescription: List of passenger IDs to include in the booking.items:
type: stringminItems: 1examples:
- - pax-101
- pax-102fareClassCode:
type: stringdescription: Fare class code to book.examples:
- YseatPreferences:
type: arraydescription: Optional seat preference per passenger.items:
$ref: '#/components/schemas/SeatPreference'SeatPreference:
type: objectdescription: A passenger's preferred seat position (window, middle, or aisle) for a booking.properties:
passengerId:
type: stringexamples:
- pax-101preference:
type: stringenum:
- window
- middle
- aisleexamples:
- aisleRebookRequest:
type: objectdescription: Request payload for rebooking passengers from a cancelled or disrupted flight onto an alternative flight.required:
- newFlightIdproperties:
newFlightId:
type: stringdescription: The alternative flight to rebook onto.examples:
- fl-8841fareClassCode:
type: stringdescription: Desired fare class on the new flight. Defaults to the original fare class.examples:
- Yreason:
type: stringdescription: Optional reason or note for the rebooking.examples:
- Original flight DL-1024 cancelled due to weather# --- Payment objects ----------------------------------------------------PaymentRequest:
type: objectdescription: Request payload for processing a payment against a booking. Supports credit card and voucher payment methods.required:
- method
- amountproperties:
method:
type: stringenum:
- credit_card
- voucherexamples:
- credit_cardamount:
$ref: '#/components/schemas/Money'creditCard:
$ref: '#/components/schemas/CreditCard'voucherCode:
type: stringdescription: Voucher code, required when method is `voucher`.examples:
- REBK-CREDIT-5000CreditCard:
type: objectdescription: Credit card details for payment processing. Only the last four digits are stored for security.properties:
lastFourDigits:
type: stringexamples:
- '4242'brand:
type: stringenum:
- visa
- mastercard
- amex
- discoverexamples:
- visaexpiryMonth:
type: integerformat: int32examples:
- 12expiryYear:
type: integerformat: int32examples:
- 2028PaymentSummary:
type: objectdescription: Summary of the payment state for a booking, including the total amount charged and payment method used.properties:
status:
type: stringenum:
- unpaid
- paid
- partially_paid
- refundedexamples:
- paidtotalCharged:
$ref: '#/components/schemas/Money'method:
type: stringexamples:
- credit_cardPaymentReceipt:
type: objectdescription: Confirmation receipt returned after a payment is processed, including the transaction status and timestamp.required:
- receiptId
- bookingId
- status
- amountproperties:
receiptId:
type: stringexamples:
- rcpt-90210bookingId:
type: stringexamples:
- bk-220401status:
type: stringenum:
- success
- failed
- pendingexamples:
- successamount:
$ref: '#/components/schemas/Money'method:
type: stringexamples:
- credit_cardprocessedAt:
type: stringformat: date-timeexamples:
- '2026-06-10T14:25:00Z'# --- Passenger objects --------------------------------------------------Passenger:
type: objectdescription: A passenger profile containing personal details, contact information, and optional loyalty program membership.required:
- passengerId
- firstName
- lastName
- emailproperties:
passengerId:
type: stringexamples:
- pax-101firstName:
type: stringexamples:
- AdalastName:
type: stringexamples:
- Lovelaceemail:
type: stringformat: emailexamples:
- ada.lovelace@example.comphone:
type: stringexamples:
- '+14045551234'dateOfBirth:
type: stringformat: dateexamples:
- '1990-05-15'loyaltyNumber:
type: stringdescription: Frequent flyer / loyalty program number.examples:
- DL-GOLD-99887766createdAt:
type: stringformat: date-timeexamples:
- '2026-01-05T09:00:00Z'CreatePassengerRequest:
type: objectdescription: Request payload for creating or updating a passenger profile. The passengerId is server-generated.required:
- firstName
- lastName
- emailproperties:
firstName:
type: stringexamples:
- AdalastName:
type: stringexamples:
- Lovelaceemail:
type: stringformat: emailexamples:
- ada.lovelace@example.comphone:
type: stringexamples:
- '+14045551234'dateOfBirth:
type: stringformat: dateexamples:
- '1990-05-15'loyaltyNumber:
type: stringexamples:
- DL-GOLD-99887766# --- Shared / utility objects -------------------------------------------Pagination:
type: objectdescription: Pagination metadata for list responses, providing total count and the current offset window.required:
- total
- limit
- offsetproperties:
total:
type: integerformat: int32description: Total number of matching records.examples:
- 42limit:
type: integerformat: int32examples:
- 20offset:
type: integerformat: int32examples:
- 0ApiResponse:
type: objectdescription: Generic API response envelope used for operations that return a status message rather than a domain object.properties:
code:
type: integerformat: int32examples:
- 200type:
type: stringexamples:
- successmessage:
type: stringexamples:
- Operation completed successfullyError:
type: objectdescription: Standardized error response returned for all 4xx and 5xx status codes, with an optional array of field-level details.required:
- code
- type
- messageproperties:
code:
type: integerformat: int32examples:
- 400type:
type: stringexamples:
- validation_errormessage:
type: stringexamples:
- 'Invalid input: flightId is required'details:
type: arraydescription: Optional field-level error details.items:
$ref: '#/components/schemas/ErrorDetail'ErrorDetail:
type: objectdescription: A single field-level validation error identifying which field failed and the specific issue.properties:
field:
type: stringexamples:
- flightIdissue:
type: stringexamples:
- Field is required# ==========================================================================# Parameters# ==========================================================================parameters:
FlightIdPath:
name: flightIdin: pathrequired: truedescription: Unique flight identifier.schema:
type: stringexamples:
default:
summary: A Delta flightvalue: fl-8840BookingIdPath:
name: bookingIdin: pathrequired: truedescription: Unique booking identifier.schema:
type: stringexamples:
default:
summary: A confirmed bookingvalue: bk-220401PassengerIdPath:
name: passengerIdin: pathrequired: truedescription: Unique passenger identifier.schema:
type: stringexamples:
default:
summary: An existing passengervalue: pax-101OriginQuery:
name: originin: queryrequired: truedescription: IATA code of the departure airport.schema:
type: stringexamples:
atlanta:
summary: Atlantavalue: ATLDestinationQuery:
name: destinationin: queryrequired: truedescription: IATA code of the arrival airport.schema:
type: stringexamples:
lax:
summary: Los Angelesvalue: LAXDepartureDateQuery:
name: departureDatein: queryrequired: truedescription: Departure date (ISO 8601 date format).schema:
type: stringformat: dateexamples:
summerDate:
summary: Summer 2026 datevalue: '2026-06-15'LimitQuery:
name: limitin: queryrequired: falsedescription: Maximum number of results to return (default 20, max 100).schema:
type: integerformat: int32default: 20minimum: 1maximum: 100OffsetQuery:
name: offsetin: queryrequired: falsedescription: Number of results to skip for pagination.schema:
type: integerformat: int32default: 0minimum: 0# ==========================================================================# Request Bodies# ==========================================================================requestBodies:
CreateBookingBody:
description: Booking details for the new reservation.required: truecontent:
application/json:
schema:
$ref: '#/components/schemas/CreateBookingRequest'examples:
singlePassenger:
summary: Single passenger bookingvalue:
flightId: fl-8840passengerIds:
- pax-101fareClassCode: YtwoPassengers:
summary: Two passenger booking with seat preferencesvalue:
flightId: fl-8840passengerIds:
- pax-101
- pax-102fareClassCode: YseatPreferences:
- passengerId: pax-101preference: aisle
- passengerId: pax-102preference: windowRebookBody:
description: Details for rebooking onto an alternative flight.required: truecontent:
application/json:
schema:
$ref: '#/components/schemas/RebookRequest'examples:
weatherRebook:
summary: Rebook due to weather cancellationvalue:
newFlightId: fl-8841fareClassCode: Yreason: Original flight DL-1024 cancelled due to weatherPaymentBody:
description: Payment details for the booking.required: truecontent:
application/json:
schema:
$ref: '#/components/schemas/PaymentRequest'examples:
creditCardPayment:
summary: Pay with credit cardvalue:
method: credit_cardamount:
amount: 349.99currency: USDcreditCard:
lastFourDigits: '4242'brand: visaexpiryMonth: 12expiryYear: 2028voucherPayment:
summary: Pay with rebooking vouchervalue:
method: voucheramount:
amount: 349.99currency: USDvoucherCode: REBK-CREDIT-5000CreatePassengerBody:
description: Passenger profile information.required: truecontent:
application/json:
schema:
$ref: '#/components/schemas/CreatePassengerRequest'examples:
newPassenger:
summary: Create passenger profilevalue:
firstName: AdalastName: Lovelaceemail: ada.lovelace@example.comphone: '+14045551234'dateOfBirth: '1990-05-15'loyaltyNumber: DL-GOLD-99887766# ==========================================================================# Responses (reusable error responses)# ==========================================================================responses:
BadRequest:
description: The request is invalid or missing required parameters.content:
application/json:
schema:
$ref: '#/components/schemas/Error'examples:
missingField:
summary: Missing required fieldvalue:
code: 400type: validation_errormessage: 'Invalid input: flightId is required'details:
- field: flightIdissue: Field is requiredNotFound:
description: The requested resource was not found.content:
application/json:
schema:
$ref: '#/components/schemas/Error'examples:
flightNotFound:
summary: Flight not foundvalue:
code: 404type: not_foundmessage: Flight fl-9999 not foundbookingNotFound:
summary: Booking not foundvalue:
code: 404type: not_foundmessage: Booking bk-000000 not foundInternalServerError:
description: An unexpected error occurred on the server.content:
application/json:
schema:
$ref: '#/components/schemas/Error'examples:
serverError:
summary: Internal server errorvalue:
code: 500type: internal_errormessage: An unexpected error occurred. Please try again later.# ==========================================================================# Examples# ==========================================================================examples:
# --- Flight examples ----------------------------------------------------FlightScheduledExample:
summary: A scheduled Delta flight ATL → LAXvalue:
flightId: fl-8840flightNumber: DL-1024airline:
code: DLname: Delta Air Linesorigin:
iataCode: ATLname: Hartsfield-Jackson Atlanta International Airportcity: Atlantacountry: UStimezone: America/New_Yorkdestination:
iataCode: LAXname: Los Angeles International Airportcity: Los Angelescountry: UStimezone: America/Los_AngelesscheduledDeparture: '2026-06-15T08:30:00Z'scheduledArrival: '2026-06-15T11:45:00Z'status: scheduledaircraft:
model: Boeing 737-900ERregistration: N801DZfareClasses:
- cabin: economycode: Yprice:
amount: 349.99currency: USDseatsAvailable: 42
- cabin: businesscode: Jprice:
amount: 1249.00currency: USDseatsAvailable: 8FlightCancelledExample:
summary: A cancelled flightvalue:
flightId: fl-8840flightNumber: DL-1024airline:
code: DLname: Delta Air Linesorigin:
iataCode: ATLname: Hartsfield-Jackson Atlanta International Airportcity: Atlantacountry: UStimezone: America/New_Yorkdestination:
iataCode: LAXname: Los Angeles International Airportcity: Los Angelescountry: UStimezone: America/Los_AngelesscheduledDeparture: '2026-06-15T08:30:00Z'scheduledArrival: '2026-06-15T11:45:00Z'status: cancelledaircraft:
model: Boeing 737-900ERregistration: N801DZFlightSearchResultsExample:
summary: Search results for ATL → LAX on 2026-06-15value:
data:
- flightId: fl-8840flightNumber: DL-1024airline:
code: DLname: Delta Air Linesorigin:
iataCode: ATLname: Hartsfield-Jackson Atlanta International Airportcity: Atlantacountry: USdestination:
iataCode: LAXname: Los Angeles International Airportcity: Los Angelescountry: USscheduledDeparture: '2026-06-15T08:30:00Z'scheduledArrival: '2026-06-15T11:45:00Z'status: scheduledfareClasses:
- cabin: economycode: Yprice:
amount: 349.99currency: USDseatsAvailable: 42
- flightId: fl-8841flightNumber: DL-1028airline:
code: DLname: Delta Air Linesorigin:
iataCode: ATLname: Hartsfield-Jackson Atlanta International Airportcity: Atlantacountry: USdestination:
iataCode: LAXname: Los Angeles International Airportcity: Los Angelescountry: USscheduledDeparture: '2026-06-15T14:00:00Z'scheduledArrival: '2026-06-15T17:15:00Z'status: scheduledfareClasses:
- cabin: economycode: Yprice:
amount: 299.99currency: USDseatsAvailable: 67pagination:
total: 2limit: 20offset: 0# --- Flight status examples ---------------------------------------------FlightStatusOnTimeExample:
summary: Flight is on timevalue:
flightId: fl-8840flightNumber: DL-1024status: on_timedelayMinutes: 0gate: B42terminal: T-SouthupdatedAt: '2026-06-15T07:55:00Z'FlightStatusCancelledExample:
summary: Flight is cancelledvalue:
flightId: fl-8840flightNumber: DL-1024status: cancelleddelayMinutes: nullcancellationReason: Severe weather at destination airportgate: B42terminal: T-SouthupdatedAt: '2026-06-15T06:30:00Z'FlightStatusDelayedExample:
summary: Flight is delayedvalue:
flightId: fl-8840flightNumber: DL-1024status: delayeddelayMinutes: 45gate: B42terminal: T-SouthupdatedAt: '2026-06-15T07:45:00Z'# --- Booking examples ---------------------------------------------------BookingConfirmedExample:
summary: A confirmed bookingvalue:
bookingId: bk-220401confirmationNumber: XKCD42status: confirmedflight:
flightId: fl-8840flightNumber: DL-1024airline:
code: DLname: Delta Air Linesorigin:
iataCode: ATLname: Hartsfield-Jackson Atlanta International Airportcity: Atlantacountry: USdestination:
iataCode: LAXname: Los Angeles International Airportcity: Los Angelescountry: USscheduledDeparture: '2026-06-15T08:30:00Z'scheduledArrival: '2026-06-15T11:45:00Z'status: scheduledpassengers:
- passengerId: pax-101firstName: AdalastName: Lovelaceemail: ada.lovelace@example.comfareClass:
cabin: economycode: Yprice:
amount: 349.99currency: USDtotalPrice:
amount: 349.99currency: USDpayment:
status: paidtotalCharged:
amount: 349.99currency: USDmethod: credit_cardcreatedAt: '2026-06-10T14:22:00Z'BookingCancelledExample:
summary: A cancelled bookingvalue:
bookingId: bk-220401confirmationNumber: XKCD42status: cancelledflight:
flightId: fl-8840flightNumber: DL-1024airline:
code: DLname: Delta Air Linesorigin:
iataCode: ATLname: Hartsfield-Jackson Atlanta International Airportcity: Atlantacountry: USdestination:
iataCode: LAXname: Los Angeles International Airportcity: Los Angelescountry: USscheduledDeparture: '2026-06-15T08:30:00Z'scheduledArrival: '2026-06-15T11:45:00Z'status: cancelledpassengers:
- passengerId: pax-101firstName: AdalastName: Lovelaceemail: ada.lovelace@example.comfareClass:
cabin: economycode: Yprice:
amount: 349.99currency: USDtotalPrice:
amount: 349.99currency: USDpayment:
status: refundedtotalCharged:
amount: 349.99currency: USDmethod: credit_cardcreatedAt: '2026-06-10T14:22:00Z'updatedAt: '2026-06-15T06:35:00Z'BookingRebookedExample:
summary: A rebooked booking (references original)value:
bookingId: bk-220402confirmationNumber: REBK77status: confirmedflight:
flightId: fl-8841flightNumber: DL-1028airline:
code: DLname: Delta Air Linesorigin:
iataCode: ATLname: Hartsfield-Jackson Atlanta International Airportcity: Atlantacountry: USdestination:
iataCode: LAXname: Los Angeles International Airportcity: Los Angelescountry: USscheduledDeparture: '2026-06-15T14:00:00Z'scheduledArrival: '2026-06-15T17:15:00Z'status: scheduledpassengers:
- passengerId: pax-101firstName: AdalastName: Lovelaceemail: ada.lovelace@example.comfareClass:
cabin: economycode: Yprice:
amount: 299.99currency: USDtotalPrice:
amount: 0.00currency: USDpayment:
status: paidtotalCharged:
amount: 0.00currency: USDmethod: voucheroriginalBookingId: bk-220401createdAt: '2026-06-15T06:40:00Z'# --- Payment examples ---------------------------------------------------PaymentReceiptExample:
summary: Successful credit card paymentvalue:
receiptId: rcpt-90210bookingId: bk-220401status: successamount:
amount: 349.99currency: USDmethod: credit_cardprocessedAt: '2026-06-10T14:25:00Z'# --- Passenger examples -------------------------------------------------PassengerExample:
summary: A passenger profilevalue:
passengerId: pax-101firstName: AdalastName: Lovelaceemail: ada.lovelace@example.comphone: '+14045551234'dateOfBirth: '1990-05-15'loyaltyNumber: DL-GOLD-99887766createdAt: '2026-01-05T09:00:00Z'# ==========================================================================# Security Schemes# ==========================================================================securitySchemes:
api_key:
type: apiKeyname: X-API-Keyin: headerdescription: | API key for read-only access. For testing, use `demo-key-flights-2026`.oauth2:
type: oauth2description: OAuth 2.0 with authorization code flow for full access.flows:
authorizationCode:
authorizationUrl: https://auth.flights-api.example.com/authorizetokenUrl: https://auth.flights-api.example.com/tokenscopes:
read:flights: Read flight informationread:bookings: Read booking detailswrite:bookings: Create, cancel, and rebook bookingsread:passengers: Read passenger profileswrite:passengers: Create and manage passenger profiles
reacted with thumbs up emoji reacted with thumbs down emoji reacted with laugh emoji reacted with hooray emoji reacted with confused emoji reacted with heart emoji reacted with rocket emoji reacted with eyes emoji
Uh oh!
There was an error while loading. Please reload this page.
-
Here is my initial stab at this.
Note. It is a bit rich in context compared to Petstore. This OAS docs has bit of some of the components I find important to add. Please advice. Companion specs will be generated after this one is settled.
Beta Was this translation helpful? Give feedback.
All reactions