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 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.
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.
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.
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 New
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 New
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 New
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 New
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 New
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🔗

Spotter agent conversation APIs
Create conversation sessions, send synchronous queries, and stop in-progress responses.
Spotter agent streaming APIs
Send queries and receive real-time Server-Sent Events (SSE) responses from the Spotter agent.
Process Spotter agent conversation results
Export or download Answers generated by a Spotter agent conversation session.
Spotter agent data literacy APIs
Get data source suggestions and decompose a user query into relevant sub-questions.
Spotter agent conversation sharing APIs
Share saved Spotter conversations with other users and groups.
APIs for managing saved conversations
Retrieve, update, and delete saved Spotter 3 conversations and their messages.
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.