Spotter Analyst API

ThoughtSpot Spotter Analysts are governed AI agents, each configured with a name, description, one or more data sources, and optional instructions, Model Context Protocol (MCP) connectors, and starter prompts. Users converse with an Analyst directly in the Spotter interface.

Supported endpoints🔗

Use the following endpoints to create, search, update, share, or delete Analysts programmatically:

POST /api/rest/2.0/ai/agent/analysts/create
Creates a Spotter Analyst with a name, description, data sources, and optional instructions, MCP connectors, and starter prompts.
Available on ThoughtSpot Cloud instances from 26.10.0.cl onwards.

POST /api/rest/2.0/ai/agent/analysts/search
Retrieves Analysts visible to the caller, either a single Analyst by identifier or a paginated list ordered by most recent access.
Available on ThoughtSpot Cloud instances from 26.10.0.cl onwards.

POST /api/rest/2.0/ai/agent/analysts/{analyst_identifier}/update
Updates a Spotter Analyst. The update is a full replace; omitted optional fields are cleared.
Available on ThoughtSpot Cloud instances from 26.10.0.cl onwards.

POST /api/rest/2.0/ai/agent/analysts/{analyst_identifier}/share ^Beta
Updates share permissions on a Spotter Analyst for one or more users or groups. Granting access also shares the Analyst’s data sources with the principal.
Available on ThoughtSpot Cloud instances from 26.10.0.cl onwards.

POST /api/rest/2.0/ai/agent/analysts/{analyst_identifier}/delete
Permanently deletes a Spotter Analyst. This operation is irreversible.
Available on ThoughtSpot Cloud instances from 26.10.0.cl onwards.

Analyst object🔗

Each AI Analyst object in ThoughtSpot has the following properties:

id
String. Server-assigned unique identifier.
name
String. Display name of the Analyst.
description
String. Description of the Analyst. Maximum 200 characters.
instructions
String. Optional natural-language behavior guidelines for the agent.
sources
Array of strings. Data sources the Analyst can query. Each source includes an id, type, and display name. Supported types: MODEL, ANSWER, LIVEBOARD, CONVERSATION.
mcp_connectors
Array of strings. Linked MCP connectors. Each connector includes id, name, and icon_url.
starter_prompts
Array of strings. Up to 4 suggested prompts shown on the Analyst landing page. Each entry includes label, text, order, and is_ai_generated.
icon_id
String. Analyst icon identifier. Analysts created via the API use the default icon until one is set in the UI.
updated_time_in_millis
Integer. Epoch timestamp in milliseconds of the last update.
last_accessed_time_in_millis
Integer. Epoch timestamp in milliseconds of the last access.
created_by
User who created the Analyst. Includes id, name, and display_name.
updated_by
User who last updated the Analyst. Includes id, name, and display_name.

Create an analyst🔗

To create a Spotter Analyst programmatically, send a POST request to the /api/rest/2.0/ai/agent/analysts/create endpoint with the Analyst definition in the request body. The definition includes a name, a description, and at least one data source, and can optionally include instructions, MCP connectors, and starter prompts.

Use this endpoint to provision governed Analysts as part of an automated deployment workflow, or to create Analysts programmatically across environments.

Note	Analysts created via the API use the default icon until one is set in the ThoughtSpot UI.

Required privileges🔗

Requires at least one of the following privileges:

ADMINISTRATION
CAN_MANAGE_SPOTTER
CAN_USE_SPOTTER

The user must also have at least view access to the data sources specified in the API request.

Request parameters🔗

Parameter Description

Parameter	Description
`name`	String. Display name of the Analyst.
`description`	String. Description of the Analyst. Maximum 200 characters.
`sources`	Array of objects. Data sources the Analyst can query. At least one source is required. The caller must have view access to every referenced source. For each source object, specify the following attributes: `identifier` String. Unique ID of the data source object. `type` String. Type of the data source object. Valid values: `MODEL`, `ANSWER`, `LIVEBOARD`, and `CONVERSATION`. `name` String. Optional. Display name of the data source.
`instructions`	String. Optional. Natural-language instructions that guide the agent’s behavior. Instructions that conflict with system guardrails are rejected with a `409` error.
`mcp_connector_identifiers`	Array of strings. Optional. Identifiers of MCP connectors to link to the Analyst.
`starter_prompts`	Array of strings. Optional. Up to 4 plain-text prompts, each between 10 and 250 characters. Display order follows list position.

name

String. Display name of the Analyst.

description

String. Description of the Analyst. Maximum 200 characters.

sources

Array of objects. Data sources the Analyst can query. At least one source is required. The caller must have view access to every referenced source. For each source object, specify the following attributes:

identifier
String. Unique ID of the data source object.
type
String. Type of the data source object. Valid values: MODEL, ANSWER, LIVEBOARD, and CONVERSATION.
name
String. Optional. Display name of the data source.

instructions

String. Optional. Natural-language instructions that guide the agent’s behavior. Instructions that conflict with system guardrails are rejected with a 409 error.

mcp_connector_identifiers

Array of strings. Optional. Identifiers of MCP connectors to link to the Analyst.

starter_prompts

Array of strings. Optional. Up to 4 plain-text prompts, each between 10 and 250 characters. Display order follows list position.

Request example🔗

curl -X POST \
  --url 'https://{cluster}/api/rest/2.0/ai/agent/analysts/create' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {token}' \
  --data-raw '{
  "name": "Revenue Analyst",
  "description": "Answers revenue questions using the Sales data model.",
  "sources": [
    {
      "identifier": "{model-guid}",
      "type": "MODEL"
    }
  ],
  "instructions": "Focus on year-over-year comparisons. Do not surface raw transaction data.",
  "starter_prompts": [
    "What was total revenue last quarter?",
    "Compare revenue by region for the past 12 months."
  ]
}'

API Response🔗

Returns 200 OK and the created Analyst object, including the server-assigned id.

Search analysts🔗

To retrieve the Spotter Analysts visible to the authenticated user, send a POST request to the /api/rest/2.0/ai/agent/analysts/search endpoint. Use this endpoint to fetch a specific Analyst by its identifier, or to render an Analyst catalog or picker in your app.

This endpoint operates in two modes:

Fetch mode: Provide analyst_identifier in the request body to retrieve a single Analyst. All other filters are ignored and total_size is 1.
List mode: Omit analyst_identifier to get a paginated list of Analysts, ordered by most recently accessed.

Required privileges🔗

Requires at least one of the following privileges:

ADMINISTRATION
CAN_MANAGE_SPOTTER
CAN_USE_SPOTTER

Request parameters🔗

Parameter Description

Parameter	Description
`analyst_identifier`	String. Optional. When provided, returns exactly this Analyst. All other filters are ignored.
`record_size`	Integer. Optional. Number of records per page. The default value is `50`. The supported range is 1 to 500.
`record_offset`	Integer. Optional. Zero-based index of the first record. The default value is `0`. The maximum value is `10000`.
`query`	String. Optional. Case-insensitive substring match on Analyst name.
`type`	String. Optional. Ownership filter. Valid values are `ALL` (default, returns Analysts created by or shared with the caller), `CREATED_BY_ME`, and `SHARED_TO_ME`.

analyst_identifier

String. Optional. When provided, returns exactly this Analyst. All other filters are ignored.

record_size

Integer. Optional. Number of records per page. The default value is 50. The supported range is 1 to 500.

record_offset

Integer. Optional. Zero-based index of the first record. The default value is 0. The maximum value is 10000.

query

String. Optional. Case-insensitive substring match on Analyst name.

type

String. Optional. Ownership filter. Valid values are ALL (default, returns Analysts created by or shared with the caller), CREATED_BY_ME, and SHARED_TO_ME.

Request examples🔗

List all Analysts

curl -X POST \
  --url 'https://{cluster}/api/rest/2.0/ai/agent/analysts/search' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {token}' \
  --data-raw '{
  "record_size": 50,
  "record_offset": 0,
  "type": "ALL"
}'

Fetch a single Analyst

curl -X POST \
  --url 'https://{cluster}/api/rest/2.0/ai/agent/analysts/search' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {token}' \
  --data-raw '{
  "analyst_identifier": "{analyst-guid}"
}'

API Response🔗

Returns 200 OK and an AnalystSearchResponse object with:

analysts: the current page of matching Analyst objects.
total_size: total count of matching Analysts before pagination.

Update an analyst🔗

To modify an existing Spotter Analyst, send a POST request to the /api/rest/2.0/ai/agent/analysts/{analyst_identifier}/update endpoint. The Analyst to update is identified by the analyst_identifier URL path parameter, and the new definition is passed in the request body.

The update is a full replace: the Analyst is rewritten from the request body, and any optional field omitted from the request is cleared. Include all fields you want to retain.

When new sources are added, they are automatically shared with users the Analyst was previously shared with. Those users retain access to a working Analyst.

Required privileges🔗

Requires at least one of the following privileges:

ADMINISTRATION
CAN_MANAGE_SPOTTER

The API endpoint doesn’t allow users to edit the Analyst objects that are shared with them by another user.

Request parameters🔗

Parameter Type Description

Parameter	Type	Description
`analyst_identifier`	Path parameter	String. Unique identifier of the Analyst to update, as returned by the Create an analyst or Search analysts endpoint.
`name`	Form parameter	String. Display name of the Analyst.
`description`	Form parameter	String. Description of the Analyst. Maximum 200 characters.
`sources`	Form parameter	Array of objects. Data sources the Analyst can query. Replaces the existing list in full. When new sources are added, they are automatically shared with users the Analyst was previously shared with, so those users keep a working Analyst.
`instructions`	Form parameter	String. Optional. Natural-language instructions that guide the agent’s behavior. Instructions that conflict with system guardrails are rejected with a `409` error. If instructions are not specified, any existing instructions on the Analyst are removed.
`mcp_connector_identifiers`	Form parameter	Array of strings. Optional. Identifiers of MCP connectors to link to the Analyst. Replaces the existing list in full. To remove the existing connectors, pass an empty array.
`starter_prompts`	Form parameter	Array of strings. Optional. Up to 4 plain-text prompts, each between 10 and 250 characters. Replaces the existing list in full. To remove the existing starter prompts, pass an empty array.

analyst_identifier

Path parameter

String. Unique identifier of the Analyst to update, as returned by the Create an analyst or Search analysts endpoint.

name

Form parameter

String. Display name of the Analyst.

description

Form parameter

String. Description of the Analyst. Maximum 200 characters.

sources

Form parameter

Array of objects. Data sources the Analyst can query. Replaces the existing list in full. When new sources are added, they are automatically shared with users the Analyst was previously shared with, so those users keep a working Analyst.

instructions

Form parameter

String. Optional. Natural-language instructions that guide the agent’s behavior. Instructions that conflict with system guardrails are rejected with a 409 error. If instructions are not specified, any existing instructions on the Analyst are removed.

mcp_connector_identifiers

Form parameter

Array of strings. Optional. Identifiers of MCP connectors to link to the Analyst. Replaces the existing list in full. To remove the existing connectors, pass an empty array.

starter_prompts

Form parameter

Array of strings. Optional. Up to 4 plain-text prompts, each between 10 and 250 characters. Replaces the existing list in full. To remove the existing starter prompts, pass an empty array.

Request examples🔗

curl -X POST \
  --url 'https://{cluster}/api/rest/2.0/ai/agent/analysts/{analyst_identifier}/update' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {token}' \
  --data-raw '{
  "name": "Revenue Analyst v2",
  "description": "Updated to include APAC data model.",
  "sources": [
    {
      "identifier": "{model-guid}",
      "type": "MODEL"
    },
    {
      "identifier": "{apac-model-guid}",
      "type": "MODEL"
    }
  ],
  "starter_prompts": [
    "What was total revenue last quarter?",
    "Compare revenue by region for the past 12 months.",
    "Show top 10 products by APAC revenue."
  ]
}'

Note	The update operation replaces existing properties of the Analyst object. Ensure that you include every parameter that you want to keep.

API Response🔗

Returns 200 OK and the updated Analyst object, including the refreshed updated_time_in_millis and updated_by fields.

To share a Spotter Analyst with other ThoughtSpot users and groups, or to change or revoke their access, send a POST request to the /api/rest/2.0/ai/agent/analysts/{analyst_identifier}/share endpoint. The Analyst to share is identified by the analyst_identifier URL path parameter, and the permission assignments are passed in the request body, one entry per principal.

Use READ_ONLY or MODIFY to grant or change a principal’s access, and NO_ACCESS to revoke it. When access is granted, the Analyst’s data sources are automatically shared with the principal, so the Analyst keeps working for them.

Users the Analyst is shared with can use it but cannot edit it. To allow editing, set share_mode to MODIFY.

Required privileges🔗

Requires at least one of the following privileges:

ADMINISTRATION
CAN_MANAGE_SPOTTER

Use a Bearer token for the Org in which the Analyst exists.

Request parameters🔗

Specify the analyst_identifier as a path parameter.

The request body contains a permissions array with one entry per principal. A principal may appear at most once per request.

Parameter Type Description

Parameter	Type	Description
`analyst_identifier`	Path parameter	String. Unique identifier of the Analyst to share, as returned by the Create an analyst or Search analysts endpoint.
`permissions`	Form parameter	Array of objects. Permission assignments, one entry per principal. A principal may appear at most once per request. For each entry, specify the following attributes: `principal` Object. The user or group to assign access to. Specify the following attributes: `identifier` String. Unique identifier of the user or group. `type` String. Type of principal. Valid values: `USER` and `USER_GROUP`. `share_mode` String. Access level to assign. `READ_ONLY` or `MODIFY` grants or changes the principal’s access. `NO_ACCESS` revokes it.

analyst_identifier

Path parameter

String. Unique identifier of the Analyst to share, as returned by the Create an analyst or Search analysts endpoint.

permissions

Form parameter

Array of objects. Permission assignments, one entry per principal. A principal may appear at most once per request. For each entry, specify the following attributes:

principal
Object. The user or group to assign access to. Specify the following attributes:
- identifier
  String. Unique identifier of the user or group.
- type
  String. Type of principal. Valid values: USER and USER_GROUP.
share_mode
String. Access level to assign. READ_ONLY or MODIFY grants or changes the principal’s access. NO_ACCESS revokes it.

Request examples🔗

Share with a user and a group

curl -X POST \
  --url 'https://{cluster}/api/rest/2.0/ai/agent/analysts/{analyst_identifier}/share' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {token}' \
  --data-raw '{
  "permissions": [
    {
      "principal": {
        "identifier": "{user-guid}",
        "type": "USER"
      },
      "share_mode": "READ_ONLY"
    },
    {
      "principal": {
        "identifier": "{group-guid}",
        "type": "USER_GROUP"
      },
      "share_mode": "MODIFY"
    }
  ]
}'

Revoke access

curl -X POST \
  --url 'https://{cluster}/api/rest/2.0/ai/agent/analysts/{analyst_identifier}/share' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {token}' \
  --data-raw '{
  "permissions": [
    {
      "principal": {
        "identifier": "{user-guid}",
        "type": "USER"
      },
      "share_mode": "NO_ACCESS"
    }
  ]
}'

API Response🔗

Returns an empty 204 No Content response on success.

Delete an analyst🔗

To permanently delete a Spotter Analyst, send a POST request to the /api/rest/2.0/ai/agent/analysts/{analyst_identifier}/delete endpoint with the Analyst’s unique identifier as the URL path parameter. No request body is required.

Warning

This operation is irreversible. Deleted Analysts cannot be recovered.

Required privileges🔗

The owners of the Analyst object specified in the API request can delete the object. Other users require at least one of the following privileges:

ADMINISTRATION
CAN_MANAGE_SPOTTER

The API endpoint doesn’t allow users to delete the Analyst objects that are shared with them by another user.

Request parameter🔗

Specify the ID of the Analyst to delete in the analyst_identifier path parameter.

Request example🔗

curl -X POST \
  --url 'https://{cluster}/api/rest/2.0/ai/agent/analysts/{analyst_identifier}/delete' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {token}'

API Response🔗

Returns 200 OK and an AnalystDeleteResponse object containing the id of the deleted Analyst.

Spotter Analyst API

Supported endpoints🔗

Analyst object🔗

Create an analyst🔗

Required privileges🔗

Request parameters🔗

Request example🔗

API Response🔗

Search analysts🔗

Required privileges🔗

Request parameters🔗

Request examples🔗

API Response🔗

Update an analyst🔗

Required privileges🔗

Request parameters🔗

Request examples🔗

API Response🔗

Share an analyst Beta🔗

Required privileges🔗

Request parameters🔗

Request examples🔗

API Response🔗

Delete an analyst🔗

Required privileges🔗

Request parameter🔗

Request example🔗

API Response🔗

Related resources🔗

Share an analyst ^Beta🔗