openapi: 3.0.0
info:
title: ThoughtSpot Public REST 10.1.0.cl 10.4.0.cl API
version: '2.0'
servers:
- url: '{base-url}'
variables:
base-url:
default: https://localhost:443
security:
- bearerAuth: []
tags:
- name: 10.4.0.cl
paths:
/api/rest/2.0/ai/conversation/create:
post:
operationId: createConversation
description: '
<span class="since-beta-tag">Beta</span> <span class="since-beta-tag">Version: 10.4.0.cl or later</span>
<span class="since-beta-tag">Version: 10.4.0.cl or later</span>
Creates a new conversation session tied to a specific data model for AI-driven natural language querying.
Requires `CAN_USE_SPOTTER` privilege and at least view access to the metadata object specified in the request.
#### Usage guidelines
The request must include:
- `metadata_identifier`: the unique ID of the data source that provides context for the conversation
Optionally, you can provide:
- `tokens`: a token string to set initial context for the conversation (e.g., `"[sales],[item type],[state]"`)
If the request is successful, ThoughtSpot returns a unique `conversation_identifier` that must be passed to `sendMessage` to continue the conversation.
#### 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 view permission on the specified metadata object. |
> ###### Note:
> * 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
'
tags:
- 10.4.0.cl
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateConversationRequest'
required: true
parameters: []
responses:
'200':
description: Common successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Conversation'
'201':
description: Common error response
content:
application/json:
schema:
$ref: '#/components/schemas/Conversation'
'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/conversation/{conversation_identifier}/converse:
post:
operationId: sendMessage
description: '
<span class="since-beta-tag">Beta</span> <span class="since-beta-tag">Version: 10.4.0.cl or later</span>
Sends a follow-up message to an existing conversation within the context of a data model.
Requires `CAN_USE_SPOTTER` privilege and at least view access to the metadata object specified in the request. A conversation must first be created using the `createConversation` API.
#### Usage guidelines
The request must include:
- `conversation_identifier`: the unique session ID returned by `createConversation`
- `metadata_identifier`: the unique ID of the data source used for the conversation
- `message`: a natural language string with the follow-up question
If the request is successful, the API returns an array of response messages, each containing:
- `session_identifier`: the unique ID of the generated response
- `generation_number`: the generation number of the response
- `message_type`: the type of the response (e.g., `TSAnswer`)
- `visualization_type`: the generated visualization type (`Chart`, `Table`, or `Undefined`)
- `tokens` / `display_tokens`: the search tokens and user-friendly display tokens for the response
#### 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 view permission on the specified metadata object. |
> ###### Note:
> * 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
'
tags:
- 10.4.0.cl
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SendMessageRequest'
required: true
parameters:
- in: path
name: conversation_identifier
required: true
schema:
type: string
description: Unique identifier of the conversation.
responses:
'200':
description: Common successful response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ResponseMessage'
'201':
description: Common error response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ResponseMessage'
'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/answer/create:
post:
operationId: singleAnswer
description: '
<span class="since-beta-tag">Beta</span> <span class="since-beta-tag">Version: 10.4.0.cl or later</span>
Processes a natural language query against a specified data model and returns a single AI-generated answer without requiring a conversation session.
Requires `CAN_USE_SPOTTER` privilege and at least view access to the metadata object specified in the request.
#### Usage guidelines
The request must include:
- `query`: a natural language question (e.g., "What were total sales last quarter?")
- `metadata_identifier`: the unique ID of the data source to query against
If the request is successful, the API returns a response message containing:
- `session_identifier`: the unique ID of the generated response
- `generation_number`: the generation number of the response
- `message_type`: the type of the response (e.g., `TSAnswer`)
- `visualization_type`: the generated visualization type (`Chart`, `Table`, or `Undefined`)
- `tokens` / `display_tokens`: the search tokens and user-friendly display tokens for the response
#### 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 view permission on the specified metadata object. |
> ###### Note:
> * 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
'
tags:
- 10.4.0.cl
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SingleAnswerRequest'
required: true
parameters: []
responses:
'200':
description: Common successful response
content:
application/json:
schema:
$ref: '#/components/schemas/ResponseMessage'
'201':
description: Common error response
content:
application/json:
schema:
$ref: '#/components/schemas/ResponseMessage'
'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/auth/token/custom:
post:
operationId: getCustomAccessToken
description: "\n <span class=\"since-beta-tag\">Version: 10.4.0.cl or later</span>\n\nCreates an authentication token that provides values for the formula variables in the Row Level Security (RLS) rules for a given user. Recommended for use cases that require Attribute-based access control (ABAC) via RLS.\n\n#### Required privileges\n\nTo add a new user and assign privileges during auto-creation, the `ADMINISTRATION` (**Can administer ThoughtSpot**) privilege is required. If [Role-Based Access Control (RBAC)](https://developers.thoughtspot.com/docs/rbac) is enabled, the `CONTROL_TRUSTED_AUTH` (**Can Enable or Disable Trusted Authentication**) privilege and edit access to the data source are required.\n\nTo configure formula variables for all Orgs on your instance or the Primary Org, cluster administration privileges are required. Org administrators can configure formula variables for their respective Orgs. If Role-Based Access Control (RBAC) is enabled, users with the `CAN_MANAGE_VARIABLES` (**Can manage variables**) role privilege can also create and manage variables for their Org context.\n\n#### Usage guidelines\n\nYou can generate a token by providing a `username` and `password`, or by using a `secret_key`. To generate a `secret_key`, the administrator must enable [Trusted authentication](https://developers.thoughtspot.com/docs/trusted-auth-secret-key) in the **Develop** > **Customizations** > **Security Settings** page.\n\n**Note**:\n* When both `password` and `secret_key` are included in the API request, `password` takes precedence.\n* If [Multi-Factor Authentication (MFA)](https://docs.thoughtspot.com/cloud/latest/authentication-local-mfa) is enabled on your instance, the API login request with `username` and `password` returns an error. You can switch to token-based authentication with `secret_key` or contact ThoughtSpot Support for assistance.\n\nThe token obtained from ThoughtSpot is valid for 5 minutes by default. You can configure the token expiration time as required.\n\n#### ABAC via RLS\n\nTo implement ABAC via RLS and assign security entitlements to users during session creation, generate a token with custom variable values. The values set in the authentication token are applied to the formula variables referenced in RLS rules at the table level, which determines the data each user can access based on their entitlements.\n\nThe variable values can be configured to persist for a specific set of Models in user sessions initiated with the token, allowing different RLS rules to be set for different data models. Once defined, the rules are added to the user's `variable_values` object, after which all sessions will use the persisted values.\n\nFor more information, see [ABAC via tokens Documentation](https://developers.thoughtspot.com/docs/abac-via-rls-variables).\n\n##### Formula variables\nBefore defining variable values, ensure the variables are created and available on your instance. To create a formula variable, you can use the **Create variable** (`/api/rest/2.0/template/variables/create`) REST API endpoint, with the variable `type` set as `Formula_Variable` in the API request.\n\nThe API doesn't support `\"persist_option\": \"RESET\"` and `\"persist_option\": \"NONE\"` when `variable_values` are defined in the request. If you are using `variable_values` for token generation, you must use other supported persist options such as `APPEND` or `REPLACE`.\n\nIf you want to use `RESET` or `NONE`, do not pass any `variable_values`. In such cases, `variable_values` will remain unaffected.\n\n#### Supported objects\n\nThe supported object type is `LOGICAL_TABLE`. When using `object_id` with `variable_values`, models are supported.\n\n#### Just-in-time provisioning\n\nFor [just-in-time user creation and provisioning](https://developers.thoughtspot.com/docs/just-in-time-provisioning), specify the following attributes in the API request:\n\n* `auto_create`\n* `username`\n* `display_name`\n* `email`\n* `groups`\n\nSet `auto_create` to `true` if the username does not exist in ThoughtSpot. If the username already exists in ThoughtSpot and `auto_create` is set to `true`, user properties such as display name, email, Org and group entitlements will not be updated with new values. Setting `auto_create` to `true` does not create formula variables. Hence, this setting will not be applicable to `variable_values`.\n\n#### Important point to note\nAll options in the token creation APIs that define user access to data in ThoughtSpot will take effect during token creation, not when the token is used for authentication. For example, `auto_create:true` will create the user when the authentication token is created. Persist options such as `APPEND` and `REPLACE` will persist `variable_values` on the user profile when the token is created.\n\n\n\n\n#### Endpoint URL\n"
tags:
- 10.4.0.cl
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/GetCustomAccessTokenRequest'
required: true
parameters: []
responses:
'200':
description: ABAC token creation was successful.
content:
application/json:
schema:
$ref: '#/components/schemas/AccessToken'
examples:
example_1:
description: Custom access token with variable values and APPEND persist option for an existing user
value:
id: 9f8e7d6c-5b4a-3210-fedc-ba9876543210
token: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.example_custom_token.signature
org:
id: 0
name: Primary
user:
id: 59481331-ee53-42be-a548-bd87be6ddd4a
name: analyst_user
creation_time_in_millis: 1724277430000
expiration_time_in_millis: 1724277730000
example_2:
description: Custom access token with variable values for a JIT-provisioned user
value:
id: 1a2b3c4d-5e6f-7890-abcd-ef1234567890
token: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.example_jit_custom_token.signature
org:
id: 1
name: SalesOrg
user:
id: 3f2e1d4c-9b8a-7e6f-5d4c-3b2a1e0f9d8c
name: new_sales_user@example.com
creation_time_in_millis: 1724278000000
expiration_time_in_millis: 1724278300000
'400':
description: Invalid request. This could be due to missing or incorrect parameters.
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: 'Invalid persistOption: ''APPEND''. Expected: ''RESET'' when resetOption is provided.'
'401':
description: Unauthorized access. The request could not be authenticated.
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: Invalid credentials. The provided secret key or password is incorrect.
'403':
description: Forbidden access. The user does not have permission to access this resource.
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: Trusted authentication is not enabled for this cluster or org.
'409':
description: Conflict. A concurrent update to the same template variable was detected and the request could not be applied. Retry the request after serializing concurrent variable updates.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: An unexpected error occurred on the server.
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 generating the custom access token.
security: []
/api/rest/2.0/connections/{connection_identifier}/delete:
post:
operationId: deleteConnectionV2
description: "\n <span class=\"since-beta-tag\">Version: 10.4.0.cl or later</span>\n\nDeletes a connection object.\n\n**Note**: If a connection has dependent objects, make sure you remove its associations before the delete operation.\n\nRequires `DATAMANAGEMENT` (**Can manage data**) and edit permissions to the connection object, or `ADMINISTRATION` (**Can administer ThoughtSpot**) privilege.\nIf [Role-Based Access Control (RBAC)](https://developers.thoughtspot.com/docs/rbac) is enabled on your instance, the `CAN_CREATE_OR_EDIT_CONNECTIONS` (**Can create/edit Connections**) privilege is required.\n\n\n\n\n#### Endpoint URL\n"
tags:
- 10.4.0.cl
parameters:
- in: path
name: connection_identifier
required: true
schema:
type: string
description: Unique ID or name of the connection.
responses:
'204':
description: Connection successfully deleted.
'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'
'500':
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/api/rest/2.0/connections/{connection_identifier}/update:
post:
operationId: updateConnectionV2
description: "\n <span class=\"since-beta-tag\">Version: 10.4.0.cl or later</span>\n\nUpdates a connection object.\n\nRequires `DATAMANAGEMENT` (**Can manage data**) and edit permissions to the connection object, or `ADMINISTRATION` (**Can administer ThoughtSpot**) privilege.\nIf [Role-Based Access Control (RBAC)](https://developers.thoughtspot.com/docs/rbac) is enabled on your instance, the `CAN_CREATE_OR_EDIT_CONNECTIONS` (**Can create/edit Connections**) privilege is required.\n\nTo update a connection object, pass these parameters in your API request:\n\n1. GUID of the connection object.\n2. If you are updating tables or database schema of a connection object:\n a. Add the updated JSON map of metadata with database, schema, and tables in `data_warehouse_config`.\n b. Set `validate` to `true`.\n \n **NOTE:** If the `authentication_type` is anything other than SERVICE_ACCOUNT, you must explicitly provide the authenticationType property in the payload. If you do not specify authenticationType, the API will default to SERVICE_ACCOUNT as the authentication type.\n\n * A JSON map of configuration attributes, database details, and table properties in `data_warehouse_config` as shown in the following example:\n * This is an example of updating a single table in a empty connection:\n \n ```\n {\n \"authenticationType\": \"SERVICE_ACCOUNT\",\n \"databases\": [\"DB2\", \"DB3\", \"DEVELOPMENT\"],\n \"externalDatabases\": [\n {\n \"name\": \"DEVELOPMENT\",\n \"isAutoCreated\": false,\n \"schemas\": [\n {\n \"name\": \"TS_dataset\",\n \"tables\": [\n {\n \"name\": \"DEMORENAME\",\n \"type\": \"TABLE\",\n \"description\": \"\",\n \"selected\": true,\n \"linked\": true,\n \"gid\": 0,\n \"datasetId\": \"-1\",\n \"subType\": \"\",\n \"reportId\": \"\",\n \"viewId\": \"\",\n \"columns\": [\n {\n \"name\": \"Col1\",\n \"type\": \"VARCHAR\",\n \"canImport\": true,\n \"selected\": true,\n \"description\": \"\",\n \"isLinkedActive\": true,\n \"isAggregate\": false\n },\n {\n \"name\": \"Col2\",\n \"type\": \"VARCHAR\",\n \"canImport\": true,\n \"selected\": true,\n \"description\": \"\",\n \"isLinkedActive\": true,\n \"isAggregate\": false\n },\n {\n \"name\": \"Col3\",\n \"type\": \"VARCHAR\",\n \"canImport\": true,\n \"selected\": true,\n \"description\": \"\",\n \"isLinkedActive\": true,\n \"isAggregate\": false\n },\n {\n \"name\": \"Col312\",\n \"type\": \"VARCHAR\",\n \"canImport\": true,\n \"selected\": true,\n \"description\": \"\",\n \"isLinkedActive\": true,\n \"isAggregate\": false\n },\n {\n \"name\": \"Col4\",\n \"type\": \"VARCHAR\",\n \"canImport\": true,\n \"selected\": true,\n \"description\": \"\",\n \"isLinkedActive\": true,\n \"isAggregate\": false\n }\n ],\n \"relationships\": []\n }\n ]\n }\n ]\n }\n ],\n \"configuration\": {\n \"password\": \"\",\n \"database\": \"DEVELOPMENT\",\n \"role\": \"DEV\",\n \"accountName\": \"thoughtspot_partner\",\n \"warehouse\": \"DEMO_WH\",\n \"user\": \"DEV_USER\"\n }\n }\n ```\n \n* This is an example of updating a single table in an existing connection with tables:\n \n ```\n {\n \"authenticationType\": \"SERVICE_ACCOUNT\",\n \"databases\": [\"DB2\", \"DB3\", \"DEVELOPMENT\"],\n \"externalDatabases\": [\n {\n \"name\": \"DEVELOPMENT\",\n \"isAutoCreated\": false,\n \"schemas\": [\n {\n \"name\": \"TS_dataset\",\n \"tables\": [\n {\n \"name\": \"CUSTOMER\",\n \"type\": \"TABLE\",\n \"description\": \"\",\n \"selected\": true,\n \"linked\": true,\n \"gid\": 0,\n \"datasetId\": \"-1\",\n \"subType\": \"\",\n \"reportId\": \"\",\n \"viewId\": \"\",\n \"columns\": [],\n \"relationships\": []\n },\n {\n \"name\": \"tpch5k_falcon_default_schema_users\",\n \"type\": \"TABLE\",\n \"description\": \"\",\n \"selected\": true,\n \"linked\": true,\n \"gid\": 0,\n \"datasetId\": \"-1\",\n \"subType\": \"\",\n \"reportId\": \"\",\n \"viewId\": \"\",\n \"columns\": [\n {\n \"name\": \"user_id\",\n \"type\": \"INT64\",\n \"canImport\": true,\n \"selected\": true,\n \"description\": \"\",\n \"isLinkedActive\": true,\n \"isAggregate\": false\n },\n {\n \"name\": \"product_id\",\n \"type\": \"INT64\",\n \"canImport\": true,\n \"selected\": true,\n \"description\": \"\",\n \"isLinkedActive\": true,\n \"isAggregate\": false\n },\n {\n \"name\": \"user_cost\",\n \"type\": \"INT64\",\n \"canImport\": true,\n \"selected\": true,\n \"description\": \"\",\n \"isLinkedActive\": true,\n \"isAggregate\": false\n }\n ],\n \"relationships\": []\n }\n ]\n }\n ]\n }\n ],\n \"configuration\": {\n \"password\": \"\",\n \"database\": \"DEVELOPMENT\",\n \"role\": \"DEV\",\n \"accountName\": \"thoughtspot_partner\",\n \"warehouse\": \"DEMO_WH\",\n \"user\": \"DEV_USER\"\n }\n }\n ```\n\n3. If you are updating a configuration attribute, connection name, or description, you can set `validate` to `false`.\n\n **NOTE:** If the `authentication_type` is anything other than SERVICE_ACCOUNT, you must explicitly provide the authenticationType property in the payload. If you do not specify authenticationType, the API will default to SERVICE_ACCOUNT as the authentication type.\n\n * A JSON map of configuration attributes in `data_warehouse_config`. The following example shows the configuration attributes for a Snowflake connection:\n ```\n {\n \"configuration\":{\n \"accountName\":\"thoughtspot_partner\",\n \"user\":\"tsadmin\",\n \"password\":\"TestConn123\",\n \"role\":\"sysadmin\",\n \"warehouse\":\"MEDIUM_WH\"\n },\n \"databases\":[\"DB1\", \"DB2\"],\n \"externalDatabases\":[\n\n ]\n }\n ```\n\nThe optional `databases` property in `data_warehouse_config` accepts a list of database names. When specified, ThoughtSpot persists this list on the connection and uses it to scope metadata fetching to only the specified databases in subsequent table add and remove operations. If omitted, all databases in the data warehouse are accessible for metadata operations.\n\nThe `databases` and `externalDatabases` serve different purposes. `databases` is a flat list of database names that controls which databases are scanned during metadata operations. `externalDatabases` defines the full table hierarchy and determines which tables are linked into ThoughtSpot.\n\n\n\n\n\n#### Endpoint URL\n"
tags:
- 10.4.0.cl
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateConnectionV2Request'
required: true
parameters:
- in: path
name: connection_identifier
required: true
schema:
type: string
description: Unique ID or name of the connection.
responses:
'204':
description: Connection successfully updated.
'400':
description: Invalid request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized access.
content
# --- truncated at 32 KB (56 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/thoughtspot/refs/heads/main/openapi/thoughtspot-10-4-0-cl-api-openapi.yml