LLMs.txt: Complete documentation index for AI agents
Spotter agent conversation APIs
Cloud
26.9.0.clCloud (Latest)
26.8.0.clCloud
26.7.0.clCloud
Software
26.3.0.swSoftware (Latest)
10.10.0.swSoftware
10.1.0.swSoftware
GitHub

Spotter agent conversation APIs

ThoughtSpot’s Spotter agent conversation APIs allow you to create a conversation session with the Spotter agent, send natural language queries to it, and stop an in-progress response.

For information about receiving responses as a real-time event stream, see Spotter agent streaming APIs. For information about exporting Answers generated by a conversation, see Process Spotter agent conversation results. For information about the data source and question suggestion APIs, see Spotter agent data literacy APIs. For information about sharing saved conversations, see Spotter agent conversation sharing APIs.

Create a conversation session with Spotter Agent🔗

The /api/rest/2.0/ai/agent/conversation/create API endpoint creates a new conversation session with Spotter Agent for a specific or multi-data context and returns a conversation ID.

Request parameters🔗

The request body must include the metadata_context. REST API clients must have at least view access to the data source objects specified in the API request to create a conversation session and use it for subsequent queries.

Form parameterDescription

metadata_context

Defines the data context for the conversation.

  • type
    Metadata context type. The context type is mandatory. Select one of the following values:

    • AUTO_MODE to allow Spotter Agent to automatically discover and select the most relevant datasets for users' queries.

    • DATA_SOURCE to set a specific data source as the data context. You must specify data_source_context and data source IDs.
      To set a specific data source object, use data_source_identifier.
      To set multi-data context, use data_source_identifiers.

    • data_source Deprecated
      This option is deprecated in 26.5.0.cl. ThoughtSpot recommends using the DATA_SOURCE with data_source_context and data source IDs instead.

conversation_settings

Optional. Defines additional parameters for the conversation context. You can set any of the following attributes as needed:

  • enable_contextual_change_analysis
    Boolean. When enabled, Spotter analyzes how context changes over time, that is, comparing results from different queries. Enabled by default in 26.2.0.cl and later versions.

  • enable_natural_language_answer_generation
    Boolean. Allows sending natural language queries to the conversation session. Enabled by default in 26.2.0.cl and later versions.

  • enable_reasoning
    Boolean. Allows Spotter to use reasoning for deep analysis and precise responses. Enabled by default in 26.2.0.cl and later versions.

  • enable_save_chat
    When set to true, adds the conversation to chat history.

Example request🔗

With AUTO_MODE for metadata context
curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/create'  \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {AUTH_TOKEN}' \
  --data-raw '{
  "metadata_context": {
    "type": "AUTO_MODE"
  },
  "conversation_settings": {
    "enable_save_chat": true
  }
}'
For a single data source as the data context
curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/create'  \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {AUTH_TOKEN}' \
  --data-raw '{
  "metadata_context": {
    "type": "DATA_SOURCE",
    "data_source_context": {
      "data_source_identifier": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
  },
  "conversation_settings": {}
}'
For multi-data source context
curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/create'  \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {AUTH_TOKEN}' \
  --data-raw '{
  "metadata_context": {
    "type": "DATA_SOURCE",
    "data_source_context": {
      "data_source_identifiers": [
        "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "b2c3d4e5-f6a7-8901-bcde-f12345678901"
      ]
    }
  },
  "conversation_settings": {
    "enable_save_chat": true
  }
}'

API response🔗

If the API request is successful, the API returns the conversation ID and identifier in the response body.

{
  "conversation_id": "wwHQ5j8O8dQC",
  "conversation_identifier": "wwHQ5j8O8dQC"
}

  • conversation_identifier
    Use this for all subsequent message calls.

  • conversation_id Deprecated
    Returns the same value as conversation_identifier.

Send queries to a conversation session🔗

To send queries to an ongoing conversation session with the Spotter agent and receive a response synchronously, use the /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send API endpoint.

This API operation requires the conversation ID obtained from the conversation creation API endpoint (/api/rest/2.0/ai/agent/conversation/create). The user making the API request must have access to the conversation session. The API request body must include at least one message in natural language format.

Request parameters🔗

ParameterTypeDescription

conversation_identifier

Path parameter

String. Required. Specify the conversation ID received from the POST /api/rest/2.0/ai/agent/conversation/create API call.

messages

Form parameter

Array of strings. Required. Specify at least one query in natural language. For example, total sales of jackets last month.

Request and response examples🔗

The following example sends a data comparison query to a conversation session. The conversation ID is specified in the request URL as a path parameter.

curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {AUTH_TOKEN}'  \
  --data-raw '{
  "messages": [
    "Sales in 2025 vs 2024"
  ]
}'

If the request is successful, the API returns an array of objects in the response. The messages in the API response include the following parts:

[
  {
    "type": "text",
    "text": "\n\nI'll compare sales between 2025 and 2024. First, let me get the dataset context.",
    "metadata": {},
    "internal": {},
    "agent_context": ""
  },
  {
    "type": "text",
    "text": "```json\n{\"dataset_name\":\"(Sample) Retail - Apparel\",\"columns\":[{\"name\":\"sales\",\"type\":\"MEASURE\"},{\"name\":\"date\",\"type\":\"ATTRIBUTE\"}]}\n```",
    "metadata": {},
    "internal": {},
    "agent_context": ""
  },
  {
    "type": "answer",
    "title": "Compare total sales for 2025 vs 2024",
    "description": "",
    "session_id": "842bb67a-e08e-4861-97e8-8db9538db51d",
    "gen_no": 2,
    "sage_query": "[sales] [date] = '2025' vs [date] = '2024'",
    "tml_tokens": ["[sales]", "[date] = '2025' vs [date] = '2024'"],
    "formulas": [],
    "parameters": [],
    "subqueries": [],
    "viz_suggestion": "CAEQIBomEiQ2NjE5NzI0Yy1kMjVlLTU4MDItOWNjOC1jNDA3MWY3OWY5MzAoATIA",
    "metadata": {
      "output": "<base64-encoded-protobuf-output>",
      "worksheet_id": "cd252e5c-b552-49a8-821d-3eadaa049cca",
      "chart_type": "KPI",
      "interrupted": false,
      "data_awareness_enabled": true
    },
    "internal": {}
  },
  {
    "type": "text",
    "text": "\n\nThe visualization shows year-over-year comparison. You can identify growth or decline trends.",
    "metadata": {},
    "internal": {},
    "agent_context": ""
  }
]

The following example sends a follow-up question to the same conversation session.

curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {AUTH_TOKEN}'  \
  --data-raw '{
  "messages": [
    "Now break that down by product category"
  ]
}'

If the request is successful, the agent returns the response for the follow-up question:

[{
    "type": "text",
    "text": "I'll add product category to the comparison.",
    "metadata": {},
    "internal": {},
    "agent_context": ""
  },
  {
    "type": "answer",
    "title": "Sales by Product Category: 2025 vs 2024",
    "session_id": "9abc1234-0000-0000-0000-000000000005",
    "gen_no": 3,
    "sage_query": "[sales] [product category] [date] = '2025' vs [date] = '2024'",
    "tml_tokens": ["[sales]", "[product category]", "[date] = '2025' vs [date] = '2024'"],
    "formulas": [],
    "parameters": [],
    "subqueries": [],
    "viz_suggestion": "",
    "metadata": {
      "chart_type": "BAR",
      "worksheet_id": "cd252e5c-b552-49a8-821d-3eadaa049cca"
    },
    "internal": {}
  }]

In each response, the agent returns the following information:

  • type
    Type of the message, such as text, answer, or error.

  • text
    Response message generated for the query.

  • metadata
    Additional information based on the message type. For example, answer metadata, chart type, or the data source ID.

  • tml_tokens
    Query string broken down as TML tokens.

In case of errors, the response returns the error details:

[{
    "type": "error",
    "message": "The conversation session has expired. Please create a new conversation.",
    "code": "SESSION_EXPIRED"
}]

Stop an in-progress agent response🔗

The /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response API endpoint stops a Spotter agent response that is currently in progress for a given conversation session.

Use this endpoint when you want to cancel a long-running Spotter response before it completes. The conversation session remains active after you stop a response, so you can send a new query to the same session immediately.

Request parameters🔗

ParameterTypeDescription

conversation_identifier

Path parameter

String. Required. The identifier of the active conversation session. Use the value returned by the create conversation API endpoint.

This endpoint does not require a request body.

Example request🔗

curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {AUTH_TOKEN}'

Example response🔗

If the API request is successful, ThoughtSpot stops the in-progress response and returns a 204 response code.

If the conversation session is not found or has expired, the API returns an error:

{
  "error_code": "CONVERSATION_NOT_FOUND",
  "message": "The specified conversation session does not exist or has expired."
}

Additional resources🔗

© 2026 ThoughtSpot Inc. All Rights Reserved.