Wanderbolt.AI API Instructions

Wanderbolt.AI provides a RESTful API for managing your travel agency data programmatically.

Authentication

The API uses JWT (JSON Web Token) for authentication. All requests to the API (except for the login endpoint) must include the JWT token in the Authorization header.

[!NOTE] The API currently supports standard email/password authentication only. Multi-Factor Authentication (MFA) flows are enforced on the web portal but are not yet available via the REST API.

1. Obtain a Token

To get an access token, send a POST request to /api/auth/login with your credentials:

curl -X POST https://www.wanderbolt.ai/api/auth/login \
     -H "Content-Type: application/json" \
     -d '{"email": "[email protected]", "password": "your-password"}'

Response:

{
  "access_token": "your.jwt.token.here"
}

2. Use the Token

Include the token in the headers of your subsequent requests:

curl -X GET https://www.wanderbolt.ai/api/clients/ \
     -H "Authorization: Bearer your.jwt.token.here"

API Documentation (Swagger UI)

You can explore the API and test endpoints using the interactive Swagger UI directly in your browser:

URL: https://www.wanderbolt.ai/api/docs

Core Endpoints

• Auth: /api/auth/
• POST /login: Login and get token.
• Clients: /api/clients/
• GET /: List all clients (includes last_trip, trip_count).
• POST /: Create a new client (Supports split first_name, middle_name, last_name).
• GET /<id>: Get client details (includes ai_insights, last_trip, trip_count).
• GET /<id>/prior-travelers: Get unique travelers used on prior trips for this client.
• POST /<id>/insights/refresh: Force regenerate AI insights for a client.
• PUT /<id>: Update client.
• DELETE /<id>: Delete client.
• Trips: /api/trips/
• GET /: List all trips.
• POST /: Create a new trip.
• GET /<id>: Get deep details (Bookings, Milestones, Itinerary, Travelers).
• PUT /<id>: Update trip.
• DELETE /<id>: Delete trip.
• POST /<trip_id>/bookings: Create a booking for a trip.
• PUT /<trip_id>/bookings/<booking_id>: Update a booking.
• DELETE /<trip_id>/bookings/<booking_id>: Delete a booking (fires booking.deleted webhook).
• Invoices: /api/invoices/
• GET /: List all invoices.
• POST /: Create a new invoice.
• GET /<id>: Get invoice details.
• PUT /<id>: Update invoice.
• DELETE /<id>: Delete invoice.
• Proposals: /api/proposals/
• GET /: List all proposals.
• POST /: Create a new proposal.
• GET /<id>: Get proposal details.
  • Note: Includes nested pages, categories, and items.
• PUT /<id>: Update proposal.
• DELETE /<id>: Delete proposal.
• Suppliers: /api/suppliers/
• GET /: List all suppliers (includes agency-shared and global suppliers).
• POST /: Create a new supplier.
• GET /<id>: Get supplier details (includes agency-shared and global).
  • Fields: agent_login, bdm_name, bdm_email, bdm_phone, is_shared, is_owned, is_global.
• PUT /<id>: Update supplier (owned suppliers only).
• DELETE /<id>: Delete supplier (owned suppliers only).

Note: Agency members see their own suppliers plus shared content from other agency members and global suppliers. Response includes is_shared, is_owned, and is_global fields.

• Vendors: /api/vendors/ (See below for details)
• Reference: /api/reference/
• GET /entity-types: List all booking entity types for dropdowns.
• GET /supplier-types: List all supplier types for dropdowns.
• GET /vendor-types: List all vendor types for dropdowns.
• Calendar: /api/calendar/
• GET /events: List calendar events (trips, bookings, payments) with optional filtering.
• Chat: /chat/
• POST /send: Send a message and receive a streaming SSE response.
• GET /history: Retrieve recent chat message history.
• GET /config: Get chat configuration (enabled status and assistant ID).

Client Response Example

GET /api/clients/1 returns client details with AI insights:

{
  "id": 1,
  "first_name": "Jane",
  "last_name": "Smith",
  "email_primary": "[email protected]",
  "phone": "555-0123",
  "address_line1": "123 Main St",
  "city": "Chicago",
  "state": "IL",
  "zip_code": "60601",
  "client_status": "Active",
  "last_trip": "Paris Anniversary 2025",
  "trip_count": 5,
  "ai_insights": "Frequent luxury traveler with preference for European destinations..."
}

Client Insights Refresh Example

POST /api/clients/1/insights/refresh forces regeneration of AI insights:

{
  "insights": "Based on Jane's recent questionnaire, she prefers..."
}

Client Prior Travelers Response Example

GET /api/clients/1/prior-travelers returns a list of unique travelers with split name fields:

[
  {
    "first_name": "John",
    "middle_name": "Quincy",
    "last_name": "Doe",
    "name": "John Quincy Doe",
    "email": "[email protected]",
    "phone": "555-0199",
    "address": "123 Maple St",
    "dob": "1985-04-12",
    "notes": "Vegetarian meal preference"
  }
]

Enhanced Trip Response Example

Fetching a single trip (GET /api/trips/1) returns a comprehensive object:

{
  "id": 1,
  "title": "Paris Getaway",
  "client_id": 10,
  "destination": "Paris, France",
  "start_date": "2024-06-01",
  "end_date": "2024-06-10",
  "status": "planning",
  "vibe": "Romantic",
  "goals": "Sightseeing",
  "budget_range": "$5k - $7k",
  "bookings": [
    {
      "id": 101,
      "booking_type": "flight",
      "title": "Flight to CDG",
      "booking_date_start": "2024-06-01",
      "booking_date_end": "2024-06-01",
      "date_of_booking": "2024-01-10",
      "final_payment_due_date": "2024-05-01",
      "cost": 1200.0,
      "supplier_id": 5,
      "supplier_name": "Air France",
      "vendor_id": 10,
      "vendor_name": "TripCo",
      "show_on_calendar": true,
      "assigned_agent_id": null,
      "agent_split_override": null,
      "payment_milestones": [
        {
          "id": 501,
          "payment_type": "Deposit",
          "due_date": "2024-01-15",
          "amount_due": 500.0,
          "status": "Paid",
          "paid_date": "2024-01-14",
          "paid_amount": 500.0
        }
      ]
    }
  ],
  "itinerary": {
    "id": 202,
    "title": "Paris Itinerary",
    "days": [
      {
        "id": 305,
        "title": "Day 1",
        "tab_title": "Arrival",
        "body": "Arrive in Paris and check into hotel.",
        "sort_order": 1
      }
    ]
  },
  "travelers": [
    {
      "id": 401,
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "[email protected]"
    }
  ]
}

Enhanced Proposal Response Example

GET /api/proposals/1 returns deep details including categories and items:

{
  "id": 1,
  "title": "Luxury Italy Proposal",
  "status": "Draft",
  "introduction": "Welcome to your dream Italy vacation.",
  "pages": [
    {
      "id": 10,
      "title": "Flights & Lodging",
      "body": "See your options below.",
      "categories": [
        {
          "id": 50,
          "title": "Flights",
          "items": [
            {
              "type": "flight",
              "title": "Emirates First Class",
              "cost": 5000.0,
              "from_date": "2024-06-01",
              "to_date": "2024-06-01",
              "internal_notes": "A380 aircraft confirmed."
            }
          ]
        }
      ]
    }
  ]
}

Supplier Response Example

GET /api/suppliers/1 returns full BDM and login info:

{
  "id": 1,
  "name": "Classic Vacations",
  "supplier_type": "Wholesaler",
  "agent_login": "https://classicvacations.com/agent-login",
  "bdm_name": "Sarah Miller",
  "bdm_email": "[email protected]",
  "bdm_phone": "555-0100",
  "is_preferred": true,
  "commission_type": "percentage",
  "commission_value": 15.0
}

Vendor Response Example

GET /api/vendors/1 returns enhanced support and feedback fields:

{
  "id": 1,
  "name": "Local Tours Italy",
  "vendor_type": "DMC",
  "phone_24_7": "+39 06 1234567",
  "app_info": "Download 'ItalyTours' app for live tracking.",
  "customer_feedback": "Highly recommended for private drivers."
}

• Vendors: /api/vendors/
• GET /: List all vendors.
• POST /: Create a new vendor.
• GET /<id>: Get detailed information.
• PUT /<id>: Update vendor info.
• DELETE /<id>: Delete vendor.
• Knowledge Base: /api/knowledge/
• GET /folders: List all folders (includes agency-shared folders).
• GET /folders/<id>: Get folder details.
• GET /articles: List all articles (includes agency-shared; optional: ?folder_id=<id>).
• GET /articles/<id>: Get article details (content, tags, etc).

Note: Agency members see their own folders/articles plus shared content from other agency members (where is_shared = true). Response includes is_shared and is_owned fields.

• Analytics: /api/analytics/
• GET /: Get dashboard analytics metrics (Trip Status, Trip Volume, Top Destinations).

Analytics Response Example

GET /api/analytics/ returns structured metrics:

{
  "trip_status": {
    "Planning": 5,
    "Booked": 2,
    "Completed": 10
  },
  "trip_volume": {
    "2023-01": 4,
    "2023-02": 3,
    "2023-03": 8
  },
  "top_destinations": {
    "Paris": 12,
    "Tokyo": 8,
    "New York": 5
  }
}

Calendar API Endpoints

The Calendar API provides programmatic access to calendar events for trips, bookings, and payment milestones.

Get Calendar Events

GET /api/calendar/events

Returns FullCalendar-compatible events for the authenticated user.

Query Parameters:

Parameter	Type	Description
start	string	Filter events starting after this date (ISO format)
end	string	Filter events ending before this date (ISO format)
type	string	Filter by type: trip, booking, payment, or all (default)

Response Example:

[
  {
    "id": "trip_1",
    "title": "✈️ Smith - Paris Vacation",
    "start": "2024-06-01",
    "end": "2024-06-10",
    "allDay": true,
    "backgroundColor": "#0d6efd",
    "extendedProps": {
      "type": "trip",
      "destination": "Paris",
      "trip_id": 1,
      "client_name": "Jane Smith",
      "client_email": "[email protected]"
    }
  },
  {
    "id": "booking_101",
    "title": "✈️ Flight to CDG",
    "start": "2024-06-01T08:30:00",
    "end": "2024-06-01T12:45:00",
    "allDay": false,
    "backgroundColor": "#6c757d",
    "extendedProps": {
      "type": "booking",
      "booking_type": "Air",
      "trip_id": 1,
      "booking_id": 101
    }
  },
  {
    "id": "payment_201",
    "title": "💰 Final Payment: Flight to CDG",
    "start": "2024-05-01",
    "end": "2024-05-01",
    "allDay": true,
    "backgroundColor": "#dc3545",
    "extendedProps": {
      "type": "payment",
      "amount": 700.50,
      "booking_title": "Flight to CDG",
      "trip_id": 1
    }
  }
]

Event Types:

• Trips (type: trip): Only trips with status = 'booked' are included.
• Bookings (type: booking): Only bookings with show_on_calendar = true (or null) are included.
• Payments (type: payment): Unpaid payment milestones and booking final payment due dates.

Chat API Endpoints

The Chat API allows for real-time interaction with the Wanderbolt Assistant.

1. Send Message

POST /chat/send

Request Body:

{
  "message": "Find my trip to Paris",
  "context": {
    "url": "/portal/dashboard"
  }
}

Response:

Server-Sent Events (SSE) stream. Each event is a JSON object:

• {"type": "text", "content": "..."}: A chunk of assistant text.
• {"type": "status", "content": "..."}: A status update (e.g., "Searching for trips...").
• {"type": "action", "action": "navigate", "url": "..."}: A navigation instruction for the frontend.
• {"type": "done"}: The end of the stream.

2. Get Chat History

GET /chat/history

Response:

{
  "messages": [
    {
      "role": "user",
      "content": "Hello"
    },
    {
      "role": "assistant",
      "content": "Hi! How can I help you today?"
    }
  ]
}

3. Chat Configuration

GET /chat/config

Response:

{
  "enabled": true,
  "assistant_id": "asst_..."
}