POST /api/rest/2.0/ai/agent/conversation/create
Allows you to save a conversation session with Spotter AI agent
Available on ThoughtSpot Cloud instances from 26.5.0.cl onwards.
APIs for managing saved conversations
Table of Contents
ThoughtSpot’s Spotter AI conversation management APIs allow you to retrieve, update, and delete saved Spotter 3 conversations and their message history. These APIs allow you to build and render custom conversation history UI, audit trails, and administrative conversation management workflows in applications using Spotter engine or embedding Spotter interface.
Prerequisites🔗
To create, save, and manage conversation sessions with the Spotter 3 agent, you need CAN_USE_SPOTTER (Can use Spotter) privilege and access to the saved conversation. Only conversation owners can delete or update their saved conversations.
Supported API operations🔗
|
|
|
|
|
Saving a conversation🔗
To save a conversation, set the enable_save_chat parameter to true when sending a conversation create POST request to the /api/rest/2.0/ai/agent/conversation/create API endpoint.
API request example🔗
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
}
}'If the API request is successful, ThoughtSpot returns the conversation IDs.
{
"conversation_id":"MotUVRdguIcr",
"conversation_identifier":"MotUVRdguIcr"
}Note these IDs.
Get conversation messages🔗
To retrieve a saved conversation, send a GET request to the /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/messages API endpoint with the conversation ID in the API request URL. Use this endpoint to render a persisted conversation in a UI, build an audit trail, or post-process a completed conversation.
|
Note
|
The full answer payload for each turn is not embedded in the response. To retrieve it, call the
load answer details endpoint with
the |
Example request🔗
curl -X GET \
--url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversations/MotUVRdguIcr/messages' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {AUTH_TOKEN}' \Response body🔗
A successful request returns an HTTP 200 response with top-level fields that include ordered conversation turns (user prompts and agent response items) and sanitized metadata for any files generated by the code-execution tool.
When the agent conversation is initiated from a Liveboard, ThoughtSpot automatically seeds the conversation with the existing Liveboard visualization as the first response turn, without any user query. In the API response, this seeded turn appears as the first item in the messages array with user_prompt set to null and message_id set to the internal root node identifier of the conversation. All subsequent turns contain a populated user_prompt. When rendering conversation history, always check whether user_prompt is null before attempting to display a user query.
API response🔗
A successful request returns an HTTP 200 response with the following top-level fields. The response includes ordered conversation turns (user prompts and agent response items) and sanitized metadata for any files generated by the code-execution tool.
When the agent conversation is initiated from a Liveboard, ThoughtSpot automatically seeds the conversation with the existing Liveboard visualization as the first response turn, without any user query. In the API response, this seeded turn appears as the first item in the messages array with user_prompt set to null and message_id set to the internal root node identifier of the conversation. All subsequent turns contain a populated user_prompt. When rendering conversation history, always check whether user_prompt is null before attempting to display a user query.
| Field | Description |
|---|---|
| An ordered array of conversation turns, oldest to newest. Returns an empty array when the conversation has no messages. |
|
|
ConversationMessage🔗
Each item in messages represents one conversational turn.
| Field | Description |
|---|---|
| String. Message ID. For Liveboard-initiated first turns, this ID is the root node identifier. |
| Unix epoch timestamp for the turn, in milliseconds. |
|
|
| An array of agent response items produced for this turn. Returns an empty array for turns that are still in progress, which allows the UI to render the user message immediately while the agent is still processing. |
UserPrompt🔗
| Field | Description |
|---|---|
|
|
|
|
UserMessage🔗
| Field | Description |
|---|---|
| String. Unique identifier of the user message. |
| String. Text body of the user query. |
UserAttachmentItem🔗
Is distinguished by the type field. Valid values are file and resource. Only the fields for the indicated variant are populated.
| Field | Description |
|---|---|
| String. Attachment type. Valid values: |
| String. Unique identifier of the attached file. Matches a |
| String. Identifier of the attached connector resource. |
ConversationResponseItem🔗
Each agent response item carries a type distinguisher. The following types are supported.
| Field | Description |
|---|---|
| String. Response item variant distinguisher. Supported values include:
|
| String. Unique identifier of the answer. Use this to call the load answer details endpoint. |
| String. Text content of the response. |
CodeExecutionFileMetadata🔗
Sanitized metadata for a file generated by the code-execution tool.
| Field | Description |
|---|---|
| String. Unique identifier of the code-execution-generated file. Stable across conversation turns. Use this to match attachment references in |
| String. Human-readable file name. |
| String. File type hint. Either a MIME type string (for example, |
| Unix epoch timestamp when the file was created, in milliseconds. |
| Boolean. Set to |
Response example🔗
{
"messages": [
{
"message_id": "node_u_01",
"timestamp_in_millis": 1744000000000,
"user_prompt": {
"message": {
"message_id": "msg_u_01",
"content": "Show me revenue by region as a chart."
},
"attachments": []
},
"response_items": [
{
"type": "tool_call",
"tool_call_id": "toolu_01ABC",
"tool_name": "search_datasets",
"step_title": "Searching datasets",
"arguments": { "query": "revenue" },
"timestamp_in_millis": 1744000001000,
"is_thinking": false
},
{
"type": "answer",
"answer_id": "ans_01XYZ",
"tool_call_id": "toolu_02DEF",
"tool_name": "fetch_and_visualize",
"step_title": "Visualising",
"timestamp_in_millis": 1744000004000,
"is_thinking": false
},
{
"type": "text",
"content": "Revenue is highest in APAC.",
"content_type": "TEXT_MARKDOWN",
"timestamp_in_millis": 1744000005000,
"is_thinking": false,
"step_title": null,
"file_reference": {
"file_id": "revenue_by_region.csv",
"display_name": "revenue_by_region.csv",
"created_time_in_millis": 1744027200000
}
}
]
}
],
"code_execution_files": [
{
"file_id": "revenue_by_region.csv",
"display_name": "revenue_by_region.csv",
"file_type": "csv",
"created_time_in_millis": 1744027200000,
"expired": false
}
]
}Get conversation list🔗
The GET /api/rest/2.0/ai/agent/conversations endpoint retrieves a paginated list of saved conversations for the currently authenticated user. Only conversations created with enable_save_chat: true are returned in the API response.
Request parameters🔗
| Query parameter | Description |
|---|---|
| Number. Maximum number of conversations to return per page. Use together with |
| Number. Number of conversations to skip before returning results. Defaults to |
| Boolean. When set to |
API request🔗
curl -X GET -G \
--url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversations' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {AUTH_TOKEN}' \
-d 'limit=30' \
-d 'offset=0' \
-d 'skip_empty=true'API response🔗
If the API request is successful, ThoughtSpot returns a response body. The API response does not include a total_count field. Use has_more to drive pagination controls.
Response body🔗
| Field | Description |
|---|---|
|
|
| Boolean. Set to |
AgentConversationList🔗
Each item in conversations represents a saved conversation.
| Field | Description |
|---|---|
| String. Unique identifier of the conversation. Use this value as input in your API requests to the send message, update conversation, delete conversation, stop response, and load answer endpoints. |
| String. Display name of the conversation. |
| String. Timestamp of when the conversation was created. |
| String. Timestamp of when the conversation was last updated. |
| Array of strings. Unique identifiers of the data sources associated with the conversation. |
|
|
DataSourceEntry🔗
| Field | Description |
|---|---|
| String. Unique identifier of the data source. |
| String. Display name of the data source. |
Pagination🔗
Use limit and offset together to page through large result sets. The response does not include a total_count field. Use has_more to determine whether additional pages exist.
GET /api/rest/2.0/ai/agent/conversations?limit=20&offset=0 (first page) GET /api/rest/2.0/ai/agent/conversations?limit=20&offset=20 (second page)
Continue incrementing offset by limit until has_more returns false.
API response example🔗
{
"conversations": [
{
"conversation_identifier": "abc123",
"conversation_title": "Sales by Region Q1",
"created_at": "2026-03-01T10:00:00Z",
"updated_at": "2026-03-05T14:23:00Z",
"data_source_identifiers": ["ds-001"],
"data_source_names": [{ "id": "ds-001", "name": "Retail Sales" }]
}
],
"has_more": false
}Load answer details🔗
To retrieve the full answer payload for a specific analytical answer within a saved conversation, send a GET request to the GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/answers/{answer_identifier}/details endpoint with the conversation ID and answer ID in the request URL.
Call sequence🔗
The following sequence is required to resolve a full answer from a saved conversation:
-
Call get conversation list to retrieve saved conversations and obtain a
conversation_identifier. -
Call get conversation messages with the
conversation_identifier. Locateresponse_itemsentries withtype: answerand note theanswer_idfield on each. -
Call this endpoint with the
conversation_identifierand theanswer_idasanswer_identifierto retrieve the full answer payload. -
Use the
tokensarray in the response to reconstruct or render the answer in your application.
Request parameters🔗
| Parameter | Description |
|---|---|
| String. Path parameter. Unique identifier of the conversation. |
| String. Path parameter. The |
API request🔗
curl -X GET \
--url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversations/0iwTDJU-tlkm/answers/5MS5xieDhefP/details' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {AUTH_TOKEN}' \Response body🔗
If the API request is successful, ThoughtSpot returns a response body with the answer details.
| Field | Type | Description |
|---|
Example response🔗
{
"answer":{
"title":"total sales by state where item type is jackets",
"description":null,
"session_identifier":"5216568f-f808-4385-ad0a-3a40bb9b5dcb",
"generation_number":2,
"tokens":[
"[sales] [state] [item type] = 'jackets'"
],
"visualization_type":"UNDEFINED",
"formulas":[
],
"parameters":[
],
"sub_queries":[
],
"ac_state":{
"transaction_identifier":"00ccc6e0-1117-4713-8798-d6201d3a5a40",
"generation_number":1
}
}
}Update a conversation🔗
To update the metadata of an existing conversation, send a POST request to the /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/update API endpoint with the conversation ID in the request URL. Currently, the API endpoint allows you to rename the conversation title only.
Request parameters🔗
| Parameter | Description |
|---|---|
| String. Path parameter. Unique identifier of the conversation to update. |
| String. Form parameter to include in the request body. To rename the display title of the conversation, specify the title string. |
API request example🔗
curl -X POST \
--url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversations/0iwTDJU-tlkm/update' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {AUTH_TOKEN}' \
--data-raw '{
"title": "Revenue Analysis — Q1 2026"
}'API response🔗
A successful request returns the 204 response. The response body contains the updated conversation object reflecting the applied changes.
Delete a conversation🔗
To delete a saved conversation and all its associated messages, send a DELETE request to the /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/delete API endpoint with the conversation ID as a path parameter.
|
Important
|
|
API request🔗
curl -X DELETE \
--url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversations/MotUVRdguIcr/delete' \
-H 'Authorization: Bearer {AUTH_TOKEN}' \API response🔗
A successful request returns an HTTP 204 No Content response with an empty body. After a successful deletion, subsequent calls to the get conversation messages or load answer endpoints for the same conversation_identifier result in the 404 Not Found error.
Additional resources🔗
-
See also Spotter Agent APIs
-
To try out the request and response workflow, use the REST API Playground