openapi: 3.0.0
info:
title: ThoughtSpot Public REST 10.1.0.cl 26.2.0.cl API
version: '2.0'
servers:
- url: '{base-url}'
variables:
base-url:
default: https://localhost:443
security:
- bearerAuth: []
tags:
- name: 26.2.0.cl
paths:
/api/rest/2.0/ai/agent/conversation/create:
post:
operationId: createAgentConversation
description: "\n <span class=\"since-beta-tag\">Version: 26.2.0.cl or later</span>\n\n<span class=\"since-beta-tag\">Version: 26.2.0.cl or later</span>\n\nCreates a new Spotter agent conversation based on the provided context and settings. The endpoint was in Beta from 26.2.0.cl through 26.4.0.cl.\n\nRequires `CAN_USE_SPOTTER` privilege and at least view access to the metadata object specified in the request.\n\n#### Usage guidelines\n\nThe request must include the `metadata_context` parameter to define the conversation context. The context type can be one of:\n\n- `DATA_SOURCE` *(available from 26.5.0.cl)*: targets a specific data source. Provide `data_source_identifier` in `data_source_context` for a single data source, or `data_source_identifiers` for multi-data-source context. The deprecated `guid` field is accepted for backwards compatibility.\n- `AUTO_MODE` *(available from 26.5.0.cl)*: automatically discovers and selects the most relevant datasets for the user's queries.\n\n> **Note for callers on versions 26.2.0.cl – 26.4.0.cl (Beta):** use the lowercase `data_source` enum value with the `guid` field instead of the above. Example: `{ \"type\": \"data_source\", \"data_source_context\": { \"guid\": \"<worksheet-id>\" } }`.\n\nThe `conversation_settings` parameter controls which Spotter capabilities are enabled for the conversation:\n\n- `enable_contextual_change_analysis` (default: `true`, **deprecated from 26.2.0.cl**) — always enabled in Spotter 3; setting this to `false` has no effect on versions >= 26.2.0.cl\n- `enable_natural_language_answer_generation` (default: `true`, **deprecated from 26.2.0.cl**) — always enabled in Spotter 3; setting this to `false` has no effect on versions >= 26.2.0.cl\n- `enable_reasoning` (default: `true`, **deprecated from 26.2.0.cl**) — always enabled in Spotter 3; setting this to `false` has no effect on versions >= 26.2.0.cl\n- `enable_save_chat` (default: `false`, *available from 26.5.0.cl*) — enables saving the conversation for later retrieval via conversation history\n\nIf the request is successful, the response includes a unique `conversation_identifier` that must be passed to `sendAgentConversationMessage` or `sendAgentConversationMessageStreaming` to send messages within this conversation. The response also includes `conversation_id` with the same value for backwards compatibility; use `conversation_identifier` for new integrations.\n\n#### Example request\n\n```json\n{\n \"metadata_context\": {\n \"type\": \"DATA_SOURCE\",\n \"data_source_context\": {\n \"data_source_identifier\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\"\n }\n },\n \"conversation_settings\": {}\n}\n```\n\n#### Error responses\n\n| Code | Description |\n| ---- | --------------------------------------------------------------------------------------------------------------------------------------- |\n| 401 | Unauthorized — authentication token is missing, expired, or invalid. |\n| 403 | Forbidden — the authenticated user does not have `CAN_USE_SPOTTER` privilege or lacks view permission on the specified metadata object. |\n\n> ###### Note:\n>\n> - This endpoint was in Beta from 26.2.0.cl through 26.4.0.cl and is Generally Available from version 26.5.0.cl.\n> - This endpoint requires Spotter - please contact ThoughtSpot support to enable Spotter on your cluster.\n\n\n\n\n#### Endpoint URL\n"
tags:
- 26.2.0.cl
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAgentConversationRequest'
required: true
parameters: []
responses:
'200':
description: Common successful response
content:
application/json:
schema:
$ref: '#/components/schemas/AgentConversation'
examples:
example_1:
summary: Create a conversation with a specific data source
value:
conversation_id: wwHQ5j8O8dQC
conversation_identifier: wwHQ5j8O8dQC
example_2:
summary: Create a conversation using auto mode where the agent automatically discovers and selects the most relevant datasets for the user's queries
value:
conversation_id: aaHQ5j8O8dQC
conversation_identifier: aaHQ5j8O8dQC
'201':
description: Common error response
content:
application/json:
schema:
$ref: '#/components/schemas/AgentConversation'
'400':
description: Operation failed
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized access.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden access.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Operation failed
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/api/rest/2.0/ai/agent/{conversation_identifier}/converse:
post:
operationId: sendAgentMessage
description: '
<span class="since-beta-tag">Beta</span> <span class="since-beta-tag">Version: 26.2.0.cl or later</span>
**Deprecated** — Use `sendAgentConversationMessage` instead.
Send natural language messages to an existing Spotter agent conversation and returns the complete response synchronously.
Requires `CAN_USE_SPOTTER` privilege and access to the metadata object associated with the conversation. The user must have access to the conversation session referenced by `conversation_identifier`.
A conversation must first be created using the `createAgentConversation` API.
#### Usage guidelines
The request must include:
- `conversation_identifier`: the unique session ID returned by `createAgentConversation`, used for context continuity and message tracking
- `messages`: an array of one or more text messages to send to the agent
The API returns an array of response objects, each containing:
- `type`: the kind of response — `text`, `answer`, or `error`
- `message`: the main content of the response
- `metadata`: additional information depending on the message type (e.g., answer metadata includes analytics and visualization details)
#### Error responses
| Code | Description |
|------|----------------------------------------------------------------------------------------------------------------------------------|
| 401 | Unauthorized — authentication token is missing, expired, or invalid. |
| 403 | Forbidden — the authenticated user does not have `CAN_USE_SPOTTER` privilege or lacks permission on the referenced conversation. |
> ###### Note:
>
> - This endpoint is deprecated. Use `sendAgentConversationMessage` for new integrations.
> - This endpoint is currently in Beta. Breaking changes may be introduced before the endpoint is made Generally Available.
> - This endpoint requires Spotter - please contact ThoughtSpot support to enable Spotter on your cluster.
#### Endpoint URL
'
deprecated: true
tags:
- 26.2.0.cl
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SendAgentMessageRequest'
required: true
parameters:
- in: path
name: conversation_identifier
required: true
schema:
type: string
description: Unique identifier for the conversation (used to track context)
responses:
'200':
description: Common successful response
content:
application/json:
schema:
type: object
'201':
description: Common error response
content:
application/json:
schema:
type: object
'400':
description: Operation failed
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized access.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden access.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Operation failed
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/api/rest/2.0/ai/agent/converse/sse:
post:
operationId: sendAgentMessageStreaming
description: '
<span class="since-beta-tag">Beta</span> <span class="since-beta-tag">Version: 26.2.0.cl or later</span>
**Deprecated** — Use `sendAgentConversationMessageStreaming` instead.
Sends one or more natural language messages to an existing Spotter agent conversation and returns the response as a real-time Server-Sent Events stream.
Requires `CAN_USE_SPOTTER` privilege and access to the metadata object associated with the conversation. The user must have access to the conversation session referenced by `conversation_identifier`. A conversation must first be created using the `createAgentConversation` API.
#### Usage guidelines
The request must include:
- `conversation_identifier`: the unique session ID returned by `createAgentConversation`, used for context continuity and message tracking
- `messages`: an array of one or more text messages to send to the agent
If the request is valid, the API returns a Server-Sent Events (SSE) stream. Each line has the form `data: [{"type": "...", ...}]` — a JSON array of event objects. Event types include:
- `ack`: confirms receipt of the request (`node_id`)
- `conv_title`: conversation title (`title`, `conv_id`)
- `notification`: status updates on operations (`group_id`, `metadata`, `code` — e.g. `TOOL_CALL_NOTIFICATION`, `nls_start`, `FINAL_RESPONSE_NOTIFICATION`)
- `text-chunk`: incremental content chunks (`id`, `group_id`, `metadata` with `format` and `type` such as `thinking` or `text`, `content`)
- `text`: full text block with same structure as `text-chunk`
- `answer`: structured answer with metadata (`id`, `group_id`, `metadata` with `sage_query`, `session_id`, `title`, etc., `title`)
- `error`: if a failure occurs
#### Error responses
| Code | Description |
|------|----------------------------------------------------------------------------------------------------------------------------------|
| 401 | Unauthorized — authentication token is missing, expired, or invalid. |
| 403 | Forbidden — the authenticated user does not have `CAN_USE_SPOTTER` privilege or lacks permission on the referenced conversation. |
> ###### Note:
>
> - This endpoint is deprecated. Use `sendAgentConversationMessageStreaming` for new integrations.
> - This endpoint is currently in Beta. Breaking changes may be introduced before the endpoint is made Generally Available.
> - This endpoint requires Spotter - please contact ThoughtSpot support to enable Spotter on your cluster.
> - The streaming protocol uses Server-Sent Events (SSE).
#### Endpoint URL
'
deprecated: true
tags:
- 26.2.0.cl
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SendAgentMessageStreamingRequest'
required: true
parameters: []
responses:
'200':
description: Common successful response
content:
application/json:
schema:
$ref: '#/components/schemas/SendAgentMessageResponse'
'201':
description: Common error response
content:
application/json:
schema:
$ref: '#/components/schemas/SendAgentMessageResponse'
'400':
description: Operation failed
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized access.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden access.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Operation failed
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-streaming: true
/api/rest/2.0/connections/{connection_identifier}/revoke-refresh-tokens:
post:
operationId: revokeRefreshTokens
description: "\n <span class=\"since-beta-tag\">Version: 26.2.0.cl or later</span>\n\nRevokes OAuth refresh tokens for users who no longer require access to a data warehouse connection.\nWhen a token is revoked, the affected user's session for that connection is terminated, and they must re-authenticate to regain access.\n\nRequires `ADMINISTRATION` (**Can administer ThoughtSpot**) or `DATAMANAGEMENT` (**Can manage data**) privileges.\nIf [Role-Based Access Control (RBAC)](https://developers.thoughtspot.com/docs/rbac) is enabled on the ThoughtSpot instance, users with `CAN_CREATE_OR_EDIT_CONNECTIONS` (**Can create/edit Connections**) privilege can also make API requests to revoke tokens for connection users.\n\n#### Usage guidelines\n\nYou can specify different combinations of identifiers to control which refresh tokens are revoked.\n\n- **connection_identifier**: Revokes refresh tokens for all users of the connection, except the connection author.\n- **connection_identifier** and **user_identifiers**: Revokes refresh tokens only for the users specified in the request. If the name or ID of the connection author is included in the request, their token will also be revoked.\n- **connection_identifier** and **configuration_identifiers**: Revokes refresh tokens for all users on the specified configurations, except the configuration author.\n- **connection_identifier**, **configuration_identifiers**, and **user_identifiers**: Revokes refresh tokens for the specified users on the specified configurations.\n- **connection_identifier** and **org_identifiers**: Revokes refresh tokens for the specified Orgs. Applicable only for published connections.\n- **connection_identifier**, **org_identifiers**, and **user_identifiers**: Revokes refresh tokens for the specified users in the specified Orgs. Applicable only for published connections.\n\n**NOTE**: The `org_identifiers` parameter is only applicable for published connections. Using this parameter for unpublished connections will result in an error. Ensure that the connections are published before making the API request.\n\n\n\n\n#### Endpoint URL\n"
tags:
- 26.2.0.cl
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RevokeRefreshTokensRequest'
required: true
parameters:
- in: path
name: connection_identifier
required: true
schema:
type: string
description: Unique ID or name of the connection whose refresh tokens need to be revoked. All the users associated with the connection will have their refresh tokens revoked except the author.
responses:
'200':
description: Token(s) successfully revoked.
content:
application/json:
schema:
$ref: '#/components/schemas/RevokeRefreshTokensResponse'
'400':
description: Invalid request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized access.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden access.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Object not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'409':
description: Conflict
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/api/rest/2.0/system/security-settings/configure:
post:
operationId: configureSecuritySettings
description: "\n <span class=\"since-beta-tag\">Version: 26.2.0.cl or later</span>\n\nConfigure security settings for your ThoughtSpot application instance.\n- Use `cluster_preferences` to update cluster-level security settings including CORS whitelisted URLs, CSP settings, SAML redirect URLs, partitioned cookies, and non-embed access configuration.\n- Use `org_preferences` to configure Org-specific security settings. If your instance has [Orgs](https://docs.thoughtspot.com/cloud/latest/orgs-overview), this allows configuring CORS and non-embed access settings specific to the Org.\n\nRequires `ADMINISTRATION` (**Can administer ThoughtSpot**) or `DEVELOPER` (**Has developer privilege**) privilege. Cluster-level SAML and script-src settings require `ADMINISTRATION` privilege.\nSee [Security Settings](https://developers.thoughtspot.com/docs/security-settings) for more details.\n\n\n\n#### Endpoint URL\n"
tags:
- 26.2.0.cl
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ConfigureSecuritySettingsRequest'
required: true
parameters: []
responses:
'204':
description: Successfully configured the security settings.
'400':
description: Invalid request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
invalid_request:
summary: Invalid request
value:
error:
message:
code: 10002
incident_id_guid: a1b2c3d4-e5f6-7890-abcd-ef1234567890
trace_id_guid: a1b2c3d4-e5f6-7890-abcd-ef1234567890
debug: groups_identifiers_with_access can only be set when block_full_app_access is true.
'401':
description: Unauthorized access.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
unauthorized_access:
summary: Unauthorized access
value:
error:
message:
code: 10097
incident_id_guid: b2c3d4e5-f678-9012-bcde-f23456789012
trace_id_guid: b2c3d4e5-f678-9012-bcde-f23456789012
debug: Authentication required to configure security settings.
'403':
description: Forbidden access.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
forbidden_access:
summary: Forbidden access
value:
error:
message:
code: 10023
incident_id_guid: c3d4e5f6-7890-1234-cdef-345678901234
trace_id_guid: c3d4e5f6-7890-1234-cdef-345678901234
debug: ADMINISTRATION privilege required to configure cluster-level security settings.
'500':
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
unexpected_error:
summary: Unexpected error
value:
error:
message:
code: 10038
incident_id_guid: d4e5f678-9012-3456-defa-456789012345
trace_id_guid: d4e5f678-9012-3456-defa-456789012345
debug: Unexpected server error while configuring security settings.
/api/rest/2.0/system/security-settings/search:
post:
operationId: searchSecuritySettings
description: "\n <span class=\"since-beta-tag\">Version: 26.2.0.cl or later</span>\n\nFetch security settings for your ThoughtSpot application instance.\n- Use `scope: CLUSTER` to retrieve cluster-level security settings, including CORS and CSP allowlists, SAML redirect URLs, and settings that control access to non-embedded pages.\n- Use `scope: ORG` to retrieve Org-level security settings. If your instance has [Orgs](https://docs.thoughtspot.com/cloud/latest/orgs-overview), this returns CORS and non-embed access settings specific to the Org.\n- If `scope` is not specified, returns both cluster and Org-specific settings based on user privileges.\n\nRequires `ADMINISTRATION` (**Can administer ThoughtSpot**) or `DEVELOPER` (**Has developer privilege**) privilege.\nSee [Security Settings](https://developers.thoughtspot.com/docs/security-settings) for more details.\n\n\n\n#### Endpoint URL\n"
tags:
- 26.2.0.cl
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SearchSecuritySettingsRequest'
required: true
parameters: []
responses:
'200':
description: Successfully retrieved the list of security settings.
content:
application/json:
schema:
$ref: '#/components/schemas/SecuritySettingsResponse'
examples:
example_1:
value:
cluster_preferences:
enable_partitioned_cookies: false
cors_whitelisted_urls:
- example.com
csp_settings:
connect_src_urls:
- https://connect.example.com
font_src_urls:
- https://font.example.com
visual_embed_hosts:
- https://embed.example.com
iframe_src_urls:
- https://embed.example.com
img_src_urls:
- https://img.example.com
script_src_urls:
enabled: true
urls:
- https://script.example.com
style_src_urls:
- https://style.example.com
saml_redirect_urls:
- https://saml.example.com
non_embed_access:
block_full_app_access: true
org_preferences:
- org:
id: 0
name: Primary
cors_whitelisted_urls:
- https://cors.example.com
non_embed_access:
block_full_app_access: true
groups_with_access:
- id: '1234567890'
name: Group Name
'400':
description: Invalid request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
invalid_request:
summary: Invalid request
value:
error:
message:
code: 10002
incident_id_guid: a1b2c3d4-e5f6-7890-abcd-ef1234567890
trace_id_guid: a1b2c3d4-e5f6-7890-abcd-ef1234567890
debug: scope must be one of CLUSTER or ORG.
'401':
description: Unauthorized access.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
unauthorized_access:
summary: Unauthorized access
value:
error:
message:
code: 10097
incident_id_guid: b2c3d4e5-f678-9012-bcde-f23456789012
trace_id_guid: b2c3d4e5-f678-9012-bcde-f23456789012
debug: Authentication required to retrieve security settings.
'403':
description: Forbidden access.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
forbidden_access:
summary: Forbidden access
value:
error:
message:
code: 10023
incident_id_guid: c3d4e5f6-7890-1234-cdef-345678901234
trace_id_guid: c3d4e5f6-7890-1234-cdef-345678901234
debug: ADMINISTRATION privilege required to retrieve cluster-level security settings.
'500':
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
unexpected_error:
summary: Unexpected error
value:
error:
message:
code: 10038
incident_id_guid: d4e5f678-9012-3456-defa-456789012345
trace_id_guid: d4e5f678-9012-3456-defa-456789012345
debug: Unexpected server error while retrieving security settings.
components:
schemas:
SecuritySettingsClusterPreferences:
type: object
properties:
enable_partitioned_cookies:
type: boolean
description: Support embedded access when third-party cookies are blocked.
nullable: true
cors_whitelisted_urls:
type: array
items:
type: string
description: Allowed origins for CORS.
nullable: true
csp_settings:
$ref: '#/components/schemas/CspSettings'
description: CSP (Content Security Policy) settings.
nullable: true
saml_redirect_urls:
type: array
items:
type: string
description: Allowed redirect hosts for SAML login.
nullable: true
non_embed_access:
$ref: '#/components/schemas/ClusterNonEmbedAccess'
description: Non-embed access configuration at cluster level.
nullable: true
trusted_auth_status:
type: string
enum:
- ENABLED
- DISABLED
description: 'Trusted authentication status at the cluster level. <br/> <span class="since-beta-tag">Version: 26.6.0.cl or later</span>'
nullable: true
description: Cluster-level security preferences.
ScriptSrcUrlsInput:
type: object
properties:
enabled:
type: boolean
description: Whether script-src customization is enabled.
nullable: true
urls:
type: array
items:
type: string
description: Allowed URLs for script-src directive. Can only be set if enabled is true.
nullable: true
description: Input for script-src CSP settings.
AgentConversation:
type: object
required:
- conversation_id
- conversation_identifier
properties:
conversation_id:
type: string
description: Unique identifier of the conversation.
conversation_identifier:
type: string
description: 'Unique identifier of the conversation. <br/> <span class="since-beta-tag">Version: 26.5.0.cl or later</span>'
SecuritySettingsClusterPreferencesInput:
type: object
properties:
enable_partitioned_cookies:
type: boolean
description: Support embedded access when third-party cookies are blocked.
nullable: true
cors_whitelisted_urls:
type: array
items:
type: string
description: Allowed origins for CORS.
nullable: true
csp_settings:
$ref: '#/components/schemas/CspSettingsInput'
description: CSP (Content Security Policy) settings.
nullable: true
saml_redirect_urls:
type: array
items:
type: string
description: Allowed redirect hosts for SAML login.
nullable: true
non_embed_access:
$ref: '#/components/schemas/ClusterNonEmbedAccessInput'
description: Non-embed access configuration at cluster level.
nullable: true
description: Input for cluster-level security preferences configuration.
GroupInfo:
type: object
properties:
id:
type: string
description: Unique identifier of the group.
nullable: true
name:
type: string
description: Name of the group.
nullable: true
description: Group information for non-embed access.
CreateAgentConversationRequest:
type: object
properties:
metadata_context:
description: Context for the conversation.
allOf:
- $ref: '#/components/schemas/ContextPayloadV2Input'
conversation_settings:
description: Conversation settings.
allOf:
- $ref: '#/components/schemas/ConversationSettingsInput'
required:
- metadata_context
- conversation_settings
SendAgentMessageStreamingRequest:
type: object
properties:
conversation_identifier:
description: Unique identifier for the conversation (used to track context)
type: string
messages:
description: messages to be sent to the agent
type: array
items:
type: string
required:
- conversation_identifier
- messages
Error
# --- truncated at 32 KB (48 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/thoughtspot/refs/heads/main/openapi/thoughtspot-26-2-0-cl-api-openapi.yml