API Documentation

Flight Search

Search flights across multiple providers with comprehensive filtering options.

Request Body:

{
  "origin": "LOS",              // Required: 3-letter airport code
  "destination": "DXB",         // Required: 3-letter airport code
  "departure_date": "2026-04-01", // Required: YYYY-MM-DD
  "return_date": "2026-04-10",   // Optional: YYYY-MM-DD
  "adults": 1,                   // Required: Number of adults
  "children": 0,                 // Optional: Number of children
  "infants": 0,                  // Optional: Number of infants
  "cabin_class": "economy"       // Optional: economy|premium|business|first
}

Response:

{
  "success": true,
  "data": {
    "offers": [...],
    "metadata": {
      "total_results": 45,
      "providers": ["duffel", "tbo", "travuafrica"]
    }
  }
}

AI-Powered Search

Natural language flight search powered by OpenAI.

Request Body:

{
  "query": "I want to fly from Lagos to Dubai next Friday in business class"
}

Response:

{
  "success": true,
  "data": {
    "parsed_query": {
      "origin": "LOS",
      "destination": "DXB",
      "departure_date": "2026-03-28",
      "cabin_class": "business"
    },
    "offers": [...]
  }
}

Create Booking

Create a new flight booking with passenger details.

Request Body:

{
  "provider": "duffel",
  "offer_id": "off_123456",
  "total_amount": 450000,
  "passengers": [
    {
      "passenger_type": "adult",
      "first_name": "John",
      "last_name": "Doe",
      "date_of_birth": "1990-01-15",
      "email": "john@example.com",
      "phone": "+2348012345678",
      "passport_number": "A12345678",
      "nationality": "NG"
    }
  ]
}

Response:

{
  "success": true,
  "data": {
    "booking": {
      "booking_reference": "SKY-FLT-123456",
      "status": "confirmed",
      "total_amount": 450000,
      "token_reward": 2250
    }
  }
}

Price Prediction

Get ML-powered price forecasts and booking recommendations.

Request Body:

{
  "route": "LOS-DXB",
  "departure_date": "2026-04-01",
  "cabin_class": "economy"
}

Response:

{
  "success": true,
  "data": {
    "current_price": 350000,
    "predicted_price": 365000,
    "confidence": 0.82,
    "trend": "increasing",
    "recommendation": "book_now"
  }
}

Booking History

Retrieve user's booking history.

Response:

{
  "success": true,
  "data": {
    "bookings": [
      {
        "booking_reference": "SKY-FLT-123456",
        "status": "confirmed",
        "origin": "LOS",
        "destination": "DXB",
        "departure_date": "2026-04-01",
        "total_amount": 450000
      }
    ]
  }
}

Cancel Booking

Cancel an existing booking and process refund.

Response:

{
  "success": true,
  "data": {
    "status": "cancelled",
    "refund_amount": 405000,
    "cancellation_fee": 45000,
    "message": "Booking cancelled and refund processed to wallet"
  }
}