# Spotter agent conversation APIs > For the complete documentation index, see [llms.txt](https://developers.thoughtspot.com/docs/llms.txt) Source: https://developers.thoughtspot.com/docs/spotter-agent-conversation-apis # 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]({{navprefix}}/{{spotter-agent-streaming-apis}}). For information about exporting Answers generated by a conversation, see [Process Spotter agent conversation results]({{navprefix}}/{{spotter-agent-process-results-apis}}). For information about the data source and question suggestion APIs, see [Spotter agent data literacy APIs]({{navprefix}}/{{spotter-agent-data-literacy-apis}}). For information about sharing saved conversations, see [Spotter agent conversation sharing APIs]({{navprefix}}/{{spotter-agent-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 parameter | Description | | --- | --- | | `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 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 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 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. ```JSON { "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 | Parameter | Type | Description | | --- | --- | --- | | `conversation_identifier` | Path parameter | _String_. Required. Specify the conversation ID received from the [POST /api/rest/2.0/ai/agent/conversation/create]({{navprefix}}/{{spotter-agent-conversation-apis}}#_create_a_conversation_session_with_spotter_agent) 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 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: ```JSON [ { "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": "", "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 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: ```JSON [{ "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: ```JSON [{ "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 | Parameter | Type | Description | | --- | --- | --- | | `conversation_identifier` | Path parameter | _String_. Required. The identifier of the active conversation session. Use the value returned by the [create conversation]({{navprefix}}/{{spotter-agent-conversation-apis}}#_create_a_conversation_session_with_spotter_agent) API endpoint. | This endpoint does not require a request body. ### Example request ```cURL 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: ```JSON { "error_code": "CONVERSATION_NOT_FOUND", "message": "The specified conversation session does not exist or has expired." } ``` ## Additional resources - See also [Spotter Agent APIs]({{navprefix}}/{{spotter-agent-apis}}) - [Spotter agent streaming APIs]({{navprefix}}/{{spotter-agent-streaming-apis}}) - [Process Spotter agent conversation results]({{navprefix}}/{{spotter-agent-process-results-apis}}) - [Spotter agent data literacy APIs]({{navprefix}}/{{spotter-agent-data-literacy-apis}}) - [Spotter agent conversation sharing APIs]({{navprefix}}/{{spotter-agent-sharing-apis}}) - Visit the [REST API v2.0 Playground]({{navprefix}}/restV2-playground?apiResourceId=http%2Fgetting-started%2Fintroduction) to view the API endpoints and verify the request and response workflows.