List conversations
GET /v1/ai/conversations/:tripId Get all AI conversations for a specific trip.
Request Authentication: Required (JWT token)Headers:
Authorization: Bearer <token>
Path parameters: Trip ID to retrieve conversations for
Response Array of conversations User ID who created the conversation
Conversation title (e.g., “Flights assistant”, “Transit assistant”)
Error message if ok is false
Example request curl http://localhost:8080/v1/ai/conversations/trip_abc123 \ -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
Example response { "ok" : true , "data" : [ { "id" : "conv_xyz789" , "tripId" : "trip_abc123" , "userId" : "user_456" , "title" : "Flights assistant" , "createdAt" : "2026-03-01T10:00:00Z" , "updatedAt" : "2026-03-02T14:30:00Z" }, { "id" : "conv_def456" , "tripId" : "trip_abc123" , "userId" : "user_456" , "title" : "Transit assistant" , "createdAt" : "2026-03-02T12:00:00Z" , "updatedAt" : "2026-03-02T13:15:00Z" } ] }
Error responses Status codes:
403 - Unauthorized trip access (user is not a trip member)500 - Internal server error
List messages
GET /v1/ai/conversations/:conversationId/messages Get chat messages for a specific conversation.
Request Authentication: Required (JWT token)Headers:
Authorization: Bearer <token>
Path parameters: Conversation ID to retrieve messages for
Query parameters: Maximum number of messages to return (1-200)
Response Array of messages (ordered by creation time) Associated conversation ID
Message role: "user" or "assistant"
AI model used (for assistant messages)
Token usage statistics for assistant messages
Error message if ok is false
Example request curl "http://localhost:8080/v1/ai/conversations/conv_xyz789/messages?limit=20" \ -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
Example response { "ok" : true , "data" : [ { "id" : "msg_001" , "conversationId" : "conv_xyz789" , "role" : "user" , "content" : "What is the status of flight AA123 on 2026-03-15?" , "model" : "" , "tokenUsage" : null , "createdAt" : "2026-03-02T14:30:00Z" }, { "id" : "msg_002" , "conversationId" : "conv_xyz789" , "role" : "assistant" , "content" : "Flight AA123 on March 15, 2026 departs from JFK at 8:00 AM and arrives at LAX at 11:30 AM local time." , "model" : "gpt-4o-mini" , "tokenUsage" : { "promptTokens" : 245 , "completionTokens" : 58 , "totalTokens" : 303 }, "createdAt" : "2026-03-02T14:30:05Z" } ] }
Error responses Status codes:
403 - Unauthorized conversation access (conversation does not belong to user)500 - Internal server error
Refresh context
POST /v1/ai/context/refresh Manually refresh context snapshot for a trip page.
Request Authentication: Required (JWT token)Headers:
Content-Type: application/jsonAuthorization: Bearer <token>
Body parameters: Page key (e.g., "flights", "transit", "finance", "itinerary", "overview")
Response Refresh confirmation Show RefreshContextResponse object
ISO 8601 timestamp of refresh
Page key that was refreshed
Error message if ok is false
Example request curl -X POST http://localhost:8080/v1/ai/context/refresh \ -H "Content-Type: application/json" \ -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \ -d '{ "tripId": "trip_abc123", "pageKey": "flights" }'
Example response { "ok" : true , "data" : { "updatedAt" : "2026-03-02T14:45:00Z" , "pageKey" : "flights" } }
Error responses Status codes:
400 - Invalid input (missing tripId or pageKey)403 - Unauthorized trip access500 - Internal server error