Spotter AI Agent APIs

Table of Contents

Overview
Supported API endpoints
Additional resources

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. Some of these API endpoints are deprecated; 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.
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). See 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. See 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.

POST /api/rest/2.0/ai/agent/conversation/create
Creates a conversation session with the Spotter agent to generate Answers for the specified data context. Available on ThoughtSpot Cloud instances from 10.13.0.cl onwards. Breaking changes introduced in 26.5.0.cl.

POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send

Sends natural language messages to an existing Spotter agent conversation and returns the complete response synchronously. Replaces /api/rest/2.0/ai/agent/{conversation_identifier}/converse.

POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream
Sends one or more natural language messages to an existing Spotter agent conversation and returns the response as a real-time Server-Sent Events (SSE) stream. Replaces /api/rest/2.0/ai/agent/converse/sse.

POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response New
Stops an in-progress Spotter agent response for a given conversation session. The conversation session remains active after the response stops.
Available on ThoughtSpot Cloud instances from 26.6.0.cl onwards.

POST /api/rest/2.0/ai/data-source-suggestions ^Beta
Returns a list of relevant data sources, such as Models, based on a query and thus helping users and agents choose the most appropriate data source for analytics.
Available on ThoughtSpot Cloud instances from 10.15.0.cl onwards.

POST /api/rest/2.0/ai/relevant-questions/ ^Beta
Decomposes a user query into relevant sub-questions. Guides users to explore data more deeply for a comprehensive analysis.
Available on ThoughtSpot Cloud instances from 10.13.0.cl onwards.

POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share
Shares a saved Spotter conversation with one or more users or groups. Use grant and revoke arrays to manage access. Shared conversations are READ_ONLY.
Available on ThoughtSpot Cloud instances from 26.9.0.cl onwards.

GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content
Returns the shared content of a Spotter conversation, including messages and associated answers.
Available on ThoughtSpot Cloud instances from 26.9.0.cl onwards.

GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info
Returns sharing metadata for a Spotter conversation — the list of principals it is shared with and whether the shared content is outdated.
Available on ThoughtSpot Cloud instances from 26.9.0.cl onwards.

POST /api/rest/2.0/ai/agent/converse/sse Deprecated
Legacy API endpoint for streaming responses, including tokens and visualizations, for a specific conversation context. Deprecated in 26.5.0.cl.

POST /api/rest/2.0/ai/agent/{conversation_identifier}/converse Deprecated
Legacy API endpoint to send natural language queries to a conversation session with Spotter agent.
Deprecated in 26.5.0.cl.

Additional resources🔗

For the complete list of Spotter API pages, rate limits, and locale settings, see Spotter APIs.
Visit the REST API v2.0 Playground to view the API endpoints and verify the request and response workflows.
For information about MCP tools, see MCP server integration.