openapi: 3.0.0 info: title: ThoughtSpot Public REST 10.1.0.cl 26.5.0.cl API version: '2.0' servers: - url: '{base-url}' variables: base-url: default: https://localhost:443 security: - bearerAuth: [] tags: - name: 26.5.0.cl paths: /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send: post: operationId: sendAgentConversationMessage description: "\n Version: 26.5.0.cl or later\n\nVersion: 26.5.0.cl or later\n\nSends natural language messages to an existing Spotter agent conversation and returns the complete response synchronously.\n\nRequires `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.\n\n#### Usage guidelines\n\nThe request must include:\n\n- `conversation_identifier`: the unique session ID returned by `createAgentConversation`, used for context continuity and message tracking\n- `messages`: an array of one or more text messages to send to the agent\n\nThe API returns an array of response objects, each containing:\n\n- `type`: the kind of response — `text`, `answer`, or `error`\n- `message`: the main content of the response\n- `metadata`: additional information depending on the message type (e.g., answer metadata includes analytics and visualization details)\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 permission on the referenced conversation. |\n\n> ###### Note:\n>\n> - This endpoint 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> - For real-time streamed responses, use `sendAgentConversationMessageStreaming` instead.\n\n\n\n\n#### Endpoint URL\n" tags: - 26.5.0.cl requestBody: content: application/json: schema: $ref: '#/components/schemas/SendAgentConversationMessageRequest' 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 examples: example_1: summary: Send a message to an existing agent conversation value: messages: - metadata: {} internal: {} type: text text: ' I''ll compare sales between 2025 and 2024. First, let me get the dataset context to identify the relevant sales and date columns.' agent_context: '' - metadata: {} internal: {} type: text text: '```json {"search_mode": "semantic", "dataset_name": "(Sample) Retail - Apparel", "columns": [{"name": "sales", "type": "MEASURE", "data_type": "double"}, {"name": "date", "type": "ATTRIBUTE", "data_type": "date", "sample_values": ["2025", "2024"]}]} ```' agent_context: '' - metadata: {} internal: {} type: text text: ' Perfect! I found the sales and date columns. I can see the dataset contains sales data for both 2025 and 2024. Now I''ll create a comparison query to show sales for 2025 versus 2024.' agent_context: '' - metadata: output: worksheet_id: cd252e5c-b552-49a8-821d-3eadaa049cca assumptions: '' chart_type: KPI interrupted: false data_awareness_enabled: true internal: {} type: answer title: Compare total sales for 2025 vs 2024 description: '' session_id: 842bb67a-e08e-4861-97e8-8db9538db51d gen_no: 2 sage_query: '[sales] [date] = ''2025'' vs [date] = ''2024''' tml_tokens: - '[sales]' - '[date] = ''2025'' vs [date] = ''2024''' formulas: [] parameters: [] subqueries: [] viz_suggestion: CAEQIBomEiQ2NjE5NzI0Yy1kMjVlLTU4MDItOWNjOC1jNDA3MWY3OWY5MzAoATIA ac_state: null - metadata: {} internal: {} type: text text: ' The visualization shows the side-by-side comparison of total sales (in USD) between the two years, allowing you to see the year-over-year performance. You can see the sales figures for both 2024 and 2025, making it easy to identify growth or decline trends in your retail apparel business.' agent_context: '' '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/conversation/{conversation_identifier}/send/stream: post: operationId: sendAgentConversationMessageStreaming description: "\n Version: 26.5.0.cl or later\n\nVersion: 26.5.0.cl or later\n\nSends one or more natural language messages to an existing Spotter agent conversation and returns the response as a real-time Server-Sent Events stream.\n\nRequires `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.\n\n#### Usage guidelines\n\nThe request must include:\n\n- `conversation_identifier`: the unique session ID returned by `createAgentConversation`, used for context continuity and message tracking\n- `messages`: an array of one or more text messages to send to the agent\n\nIf 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:\n\n- `ack`: confirms receipt of the request (`node_id`)\n- `conv_title`: conversation title (`title`, `conv_id`)\n- `notification`: status updates on operations (`group_id`, `metadata`, `code` — e.g. `TOOL_CALL_NOTIFICATION`, `nls_start`, `FINAL_RESPONSE_NOTIFICATION`)\n- `text-chunk`: incremental content chunks (`id`, `group_id`, `metadata` with `format` and `type` such as `thinking` or `text`, `content`)\n- `text`: full text block with same structure as `text-chunk`\n- `answer`: structured answer with metadata (`id`, `group_id`, `metadata` with `sage_query`, `session_id`, `title`, etc., `title`)\n- `error`: if a failure occurs\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 permission on the referenced conversation. |\n\n> ###### Note:\n>\n> - This endpoint 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> - The streaming protocol uses Server-Sent Events (SSE).\n> - For the complete response in a single payload, use `sendAgentConversationMessage` instead.\n\n\n\n\n#### Endpoint URL\n" tags: - 26.5.0.cl requestBody: content: application/json: schema: $ref: '#/components/schemas/SendAgentConversationMessageStreamingRequest' 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: $ref: '#/components/schemas/SendAgentMessageResponse' examples: example_1: summary: 'SSE stream — each line is data: [{"type": "...", ...}]. Events arrive over time; this example shows a minimal sequence.' value: - type: ack node_id: aGxzcFVrtom8 - type: conv_title title: Sales 2025 vs 2024 conv_id: -XIi04l5rrof - type: notification group_id: cDEsAQbSnd3J metadata: type: thinking tool_title: 'Analyzing Sales Performance: 2025 vs 2024' code: TOOL_CALL_NOTIFICATION - id: mNAdvy-NK2l6 type: text-chunk group_id: cDEsAQbSnd3J metadata: format: markdown type: thinking content: ' I need to compare sales performance between 2025 and 2024.' - id: hxWMDP-pgR3B type: answer group_id: m1MTvttEUa7o metadata: sage_query: '[sales] [date] = ''2025'' vs [date] = ''2024''' session_id: 431adcf9-1328-4d8c-81a1-0faa7fa37ba6 title: Compare sales for 2025 vs 2024 title: Compare sales for 2025 vs 2024 '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}/resync-metadata: post: operationId: syncMetadata description: "\n Version: 26.5.0.cl or later\n\nSynchronizes connection metadata attributes from your Cloud Data Warehouse (CDW) with ThoughtSpot.\n\nRequires the `DATAMANAGEMENT` (**Can manage data**) privilege. If [Role-Based Access Control (RBAC)](https://developers.thoughtspot.com/docs/rbac) is enabled on your instance, the `CAN_MANAGE_WORKSHEET_VIEWS_TABLES` (**Can manage data models**) privilege is required.\n\n#### Usage guidelines\n\nTo synchronize attributes from a CDW, specify the connection GUID or name in the `connection_identifier` path parameter and `sync_attributes` in the request body. Default attribute is `[\"DESCRIPTION\"]`.\n\n##### Hierarchical schema\n\n* Connection: The connection object for the sync operation.\n* Tables: Tables for the sync operation. When no table is specified, all tables are synchronized.\n* Columns: If the table is specified, you can add the columns for the sync operation. If no columns are specified, all columns in the specified table are considered for the sync operation.\n\nTo set the scope for the sync operation:\n\n* Connection-level: To sync all tables and columns, pass an empty request body, or only the attributes in the request body.\n* Table-level: To synchronize specific tables and their columns, specify the table identifiers in the `tables` array.\n* Column-level: To synchronize specific columns, specify the table identifier as the key and column identifiers as the value in the `tables` array.\n\n```\n{\n \"tables\": [\n {\"table-guid-1\": [\"column-guid-1\", \"column-guid-2\"]},\n \"table-guid-2\"\n ],\n \"sync_attributes\": [\"DESCRIPTION\"]\n}\n```\n\n##### API response\n\nIf the sync operation is successful, the API returns the following information:\n\n* Status of the sync operation. For example, `SUCCESS`, `PARTIAL_SUCCESS`, or `NO_UPDATE`.\n* Number of tables and columns that were updated.\n* Number of tables and columns with the sync failed status when the overall sync status is `PARTIAL_SUCCESS`.\n* Message text indicating the sync results.\n\n\n\n\n#### Endpoint URL\n" tags: - 26.5.0.cl requestBody: content: application/json: schema: $ref: '#/components/schemas/SyncMetadataRequest' required: true parameters: - in: path name: connection_identifier required: true schema: type: string description: Unique ID or name of the connection. responses: '200': description: Metadata synced successfully. content: application/json: schema: $ref: '#/components/schemas/SyncMetadataResponse' '400': description: Invalid request parameters or hierarchy. 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: Connection, table, or column not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /api/rest/2.0/metadata/parameterize-fields: post: operationId: parameterizeMetadataFields description: ' Parameterize multiple fields of metadata objects. For example [schemaName, databaseName] for LOGICAL_TABLE.
Version: 26.5.0.cl or later Allows parameterizing multiple fields of metadata objects in ThoughtSpot. For example, you can parameterize [schemaName, databaseName] for LOGICAL_TABLE. Requires appropriate permissions to modify the metadata object. The API endpoint allows parameterizing the following types of metadata objects: * Logical Tables * Connections * Connection Configs For a Logical Table, the field type must be `ATTRIBUTE` and field names can include: * databaseName * schemaName * tableName For a Connection or Connection Config, the field type is always `CONNECTION_PROPERTY`. In this case, field_names specifies the exact properties of the Connection or Connection Config that need to be parameterized. For Connection Config, supported field names include: * impersonate_user You can parameterize multiple fields at once by providing an array of field names. #### Endpoint URL ' tags: - 26.5.0.cl requestBody: content: application/json: schema: $ref: '#/components/schemas/ParameterizeMetadataFieldsRequest' required: true parameters: [] responses: '204': description: Parameterize successful. '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/metadata/unparameterize: post: operationId: unparameterizeMetadata description: ' Remove parameterization from fields in metadata objects.
Version: 26.5.0.cl or later Allows removing parameterization from fields in metadata objects in ThoughtSpot. Requires appropriate permissions to modify the metadata object. The API endpoint allows unparameterizing the following types of metadata objects: * Logical Tables * Connections * Connection Configs For a Logical Table the field type must be `ATTRIBUTE` and field name can be one of: * databaseName * schemaName * tableName For a Connection or Connection Config, the field type is always `CONNECTION_PROPERTY`. In this case, field_name specifies the exact property of the Connection or Connection Config that needs to be unparameterized. For Connection Config, the only supported field name is: * impersonate_user #### Endpoint URL ' tags: - 26.5.0.cl requestBody: content: application/json: schema: $ref: '#/components/schemas/UnparameterizeMetadataRequest' required: true parameters: [] responses: '204': description: Successfuly removed parameters. '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/security/metadata/publish: post: operationId: publishMetadata description: "\n Version: 26.5.0.cl or later\n\nAllows publishing metadata objects across organizations in ThoughtSpot.\n\nRequires ADMINISTRATION role and TENANT scope.\n\nThe API endpoint allows publishing the following types of metadata objects:\n* Liveboards\n* Answers\n* Logical Tables\n\nThis API will essentially share the objects along with it's dependencies to\nthe org admins of the orgs to which it is being published.\n\n\n\n\n#### Endpoint URL\n" tags: - 26.5.0.cl requestBody: content: application/json: schema: $ref: '#/components/schemas/PublishMetadataRequest' required: true parameters: [] responses: '204': description: Publishing metadata objects is successful. '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/security/metadata/unpublish: post: operationId: unpublishMetadata description: "\n Version: 26.5.0.cl or later\n\nAllows unpublishing metadata objects from organizations in ThoughtSpot.\n\nRequires ADMINISTRATION role and TENANT scope.\n\nThe API endpoint allows unpublishing the following types of metadata objects:\n* Liveboards\n* Answers\n* Logical Tables\n\nWhen unpublishing objects, you can:\n* Include dependencies by setting `include_dependencies` to true - this will unpublish all dependent objects if no other published object is using them\n* Force unpublish by setting `force` to true - this will break all dependent objects in the unpublished organizations\n\n\n\n\n#### Endpoint URL\n" tags: - 26.5.0.cl requestBody: content: application/json: schema: $ref: '#/components/schemas/UnpublishMetadataRequest' required: true parameters: [] responses: '204': description: Unpublishing metadata objects is successful. '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' components: schemas: SendAgentMessageResponse: type: object required: - success properties: success: type: boolean description: Indicates whether the agent response was received and processed successfully. message: type: string description: Optional message providing additional context about the operation outcome. nullable: true SendAgentConversationMessageStreamingRequest: type: object properties: messages: description: messages to be sent to the agent type: array items: type: string required: - messages PublishMetadataListItem: type: object required: - identifier properties: identifier: type: string description: Unique ID or name of the metadata. type: type: string enum: - LIVEBOARD - ANSWER - LOGICAL_TABLE description: Type of metadata. Required if identifier is name. nullable: true SyncMetadataRequest: type: object properties: tables: description: "Array of tables to sync. Each element can be:\n- String: Table identifier (GUID or name) to sync\n all columns for that table.\n- Object: {tableId: [columnIds]} to sync specific\n columns.\nIf not provided, syncs all tables in the connection." type: object sync_attributes: description: 'List of sync_attributes to sync from CDW. The default value is DESCRIPTION.' default: - DESCRIPTION type: array items: type: string enum: - DESCRIPTION UnpublishMetadataRequest: type: object properties: force: description: Force unpublishes the object. This will break all the dependent objects in the unpublished orgs. type: boolean nullable: true include_dependencies: description: 'Should we unpublish all the dependencies for the objects specified. The dependencies will be unpublished if no other published object is using it.' type: boolean metadata: description: Metadata objects. type: array items: $ref: '#/components/schemas/PublishMetadataListItem' org_identifiers: description: Unique ID or name of orgs. type: array items: type: string required: - include_dependencies - metadata - org_identifiers PublishMetadataRequest: type: object properties: metadata: description: Metadata objects to be published. type: array items: $ref: '#/components/schemas/PublishMetadataListItem' org_identifiers: description: Unique ID or name of orgs to which metadata objects should be published. type: array items: type: string skip_validation: description: Skip validations of objects to be published. type: boolean nullable: true required: - metadata - org_identifiers ParameterizeMetadataFieldsRequest: type: object properties: metadata_type: description: Type of metadata object to parameterize. type: string enum: - LOGICAL_TABLE - CONNECTION - CONNECTION_CONFIG metadata_identifier: description: Unique ID or name of the metadata object to parameterize. type: string field_type: description: Type of field in the metadata to parameterize. type: string enum: - ATTRIBUTE - CONNECTION_PROPERTY field_names: description: 'JSON array of field names to parameterize. Example: [schemaName, databaseName, tableName]' type: array items: type: string variable_identifier: description: Unique ID or name of the variable to use for parameterization of these fields. type: string required: - metadata_identifier - field_type - field_names - variable_identifier ErrorResponse: type: object properties: error: type: object nullable: true SyncMetadataResponse: type: object properties: status: type: string enum: - SUCCESS - PARTIAL_SUCCESS - NO_UPDATE description: Overall status of the sync operation. nullable: true tables_updated: type: integer format: int32 description: Number of tables with metadata updates. nullable: true columns_updated: type: integer format: int32 description: Number of columns with metadata updates. nullable: true tables_failed: type: integer format: int32 description: Number of tables that failed to sync (for PARTIAL_SUCCESS). nullable: true columns_failed: type: integer format: int32 description: Number of columns that failed to sync (for PARTIAL_SUCCESS). nullable: true message: type: string description: Message describing the result. nullable: true description: Response from sync metadata operation. SendAgentConversationMessageRequest: type: object properties: messages: description: messages to be sent to the agent type: array items: type: string required: - messages UnparameterizeMetadataRequest: type: object properties: metadata_type: description: Type of metadata object to unparameterize. type: string enum: - LOGICAL_TABLE - CONNECTION - CONNECTION_CONFIG metadata_identifier: description: Unique ID or name of the metadata object to unparameterize. type: string field_type: description: Type of field in the metadata to unparameterize. type: string enum: - ATTRIBUTE - CONNECTION_PROPERTY field_name: description: Name of the field which needs to be unparameterized. type: string value: description: The value to use in place of the variable for the field type: string required: - metadata_identifier - field_type - field_name - value 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