Chat with AI assistant
POST /v1/ai/chat Send messages to the AI assistant with trip and page context.
Request Authentication: Required (JWT token)Headers:
Content-Type: application/jsonAuthorization: Bearer <token>
Body parameters: Trip ID the conversation belongs to
Current page context (e.g., "flights", "transit", "finance", "itinerary", "overview")
Additional page-specific context data
Array of chat messages Message role: "user" or "assistant"
Whether to fetch real-time context (flight status, transit options, etc.)
Response Chat response data AI assistant response text
Array of highlight strings
Array of suggested next actions
Data sources used for response Source name (e.g., "next_flight_status", "trip_db_context")
Source status: "ok", "error", "skipped_missing_inputs"
Additional details or error message
Whether response is degraded due to unavailable real-time data
Error message if ok is false
Example request curl -X POST http://localhost:8080/v1/ai/chat \ -H "Content-Type: application/json" \ -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \ -d '{ "tripId": "trip_abc123", "pageKey": "flights", "pageContext": {}, "messages": [ { "role": "user", "content": "What is the status of flight AA123 on 2026-03-15?" } ], "refresh": true }'
Example response { "ok" : true , "data" : { "conversationId" : "conv_xyz789" , "answer" : "Flight AA123 on March 15, 2026 departs from JFK at 8:00 AM and arrives at LAX at 11:30 AM local time. The flight duration is 6 hours 30 minutes with no stops. Departure is from Terminal 8 Gate 12, and arrival is at Terminal 4 Gate 42." , "highlights" : [ "Read-only guidance generated from current trip context" , "Page-aware reasoning for flights" ], "suggestedActions" : [ "Share exact flight number and date for live status" , "Compare price-time tradeoff before selecting" ], "sources" : [ { "name" : "next_flight_status" , "status" : "ok" , "fetchedAt" : "2026-03-02T14:30:00Z" , "detail" : "" } ], "degraded" : false } }
Example request (transit context) curl -X POST http://localhost:8080/v1/ai/chat \ -H "Content-Type: application/json" \ -H "Authorization: Bearer <token>" \ -d '{ "tripId": "trip_abc123", "pageKey": "transit", "pageContext": {}, "messages": [ { "role": "user", "content": "How do I get from Times Square to Brooklyn Bridge?" } ], "refresh": true }'
Page-aware context The assistant fetches real-time data based on pageKey when refresh is true:
flights/api/flights/statustransit/api/transit/suggestfinanceitineraryoverview
Error responses Status codes:
400 - Invalid input (missing tripId, pageKey, or messages)403 - Unauthorized trip access500 - Internal server error