Skip to main content

Chat with trip planner

POST /v1/ai/planner/chat

Conversational AI assistant for drafting trip plans from user preferences.

Request

Authentication: Required (JWT token) Headers:
  • Content-Type: application/json
  • Authorization: Bearer <token>
Body parameters:
messages
array
required
Array of conversation messages
plannerContext
object
Planner-specific context
refresh
boolean
default:"false"
Reserved for future use

Response

ok
boolean
required
Request success status
data
object
Planner response data
error
string
Error message if ok is false

Example request

curl -X POST http://localhost:8080/v1/ai/planner/chat \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "I want to visit Paris for 5 days in April with my partner. We love museums and cafes."
      }
    ],
    "plannerContext": {
      "destination": "Paris",
      "travelers": 2,
      "mustDoExperiences": "Louvre Museum, Eiffel Tower, local cafes"
    }
  }'

Example response

{
  "ok": true,
  "data": {
    "answer": "I can help build a 5-day Paris itinerary focused on museums and cafe culture. I recommend allocating Day 1 for the Louvre (book ahead), Day 2 for Musée d'Orsay and Left Bank cafes, Day 3 for Montmartre and local bistros, Day 4 for Eiffel Tower and Seine walk, and Day 5 for Versailles day trip. Budget around €150-200 per person per day for mid-range accommodations, meals, and attractions. Would you like me to expand on any specific days or add more detail to the activities?",
    "sources": [
      {
        "name": "planner_context",
        "status": "ok",
        "fetchedAt": "2026-03-02T14:35:00Z"
      }
    ],
    "degraded": false,
    "plannerDraft": {
      "destination": "Paris",
      "country": "",
      "cities": ["Paris"],
      "startDate": "",
      "endDate": "",
      "travelers": 2,
      "budgetTotal": 0,
      "activities": [
        "Louvre Museum",
        "Eiffel Tower",
        "local cafes"
      ],
      "itinerary": [
        {
          "dayIndex": 1,
          "title": "Louvre Museum",
          "timeBlock": "afternoon",
          "category": "activities",
          "notes": "Drafted by Agent planner conversation."
        },
        {
          "dayIndex": 2,
          "title": "Eiffel Tower",
          "timeBlock": "afternoon",
          "category": "activities",
          "notes": "Drafted by Agent planner conversation."
        },
        {
          "dayIndex": 3,
          "title": "local cafes",
          "timeBlock": "afternoon",
          "category": "activities",
          "notes": "Drafted by Agent planner conversation."
        }
      ]
    }
  }
}

Example request (follow-up)

curl -X POST http://localhost:8080/v1/ai/planner/chat \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "I want to visit Paris for 5 days in April with my partner."
      },
      {
        "role": "assistant",
        "content": "Great choice! Paris in April is lovely. What are your must-do experiences?"
      },
      {
        "role": "user",
        "content": "Louvre, Eiffel Tower, and trying authentic French pastries. Budget is around $3000 total."
      }
    ],
    "plannerContext": {
      "destination": "Paris",
      "travelers": 2,
      "mustDoExperiences": "Louvre, Eiffel Tower, French pastries"
    }
  }'

Draft extraction logic

The plannerDraft object is extracted from:
  • plannerContext fields
  • User messages (regex patterns for dates, traveler count, budget)
  • Assistant response analysis
Returns null if no meaningful trip data is detected.

Error responses

ok
boolean
false when error occurs
error
string
Error description
Status codes:
  • 400 - Invalid input (missing messages)
  • 500 - Internal server error

Build docs developers (and LLMs) love