# Spotter AI Agent APIs

> For the complete documentation index, see [llms.txt](https://developers.thoughtspot.com/docs/llms.txt)

Source: https://developers.thoughtspot.com/docs/spotter-agent-apis

# Spotter AI Agent APIs

ThoughtSpot’s Spotter AI agent APIs allow users to start a conversation session with Spotter Agent and send queries to explore data and receive responses synchronously or as a real-time Server-Sent Events (SSE) stream.

## Overview

Spotter AI agent APIs support conversation sessions with natural language query strings, provide context-aware and guided data analysis, and allow integration with other agentic systems.

The key capabilities of the Spotter APIs include the following:

-   Initiating and managing conversational sessions
    
-   Processing natural-language queries
    
-   Generating analytical responses, insights, and visualizations
    
-   Recommending relevant datasets or data sources
    
-   Decomposing complex user queries
    

## Supported API endpoints

The API endpoints introduced for Spotter 2 also support Spotter 3 capabilities as of version 26.2.0.cl. Some of these API endpoints are deprecated in 26.5.0.cl; ThoughtSpot recommends using the new API endpoints instead.

Initialize session

Call the create agent conversation API (`/api/rest/2.0/ai/agent/conversation/create`) with a data source ID to establish the session context. When auto mode is enabled, and no data source ID is specified in the API request, Spotter will automatically identify the appropriate data source. See [Spotter agent conversation APIs]({{navprefix}}/{{spotter-agent-conversation-apis}}).

Execute queries

To execute queries and generate a standard response synchronously, use the Send agent conversation message API (`/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send`). The send agent message API (`/api/rest/2.0/ai/agent/{conversation_identifier}/converse`) is deprecated in 26.5.0.cl and later versions. See [Spotter agent conversation APIs]({{navprefix}}/{{spotter-agent-conversation-apis}}).

Real-time output (streaming)

To stream responses to the application UI in real-time, use the `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream`. The legacy streaming API (`/api/rest/2.0/ai/agent/converse/sse`) is deprecated in 26.5.0.cl and later versions. See [Spotter agent streaming APIs]({{navprefix}}/{{spotter-agent-streaming-apis}}).

Share a conversation

Share a saved Spotter conversation with other users or groups as read-only content. See [Spotter agent conversation sharing APIs]({{navprefix}}/{{spotter-agent-sharing-apis}}).

<table class="tableblock frame-all grid-all stretch"><colgroup><col style="width: 100%;"></colgroup><tbody><tr><td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph"><p><code>POST /api/rest/2.0/ai/agent/conversation/create</code><br><a href="{{navprefix}}/{{spotter-agent-conversation-apis}}#_create_a_conversation_session_with_spotter_agent">Creates a conversation session with the Spotter agent</a> to generate Answers for the specified data context. <em>Available on ThoughtSpot Cloud instances from 10.13.0.cl onwards. Breaking changes introduced in 26.5.0.cl.</em></p></div></div></td></tr><tr><td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph"><p><code>POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send</code> <span class="version-badge new">New</span><br><a href="{{navprefix}}/{{spotter-agent-conversation-apis}}#_send_queries_to_a_conversation_session">Sends natural language messages</a> to an existing Spotter agent conversation and returns the complete response synchronously. <em>Replaces /api/rest/2.0/ai/agent/{conversation_identifier}/converse</em>.</p></div></div></td></tr><tr><td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph"><p><code>POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream</code> <span class="version-badge new">New</span><br><a href="{{navprefix}}/{{spotter-agent-streaming-apis}}">Sends one or more natural language messages</a> to an existing Spotter agent conversation and returns the response as a real-time Server-Sent Events (SSE) stream. <em>Replaces /api/rest/2.0/ai/agent/converse/sse</em>.</p></div></div></td></tr><tr><td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph"><p><code>POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response</code> <span class="version-badge new">New</span><br><a href="{{navprefix}}/{{spotter-agent-conversation-apis}}#_stop_an_in_progress_agent_response">Stops an in-progress Spotter agent response</a> for a given conversation session. The conversation session remains active after the response stops.<br><em>Available on ThoughtSpot Cloud instances from 26.6.0.cl onwards.</em></p></div></div></td></tr><tr><td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph"><p><code>POST /api/rest/2.0/ai/data-source-suggestions</code> <sup class="beta betaBackground">Beta</sup><br><a href="{{navprefix}}/{{spotter-agent-data-literacy-apis}}#_get_data_source_suggestions">Returns a list of relevant data sources</a>, such as Models, based on a query and thus helping users and agents choose the most appropriate data source for analytics.<br><em>Available on ThoughtSpot Cloud instances from 10.15.0.cl onwards</em>.</p></div></div></td></tr><tr><td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph"><p><code>POST /api/rest/2.0/ai/relevant-questions/</code> <sup class="beta betaBackground">Beta</sup><br><a href="{{navprefix}}/{{spotter-agent-data-literacy-apis}}#_get_relevant_questions">Decomposes a user query</a> into relevant sub-questions. Guides users to explore data more deeply for a comprehensive analysis.<br><em>Available on ThoughtSpot Cloud instances from 10.13.0.cl onwards</em>.</p></div></div></td></tr><tr><td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph"><p><code>POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share</code> <span class="version-badge new">New</span><br><a href="{{navprefix}}/{{spotter-agent-sharing-apis}}#_share_a_conversation">Shares a saved Spotter conversation</a> with one or more users or groups. Use <code>grant</code> and <code>revoke</code> arrays to manage access. Shared conversations are <code>READ_ONLY</code>.<br><em>Available on ThoughtSpot Cloud instances from 26.9.0.cl onwards.</em></p></div></div></td></tr><tr><td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph"><p><code>GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content</code> <span class="version-badge new">New</span><br><a href="{{navprefix}}/{{spotter-agent-sharing-apis}}#_get_shared_content">Returns the shared content</a> of a Spotter conversation, including messages and associated answers.<br><em>Available on ThoughtSpot Cloud instances from 26.9.0.cl onwards.</em></p></div></div></td></tr><tr><td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph"><p><code>GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info</code> <span class="version-badge new">New</span><br><a href="{{navprefix}}/{{spotter-agent-sharing-apis}}#_get_share_information">Returns sharing metadata</a> for a Spotter conversation — the list of principals it is shared with and whether the shared content is outdated.<br><em>Available on ThoughtSpot Cloud instances from 26.9.0.cl onwards.</em></p></div></div></td></tr><tr><td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph"><p><code>POST /api/rest/2.0/ai/agent/converse/sse</code> <span class="version-badge deprecated">Deprecated</span><br>Legacy API endpoint for streaming responses, including tokens and visualizations, for a specific conversation context. <em>Deprecated in 26.5.0.cl</em>.</p></div></div></td></tr><tr><td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph"><p><code>POST /api/rest/2.0/ai/agent/{conversation_identifier}/converse</code> <span class="version-badge deprecated">Deprecated</span><br>Legacy API endpoint to send natural language queries to a conversation session with Spotter agent.<br><em>Deprecated in 26.5.0.cl</em>.</p></div></div></td></tr></tbody></table>

## Additional resources

-   [Spotter agent conversation APIs]({{navprefix}}/{{spotter-agent-conversation-apis}})  
    Create conversation sessions, send synchronous queries, and stop in-progress responses.
    
-   [Spotter agent streaming APIs]({{navprefix}}/{{spotter-agent-streaming-apis}})  
    Send queries and receive real-time Server-Sent Events (SSE) responses from the Spotter agent.
    
-   [Process Spotter agent conversation results]({{navprefix}}/{{spotter-agent-process-results-apis}})  
    Export or download Answers generated by a Spotter agent conversation session.
    
-   [Spotter agent data literacy APIs]({{navprefix}}/{{spotter-agent-data-literacy-apis}})  
    Get data source suggestions and decompose a user query into relevant sub-questions.
    
-   [Spotter agent conversation sharing APIs]({{navprefix}}/{{spotter-agent-sharing-apis}})  
    Share saved Spotter conversations with other users and groups.
    
-   [APIs for managing saved conversations]({{navprefix}}/{{spotter-agent-conversation-mgmt-apis}})  
    Retrieve, update, and delete saved Spotter 3 conversations and their messages.
    
-   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.
    
-   For information about MCP tools, see [MCP server integration]({{navprefix}}/{{mcp-integration}}).