openapi: 3.0.0 info: title: ThoughtSpot Public REST 10.1.0.cl 26.6.0.cl API version: '2.0' servers: - url: '{base-url}' variables: base-url: default: https://localhost:443 security: - bearerAuth: [] tags: - name: 26.6.0.cl paths: /api/rest/2.0/ai/agent/instructions/get: get: operationId: getAgentInstructions description: ' Beta Version: 26.6.0.cl or later Retrieves the admin instructions currently configured for the AI agent (Spotter). Admin instructions are tenant- and org-scoped text that guide agent behavior across all conversations. Requires admin privileges. Only users with org admin access can retrieve agent instructions. #### Usage guidelines No input parameters are required. The API returns the stored `AgentInstructions` record for the caller''s tenant and org. If no instructions have been configured yet, the API returns a record with an empty `instructions` field and `null` values for `id`, `created_at`, `updated_at`, and `last_updated_by`. If the request is successful, the response includes: - `id`: unique identifier of the instructions record - `instructions`: the configured instructions text - `created_at`: ISO timestamp when the instructions were first saved - `updated_at`: ISO timestamp when the instructions were last updated - `last_updated_by`: user ID of the admin who last updated the instructions (may be `null` for older records) #### Error responses | Code | Description | |------|-------------| | 401 | Unauthorized — authentication token is missing, expired, or invalid. | | 403 | Forbidden — the authenticated user does not have org admin privileges required to read agent instructions. | > ###### Note: > > - Use `setAgentInstructions` to create or update agent instructions. > - Available from version 26.6.0.cl and later. #### Endpoint URL ' tags: - 26.6.0.cl parameters: [] responses: '200': description: Common successful response content: application/json: schema: $ref: '#/components/schemas/AgentInstructions' '201': description: Common error response content: application/json: schema: $ref: '#/components/schemas/AgentInstructions' '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/instructions/set: put: operationId: setAgentInstructions description: ' Beta Version: 26.6.0.cl or later Creates or updates the admin instructions for the AI agent (Spotter). Admin instructions are tenant- and org-scoped text that guide agent behavior across all conversations. If instructions already exist for the org, they are replaced (upsert semantics). Requires admin privileges. Only users with org admin access can set agent instructions. #### Usage guidelines The request must include: - `instructions`: the instructions text to apply to the agent (maximum 5000 characters) Instructions are validated against system guardrails before being saved. If the instructions contain content that conflicts with guardrails, the request is rejected with a `409` error and the existing instructions remain unchanged. If the request is successful, the response includes the saved `AgentInstructions` record: - `id`: unique identifier of the record - `instructions`: the saved instructions text - `created_at`: ISO timestamp when the instructions were first created - `updated_at`: ISO timestamp of this update - `last_updated_by`: user ID of the admin who performed this update #### Error responses | Code | Description | |------|-------------| | 400 | Bad request — the request body is missing required fields or the `instructions` field exceeds the maximum allowed length of 5000 characters. | | 401 | Unauthorized — authentication token is missing, expired, or invalid. | | 403 | Forbidden — the authenticated user does not have org admin privileges required to set agent instructions. | | 409 | Conflict — the provided instructions conflict with system guardrails. Review and revise the instructions text before retrying. | | 500 | Internal server error. | > ###### Note: > > - This operation uses upsert semantics: it creates the instructions record if none exists, or replaces the existing one. > - Instructions take effect immediately for new conversations created after the update. > - Use `getAgentInstructions` to retrieve the current instructions before making changes. > - Available from version 26.6.0.cl and later. #### Endpoint URL ' tags: - 26.6.0.cl requestBody: content: application/json: schema: $ref: '#/components/schemas/SetAgentInstructionsRequest' required: true parameters: [] responses: '200': description: Common successful response content: application/json: schema: $ref: '#/components/schemas/AgentInstructions' '201': description: Common error response content: application/json: schema: $ref: '#/components/schemas/AgentInstructions' '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/{conversation_identifier}/stop-response: post: operationId: stopConversation description: ' Stops an in-progress agent conversation response.
Version: 26.6.0.cl or later Version: 26.6.0.cl or later Stops an in-progress agent response for the specified conversation. Use this endpoint to cancel a response that is actively being generated — for example, when the user navigates away, reformulates their question, or no longer needs the current result. Requires `CAN_USE_SPOTTER` privilege and access to the specified conversation. #### Usage guidelines The request must include: - `conversation_identifier` *(path parameter)*: the unique ID of the conversation whose active response should be stopped, as returned by `createAgentConversation` A successful request returns an empty `204 No Content` response. If there is no active response in progress at the time of the call, the request is still treated as successful. After stopping a response, the conversation session remains active. You can continue sending messages using `sendAgentConversationMessage` or `sendAgentConversationMessageStreaming`. #### Example request ```bash POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response ``` #### Typical usage scenario This endpoint is useful when integrating Spotter into a chat UI where users can cancel a long-running query. For example: 1. User sends a message via `sendAgentConversationMessageStreaming`. 2. User clicks a "Stop generating" button while the response is streaming. 3. Your client calls `stopConversation` with the active `conversation_identifier`. 4. The stream is terminated and the user can ask a new question. #### 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 access to the specified conversation. | > ###### Note: > > - Calling this endpoint when no response is in progress does not return an error. > - The conversation context is preserved after stopping — previous messages and answers remain accessible. > - Available from version 26.6.0.cl and later. > - This endpoint requires Spotter — please contact ThoughtSpot Support to enable Spotter on your cluster. > - This feature is available only for **Spotter 3** (`SPOTTER3`) version. #### Endpoint URL ' tags: - 26.6.0.cl parameters: - in: path name: conversation_identifier required: true schema: type: string description: Unique identifier of the conversation to stop. responses: '204': description: Successfully stopped the in-progress agent conversation response for the given. '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/configure: post: operationId: configureAuthSettings description: "\n Version: 26.6.0.cl or later\n\nVersion: 26.6.0.cl or later\n\nEnables or disables authentication at cluster or org level for the specified auth type. Currently supports `TRUSTED_AUTH`.\n\n#### Required privileges\n\nRequires `ADMINISTRATION` (**Can administer ThoughtSpot**) or `CONTROL_TRUSTED_AUTH` (**Can Enable or Disable Trusted Authentication**) privilege. If [Role-Based Access Control (RBAC)](https://developers.thoughtspot.com/docs/rbac) is enabled, the `CONTROL_TRUSTED_AUTH` privilege is required.\n\n#### Usage guidelines\n\nUse `cluster_preferences` to enable or disable authentication at the cluster level. Cluster-level settings can only be configured from the Primary Org.\n- `ENABLED` — Generates a new access token if one does not exist. An existing token is preserved.\n- `DISABLED` — Revokes the existing cluster-level access token.\n\nUse `org_preferences` to enable or disable authentication for one or more Orgs. Each entry must include an `org_identifier` (unique ID or name) and an `auth_status`. Org-level configuration requires the per-Org authentication feature to be enabled on your instance.\n- `ENABLED` — Generates a new org-level access token if one does not exist.\n- `DISABLED` — Revokes the existing org-level access token for that Org.\n\nBoth `cluster_preferences` and `org_preferences` are optional. Omitting a field leaves the corresponding settings unchanged. If both are omitted, the API returns `204 No Content` without making any changes.\n\n**Note**: Cluster-level and org-level settings are independent of each other. Enabling or disabling one does not affect the other.\n\n\n\n\n#### Endpoint URL\n" tags: - 26.6.0.cl requestBody: content: application/json: schema: $ref: '#/components/schemas/ConfigureAuthSettingsRequest' required: true parameters: [] responses: '204': description: Trusted authentication settings configured successfully. '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: At least one of cluster_preferences or org_preferences must be provided. '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 authentication 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 or CONTROL_TRUSTED_AUTH privilege required to configure authentication 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 authentication settings. /api/rest/2.0/auth/search: post: operationId: searchAuthSettings description: "\n Version: 26.6.0.cl or later\n\nVersion: 26.6.0.cl or later\n\nReturns the authentication configuration for the specified auth type at cluster and org level. Currently supports `TRUSTED_AUTH`.\n\n#### Required privileges\n\nRequires `ADMINISTRATION` (**Can administer ThoughtSpot**) or `CONTROL_TRUSTED_AUTH` (**Can Enable or Disable Trusted Authentication**) privilege. If [Role-Based Access Control (RBAC)](https://developers.thoughtspot.com/docs/rbac) is enabled, the `CONTROL_TRUSTED_AUTH` privilege is required.\n\n#### Usage guidelines\n\nUse `scope` to control which level of settings are returned:\n- `CLUSTER` — Returns cluster-level authentication status and access tokens. Accessible only from the Primary Org.\n- `ORG` — Returns org-level authentication status and access tokens for the current Org. Requires the per-Org authentication feature to be enabled on your instance.\n- If `scope` is omitted, both cluster and org-level settings are returned based on the caller's org context and feature availability.\n\nThe `access_tokens` array in `cluster_preferences` or `org_preferences` is omitted when no token is configured at that level.\n\n**Note**: Access tokens returned in the response are sensitive credentials. Treat them with the same care as passwords.\n\n\n\n\n#### Endpoint URL\n" tags: - 26.6.0.cl requestBody: content: application/json: schema: $ref: '#/components/schemas/SearchAuthSettingsRequest' required: true parameters: [] responses: '200': description: Authentication settings retrieved successfully. content: application/json: schema: $ref: '#/components/schemas/SearchAuthSettingsResponse' examples: example_1: value: auth_type: TRUSTED_AUTH cluster_preferences: auth_status: ENABLED access_tokens: - key: a1b2c3d4-e5f6-7890-abcd-ef1234567890 org_preferences: - org: id: 583464508 name: sales_org auth_status: ENABLED access_tokens: - key: f9e8d7c6-b5a4-3210-fedc-ba9876543210 '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: auth_type must be specified and currently only TRUSTED_AUTH is supported. '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 authentication 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 or CONTROL_TRUSTED_AUTH privilege required to retrieve authentication 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 authentication settings. /api/rest/2.0/connections/{connection_identifier}/status: post: operationId: updateConnectionStatus description: "\n Version: 26.6.0.cl or later\n\nActivates or deactivates a connection. A deactivated connection cannot be used for queries or operations until it is activated again.\n\nRequires `DATAMANAGEMENT` (**Can manage data**) privilege. If [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. Only the connection owner or an administrator can perform this operation.\n\n#### Usage guidelines\n\nTo update the status of a connection, specify the connection GUID or name in the `connection_identifier` path parameter and the desired `status` in the request body.\n\n- **ACTIVATED**: Enables the connection. Queries and operations can resume on an activated connection.\n- **DEACTIVATED**: Disables the connection. It does not remove the connection metadata, but only makes the connection unavailable for queries and operations. You can reactivate a deactivated connection by setting \"status\": \"ACTIVATED\".\n\n\n\n\n\n#### Endpoint URL\n" tags: - 26.6.0.cl requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateConnectionStatusRequest' 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 status updated successfully. '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' '500': description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: SetAgentInstructionsRequest: type: object properties: instructions: description: The admin instructions text to set for the agent. type: string required: - instructions AuthClusterPreferencesInput: type: object properties: auth_status: type: string enum: - ENABLED - DISABLED description: Enable or disable authentication at the cluster level. When enabled, a new token is generated if one does not exist. When disabled, the existing token is revoked. nullable: true description: Input for cluster-level auth configuration. AuthSettingsAccessToken: type: object required: - key properties: key: type: string description: The plaintext token key value. description: An auth settings access token. AuthOrgInfo: type: object required: - id properties: id: type: integer format: int32 description: Unique identifier of the org. name: type: string description: Name of the org. nullable: true description: Org identifier returned in auth settings search results. ConfigureAuthSettingsRequest: type: object properties: auth_type: description: Type of authentication mechanism to configure. Currently supports TRUSTED_AUTH. type: string enum: - TRUSTED_AUTH cluster_preferences: description: Cluster-level authentication preferences. Omit to leave the existing cluster setting unchanged. allOf: - $ref: '#/components/schemas/AuthClusterPreferencesInput' org_preferences: description: Org-level authentication preferences. Each entry identifies an org and the desired status. Omit to leave existing org settings unchanged. type: array items: $ref: '#/components/schemas/AuthOrgPreferenceInput' required: - auth_type AuthClusterPreferences: type: object properties: auth_status: type: string enum: - ENABLED - DISABLED description: Whether authentication is enabled or disabled at the cluster level. nullable: true access_tokens: type: array items: $ref: '#/components/schemas/AuthSettingsAccessToken' description: Cluster-level access tokens. Absent when no token is configured. nullable: true description: Cluster-level authentication preferences. SearchAuthSettingsRequest: type: object properties: auth_type: description: Type of authentication mechanism to retrieve settings for. Currently supports TRUSTED_AUTH. type: string enum: - TRUSTED_AUTH scope: description: Scope of auth settings to retrieve. When absent, both cluster and org settings are returned (subject to caller privileges). Set to CLUSTER to retrieve only cluster-level settings, or ORG to retrieve only org-level settings. type: string enum: - CLUSTER - ORG required: - auth_type AuthOrgPreferenceInput: type: object required: - org_identifier properties: org_identifier: type: string description: Unique ID or name of the org to configure. auth_status: type: string enum: - ENABLED - DISABLED description: Enable or disable authentication for this org. When enabled, a new token is generated if one does not exist. When disabled, the existing token is revoked. nullable: true description: Input for org-level auth configuration. ErrorResponse: type: object properties: error: type: object nullable: true UpdateConnectionStatusRequest: type: object properties: status: description: Status to set for the connection. Use ACTIVATED to enable the connection or DEACTIVATED to disable it. default: ACTIVATED type: string enum: - ACTIVATED - DEACTIVATED SearchAuthSettingsResponse: type: object properties: auth_type: type: string enum: - TRUSTED_AUTH description: Type of authentication mechanism returned. nullable: true cluster_preferences: $ref: '#/components/schemas/AuthClusterPreferences' description: Cluster-level authentication configuration. Present when cluster scope was requested and the caller has ADMINISTRATION or CONTROL_TRUSTED_AUTH privilege. nullable: true org_preferences: type: array items: $ref: '#/components/schemas/AuthOrgPreference' description: Org-level authentication configurations. Present when org scope was requested and per-org auth feature is enabled. nullable: true description: Response for searchAuthSettings. Contains auth type and cluster/org-level preferences. AuthOrgPreference: type: object properties: org: $ref: '#/components/schemas/AuthOrgInfo' description: Org identifier details. nullable: true auth_status: type: string enum: - ENABLED - DISABLED description: Whether authentication is enabled or disabled for this org. nullable: true access_tokens: type: array items: $ref: '#/components/schemas/AuthSettingsAccessToken' description: Org-level access tokens. Absent when no token is configured or the feature flag is off. nullable: true description: Org-level authentication preferences for a single org. AgentInstructions: type: object required: - instructions properties: id: type: string description: Unique identifier of the record. nullable: true instructions: type: string description: The admin instructions text for the agent. created_at: type: string description: ISO timestamp when the instructions were created. nullable: true updated_at: type: string description: ISO timestamp when the instructions were last updated. nullable: true last_updated_by: type: string description: User ID of the admin who last updated the instructions. nullable: true description: Admin instructions configured for the AI agent. securitySchemes: bearerAuth: type: http scheme: bearer x-roles: - name: 26.2.0.cl id: 26.2.0.cl tags: - 26.2.0.cl description: Roles for version 26.2.0.cl - name: 10.4.0.cl id: 10.4.0.cl tags: - 10.4.0.cl description: Roles for version 10.4.0.cl - name: 26.7.0.cl id: 26.7.0.cl tags: - 26.7.0.cl description: Roles for version 26.7.0.cl - name: 26.8.0.cl id: 26.8.0.cl tags: - 26.8.0.cl description: Roles for version 26.8.0.cl - name: 26.6.0.cl id: 26.6.0.cl tags: - 26.6.0.cl description: Roles for version 26.6.0.cl - name: 10.15.0.cl id: 10.15.0.cl tags: - 10.15.0.cl description: Roles for version 10.15.0.cl - name: 10.13.0.cl id: 10.13.0.cl tags: - 10.13.0.cl description: Roles for version 10.13.0.cl - name: 26.9.0.cl id: 26.9.0.cl tags: - 26.9.0.cl description: Roles for version 26.9.0.cl - name: 10.7.0.cl id: 10.7.0.cl tags: - 10.7.0.cl description: Roles for version 10.7.0.cl - name: 26.5.0.cl id: 26.5.0.cl tags: - 26.5.0.cl description: Roles for version 26.5.0.cl - name: 9.0.0.cl id: 9.0.0.cl tags: - 9.0.0.cl description: Roles for version 9.0.0.cl - name: 9.4.0.cl id: 9.4.0.cl tags: - 9.4.0.cl description: Roles for version 9.4.0.cl - name: 9.12.0.cl id: 9.12.0.cl tags: - 9.12.0.cl description: Roles for version 9.12.0.cl - name: 26.4.0.cl id: 26.4.0.cl tags: - 26.4.0.cl description: Roles for version 26.4.0.cl - name: 10.12.0.cl id: 10.12.0.cl tags: - 10.12.0.cl description: Roles for version 10.12.0.cl - name: 9.2.0.cl id: 9.2.0.cl tags: - 9.2.0.cl description: Roles for version 9.2.0.cl - name: 9.9.0.cl id: 9.9.0.cl tags: - 9.9.0.cl description: Roles for version 9.9.0.cl - name: 9.6.0.cl id: 9.6.0.cl tags: - 9.6.0.cl description: Roles for version 9.6.0.cl - name: 10.10.0.cl id: 10.10.0.cl tags: - 10.10.0.cl description: Roles for version 10.10.0.cl - name: 10.6.0.cl id: 10.6.0.cl tags: - 10.6.0.cl description: Roles for version 10.6.0.cl - name: 10.3.0.cl id: 10.3.0.cl tags: - 10.3.0.cl description: Roles for version 10.3.0.cl - name: 10.1.0.cl id: 10.1.0.cl tags: - 10.1.0.cl description: Roles for version 10.1.0.cl - name: 10.9.0.cl id: 10.9.0.cl tags: - 10.9.0.cl description: Roles for version 10.9.0.cl - name: 10.8.0.cl id: 10.8.0.cl tags: - 10.8.0.cl description: Roles for version 10.8.0.cl - name: 9.5.0.cl id: 9.5.0.cl tags: - 9.5.0.cl description: Roles for version 9.5.0.cl - name: 26.3.0.cl id: 26.3.0.cl tags: - 26.3.0.cl description: Roles for version 26.3.0.cl - name: 10.14.0.cl id: 10.14.0.cl tags: - 10.14.0.cl description: Roles for version 10.14.0.cl - name: 9.7.0.cl id: 9.7.0.cl tags: - 9.7.0.cl description: Roles for version 9.7.0.cl