---
title: "Conversational property search"
method: POST
path: "/chat"
---

# Conversational property search

`POST /chat`

## Request

- Base URL: `https://api.tellandgo.com/api/v1/agent`
- URL: `https://api.tellandgo.com/api/v1/agent/chat`
- Auth: API key in header `X-API-Key`

Multi-turn conversational search with preference extraction and follow-up questions.
Maintains session context across turns for increasingly refined recommendations.

## Request body

- ChatRequest
  - `message` string, required: User message
  - `session_id` string: Session ID for multi-turn conversations
  - `context` object
    - `previous_searches` string[]
    - `selected_properties` string[]
    - `collected_preferences` object
      - `travel_style` string[]
      - `interests` string[]
      - `budget` object
        - `min` number
        - `max` number
      - `dates` object
        - `check_in` string, date
        - `check_out` string, date
      - `destination` string
      - `guests` object
        - `adults` integer
        - `children` integer[]
  - `include_pricing` boolean
  - `max_properties` integer

## Response `200`

Chat response with optional property recommendations

- ChatResponse
  - `success` boolean
  - `response` object
    - `text` string: Chat response text
    - `intent` 'greeting' | 'search' | 'recommendation' | 'comparison' | 'clarification' | 'booking_intent' | 'general_info' | 'farewell' | 'narrowing'
    - `confidence` number
    - `extracted_preferences` object
      - `destination` string
      - `dates` object
        - `check_in` string
        - `check_out` string
      - `budget` object
        - `min` number
        - `max` number
      - `interests` string[]
  - `properties` PropertyResult[]
    - `id` string
    - `name` string
    - `slug` string
    - `location` object
      - `country` string
      - `area` string
      - `coordinates` object
        - `lat` number
        - `lng` number
    - `pricing` object
      - `price_per_night` number
      - `total_price` number
      - `currency` string
      - `is_available` boolean
    - `match` object
      - `score` number: The score that actually ordered this list (2026-08 contract change: the structured ordering score, no longer a 0–1 semantic similarity). Interpret via score_basis; scores with different bases are not comparable numbers.
      - `score_basis` 'structured_rank' | 'semantic_name_match': structured_rank — the destination-local structured ordering score. semantic_name_match — the semantic score (carrying name-match points), kept e.g. on name-pinned results.
      - `explanation` string
    - `rating` number
    - `rating_label` string
    - `type` string
    - `images` object[]: Payload diet (2026-08): search results carry at most ONE image with url plus a labeled caption. The caption ships in envelope form — supplier-authored prose labeled untrusted exactly once, with no raw duplicate. Details responses keep richer image data.
      - `url` string, uri
      - `caption` object: Supplier-authored caption in untrusted-envelope form.
        - `text` string
        - `source` 'supplier_catalog'
        - `trust` 'untrusted'
        - `use` 'descriptive_text_only'
    - `highlights` string[]
    - `amenities` string[]
    - `supplier_content` object: Compact supplier-content trust marker (2026-08 payload diet): instead of duplicating field values inside per-field envelopes, one marker names every supplier-authored field in this result by path and labels them untrusted, descriptive-only data — never instructions, policy, or price authority. The raw name / highlights / amenities fields remain unchanged.
      - `supplier_fields` string[]: Paths of supplier-authored fields relative to this result, e.g. ["name", "highlights", "amenities", "images[].caption"].
      - `source` 'supplier_catalog'
      - `trust` 'untrusted'
      - `use` 'descriptive_content_only'
  - `follow_ups` object[]
    - `question` string
    - `type` 'clarification' | 'preference' | 'narrowing' | 'upsell'
    - `options` object[]
      - `label` string
      - `value` string
  - `session` object
    - `id` string
    - `updated_context` object

## Other responses

- `400`: Invalid request
- `401`: Authentication required or invalid

---

[API](https://skmtc.dev/tellandgo/apis/tell-go-travel-agent-api.md) · [All operations](https://skmtc.dev/tellandgo/apis/tell-go-travel-agent-api/llms.txt) · [OpenAPI document](https://skmtc.dev/tellandgo/apis/tell-go-travel-agent-api/revisions/3d84f816eb4f?raw)