{"openapi":"3.0.3","info":{"title":"SkyRoute Travel API","description":"AI-powered flight booking API for SkyRoute airlines. Search for flights, create bookings, check booking status, and manage cancellations.","version":"1.0.0","contact":{"name":"SkyRoute Support","email":"support@l6l.studio"}},"servers":[{"url":"https://a2a-demo-skyroute.l6l.studio","description":"API server"}],"security":[{"apiKey":[]}],"paths":{"/api/flights/search":{"post":{"operationId":"searchFlights","summary":"Search for available flights","description":"Search for flights between two cities on a specific date. Returns a list of available flights with prices, times, and seat availability.","tags":["Flights"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["from","to","date"],"properties":{"from":{"type":"string","description":"Departure city or airport code (e.g., 'New York', 'NYC', 'JFK')","example":"New York"},"to":{"type":"string","description":"Destination city or airport code (e.g., 'Los Angeles', 'LAX')","example":"Los Angeles"},"date":{"type":"string","format":"date","description":"Travel date in YYYY-MM-DD format","example":"2026-03-15"}}}}}},"responses":{"200":{"description":"List of available flights","content":{"application/json":{"schema":{"type":"object","properties":{"flights":{"type":"array","items":{"$ref":"#/components/schemas/Flight"}}}}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/flights/{id}":{"get":{"operationId":"getFlightDetails","summary":"Get flight details","description":"Retrieve detailed information about a specific flight by its ID.","tags":["Flights"],"parameters":[{"name":"id","in":"path","required":true,"description":"The unique flight ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Flight details","content":{"application/json":{"schema":{"type":"object","properties":{"flight":{"$ref":"#/components/schemas/Flight"}}}}}},"404":{"description":"Flight not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/bookings":{"get":{"operationId":"listBookings","summary":"List all bookings","description":"Retrieve a list of all bookings. Requires authentication.","tags":["Bookings"],"responses":{"200":{"description":"List of bookings","content":{"application/json":{"schema":{"type":"object","properties":{"bookings":{"type":"array","items":{"$ref":"#/components/schemas/Booking"}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createBooking","summary":"Create a new booking","description":"Book a flight for a passenger. Requires the flight ID from a search result and passenger details.","tags":["Bookings"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["flightId","passengerName","passengerEmail"],"properties":{"flightId":{"type":"string","description":"The ID of the flight to book (from searchFlights response)"},"passengerName":{"type":"string","description":"Full name of the passenger as it appears on their ID","example":"John Smith"},"passengerEmail":{"type":"string","format":"email","description":"Email address for booking confirmation","example":"john.smith@example.com"}}}}}},"responses":{"200":{"description":"Booking created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"booking":{"$ref":"#/components/schemas/Booking"}}}}}},"400":{"description":"Invalid request or no seats available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Flight not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/bookings/{id}":{"get":{"operationId":"getBooking","summary":"Get booking details","description":"Retrieve details of a specific booking by ID or reference code.","tags":["Bookings"],"parameters":[{"name":"id","in":"path","required":true,"description":"The booking ID or reference code (e.g., 'SR-ABC123')","schema":{"type":"string"}}],"responses":{"200":{"description":"Booking details","content":{"application/json":{"schema":{"type":"object","properties":{"booking":{"$ref":"#/components/schemas/Booking"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Booking not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"cancelBooking","summary":"Cancel a booking","description":"Cancel an existing booking. Only confirmed bookings can be cancelled. This action cannot be undone.","tags":["Bookings"],"parameters":[{"name":"id","in":"path","required":true,"description":"The booking ID or reference code to cancel","schema":{"type":"string"}}],"responses":{"200":{"description":"Booking cancelled successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Booking cancelled successfully"}}}}}},"400":{"description":"Booking cannot be cancelled (already cancelled or completed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Booking not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"x-api-key","description":"API key for authentication"}},"schemas":{"Flight":{"type":"object","properties":{"id":{"type":"string","description":"Unique flight identifier"},"flightNumber":{"type":"string","description":"Flight number (e.g., 'SR705')","example":"SR705"},"fromCity":{"type":"string","description":"Departure city name","example":"New York"},"fromCode":{"type":"string","description":"Departure airport code","example":"JFK"},"toCity":{"type":"string","description":"Destination city name","example":"Los Angeles"},"toCode":{"type":"string","description":"Destination airport code","example":"LAX"},"departureTime":{"type":"string","format":"date-time","description":"Departure date and time in ISO 8601 format"},"arrivalTime":{"type":"string","format":"date-time","description":"Arrival date and time in ISO 8601 format"},"price":{"type":"number","description":"Ticket price in USD","example":299.99},"currency":{"type":"string","description":"Currency code","example":"USD"},"airline":{"type":"string","description":"Airline name","example":"SkyRoute Air"},"aircraft":{"type":"string","description":"Aircraft type","example":"Boeing 737-800"},"seatsAvailable":{"type":"integer","description":"Number of available seats","example":42}}},"Booking":{"type":"object","properties":{"id":{"type":"string","description":"Unique booking identifier"},"referenceCode":{"type":"string","description":"Human-readable booking reference code","example":"SR-ABC123"},"passengerName":{"type":"string","description":"Name of the passenger"},"passengerEmail":{"type":"string","description":"Email of the passenger"},"status":{"type":"string","enum":["PENDING","CONFIRMED","CANCELLED","COMPLETED"],"description":"Current booking status"},"totalPrice":{"type":"number","description":"Total booking price"},"createdAt":{"type":"string","format":"date-time","description":"Booking creation timestamp"},"flight":{"$ref":"#/components/schemas/Flight"}}},"Error":{"type":"object","properties":{"error":{"type":"string","description":"Error message"}}}}}}