From f71d334a5bcc11232fb586a3ba73469d414d5d2f Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Wed, 5 Aug 2026 22:23:26 +0530 Subject: [PATCH 001/154] edits --- .../ROOT/pages/spottercode-integration.adoc | 25 +++++++++++-------- modules/ROOT/pages/spottercode.adoc | 4 ++- 2 files changed, 17 insertions(+), 12 deletions(-) diff --git a/modules/ROOT/pages/spottercode-integration.adoc b/modules/ROOT/pages/spottercode-integration.adoc index 3acc56d56..6bdb97d9e 100644 --- a/modules/ROOT/pages/spottercode-integration.adoc +++ b/modules/ROOT/pages/spottercode-integration.adoc @@ -40,23 +40,26 @@ The session token is stored in a secure backend store. Contact your ThoughtSpot ==== === Bearer token authentication -For programmatic or CI/CD scenarios where an MCP client cannot perform an interactive login, SpotterCode accepts a bearer token directly. +For programmatic or CI/CD scenarios where an MCP client cannot perform an interactive login, SpotterCode accepts a bearer token directly using a dedicated MCP Server endpoint: `https://spottercode.thoughtspot.app/bearer/mcp`. -In your MCP client configuration, pass the `Authorization` header in the following format: +In your MCP client configuration, pass the following headers: -[source,text] ----- -Authorization: Bearer @ ----- +* `Authorization: Bearer `, where `` is a valid ThoughtSpot bearer token obtained from the ThoughtSpot REST API. +* `x-ts-host: `, where `` is the full URL of your ThoughtSpot instance (for example, `https://your-org.thoughtspot.cloud`). -Where: +SpotterCode extracts and validates the token and host from these headers, then injects the authentication context into each MCP tool request. -* `` is a valid ThoughtSpot bearer token obtained from the ThoughtSpot REST API. -* `` is your ThoughtSpot instance hostname (for example, `your-org.thoughtspot.cloud`). +For example, to add SpotterCode to Claude Code using the bearer token endpoint: -SpotterCode extracts and validates the token and host, then injects the authentication context into each MCP tool request. +[source,Bash] +---- +claude mcp add --transport http SpotterCode \ + https://spottercode.thoughtspot.app/bearer/mcp \ + -H "Authorization: Bearer " \ + -H "x-ts-host: https://your-org.thoughtspot.cloud" +---- -[TIP] +[NOTE] ==== To obtain a bearer token, use the xref:authentication.adoc[ThoughtSpot REST API v2 authentication endpoints] or trusted authentication. For more information, see xref:trusted-authentication.adoc[Trusted authentication]. ==== diff --git a/modules/ROOT/pages/spottercode.adoc b/modules/ROOT/pages/spottercode.adoc index 414d75c4a..1850492c8 100644 --- a/modules/ROOT/pages/spottercode.adoc +++ b/modules/ROOT/pages/spottercode.adoc @@ -142,7 +142,9 @@ a| User queries and page context. No authentication or instance data is required |==== === ThoughtSpot access controls and governance -SpotterCode does not bypass or modify ThoughtSpot's existing access control model. When SpotterCode executes operations against your ThoughtSpot instance via the `execute-thoughtspot-code` tool, it acts as the authenticated user whose session token is in use. The following ThoughtSpot security features remain in effect: +SpotterCode does not bypass or modify ThoughtSpot's existing access control model. When SpotterCode executes operations against your ThoughtSpot instance via the `execute-thoughtspot-code` tool, it acts as the authenticated user whose session token is in use, and can perform both read and write operations permitted to that user. The following ThoughtSpot security features remain in effect: + +Because code executes as the authenticated user, write operations, such as create, update, delete, and share, generate the same audit log entries as equivalent REST API calls made directly by that user. For details on the events captured and how to retrieve them, see xref:audit-logs.adoc[Audit logs] and xref:logs-api.adoc[Audit logs API]. [NOTE] ==== From 749c2487a62bd97beb781aad3c7290e98412b7fe Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Wed, 5 Aug 2026 23:36:36 +0530 Subject: [PATCH 002/154] whats new update --- modules/ROOT/pages/whats-new.adoc | 20 +++++++++----------- 1 file changed, 9 insertions(+), 11 deletions(-) diff --git a/modules/ROOT/pages/whats-new.adoc b/modules/ROOT/pages/whats-new.adoc index 627969434..bb7fcb470 100644 --- a/modules/ROOT/pages/whats-new.adoc +++ b/modules/ROOT/pages/whats-new.adoc @@ -22,7 +22,6 @@ This page lists new features, enhancements, and deprecated functionality introdu // *Status:* Current / Supported / Deprecated // *Affects:* Developers, Administrators, End Users // ============================================================ - == August 2026 **Release version**: ThoughtSpot Cloud 26.8.0.cl + @@ -40,15 +39,14 @@ a| ==== Spotter embedding Spotter Analysts:: -[earlyAccess eaBackground]#Early Access# -Spotter now includes an *Analysts* panel in the sidebar that surfaces dedicated Spotter Analyst agents. Each Analyst is scoped to a specific data model and skill set, enabling your embedded users to start focused AI-driven conversations without manually selecting a data source. For more information, see xref:embed-spotter.adoc#spotter-analysts[Spotter Analysts in embedded applications]. +[earlyAccess eaBackground]#Early Access# + +Spotter now includes an *Analysts* panel in the sidebar that surfaces dedicated Spotter Analyst agents. Each Analyst is scoped to a specific data model and skill set, enabling your embedded users to start focused AI-driven conversations without manually selecting a data source. For more information, see xref:customize-spotter-embed.adoc#_spotter_analysts[Customize Spotter embed]. Spotter onboarding starter prompts:: -Embedded Spotter interface supports onboarding starter prompts to guide first-time users. When enabled, Spotter presents suggested questions based on the connected data model. For more information, see xref:embed-spotter.adoc#_enable_starter_prompts[Enable starter prompts in Spotter]. +Embedded Spotter interface supports onboarding starter prompts to guide first-time users. When enabled, Spotter presents suggested questions based on the connected data model. For more information, see xref:customize-spotter-embed.adoc#_spotter_starter_prompts[Enable starter prompts in Spotter]. --- - [discrete] ==== Liveboard embedding The following features, previously in Early Access, are now generally available and enabled by default on ThoughtSpot Embedded instances: @@ -73,7 +71,7 @@ Starting from ThoughtSpot Cloud 26.8.0.cl, the classic V1 and V2 navigation and --- [discrete] -==== Wide logo dimension [.version-badge.breaking]#Breaking# +==== Wide logo dimension [.version-badge.breaking]#Breaking change# Starting from ThoughtSpot Cloud 26.8.0.cl, the recommended dimensions for the wide logo displayed on the ThoughtSpot login page have changed from 330x100px to *250x50px (5:1 aspect ratio)*. Logos uploaded at the previous dimensions may appear distorted or incorrectly scaled on the login screen. If you previously uploaded a wide logo at 330x100px, re-upload it at 250x50px to ensure correct display. For more information, see xref:customize-style.adoc#wide-logo[Customize the login page logo]. @@ -85,8 +83,8 @@ For more information, see xref:customize-style.adoc#wide-logo[Customize the logi ==== Granular download privileges The new granular download privileges that replace the single general download privilege for RBAC enabled clusters are now generally available. -* *Can Download Visuals* — Allows downloading chart images and visual exports. -* *Can Download Detailed Data* — Allows downloading raw tabular data (CSV, XLSX). +* *Can Download Visuals*: Allows downloading chart images and visual exports. +* *Can Download Detailed Data*: Allows downloading raw tabular data (CSV, XLSX). These privileges can be assigned independently per user or group. Update privilege assignments in your embedded application accordingly. @@ -105,14 +103,14 @@ For more information, see xref:tml.adoc#personalized-views-portability[Personali --- [discrete] -==== Discoverability checkbox deprecation [.version-badge.breaking]#Breaking# +==== Discoverability checkbox deprecation [.version-badge.breaking]#Breaking change# The *Make this Liveboard Discoverable* checkbox has been removed from the ThoughtSpot UI. Embedding applications that relied on discoverability for content visibility should review their sharing logic and update user-facing guidance for content access. For more information, see xref:deprecated-features.adoc#liveboardAnswerDiscoverable[Deprecation announcements]. --- [discrete] -==== SpotterCode widget documentation assistance -This developer documentation site now includes a SpotterCode AI assistant panel that replaces the earlier *AskDocs* feature. When you open the assistant panel, it displays prebuilt starter prompts relevant to the page you are currently viewing and allows you to explore topics instantly. You can also type your own questions about embedding, REST APIs, SDK configuration, and developer guides. +==== SpotterCode widget for documentation assistance +This developer documentation site now includes a SpotterCode AI assistant panel that replaces the earlier *AskDocs* feature. When you open the assistant panel, it displays prebuilt starter prompts relevant to the page you are currently viewing and allows you to explore topics instantly. You can also type your own questions about embedding, REST APIs, SDK configuration, and developer guides. For more information, see xref:spottercode.adoc[SpotterCode documentation]. --- From 8e02684d5b17932b98f801e97b5010e9b8870703 Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Thu, 6 Aug 2026 13:20:34 +0530 Subject: [PATCH 003/154] edited for Siddhant's input --- modules/ROOT/pages/tml.adoc | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/modules/ROOT/pages/tml.adoc b/modules/ROOT/pages/tml.adoc index 8619546fb..d53b7d018 100644 --- a/modules/ROOT/pages/tml.adoc +++ b/modules/ROOT/pages/tml.adoc @@ -123,8 +123,9 @@ If the import is performed by an administrator account, all personalized views s Why this happens?:: -Personalized views are stored as user-owned objects linked to the Liveboard's GUID. -When an admin imports a Liveboard TML that matches an existing GUID, the import operation overwrites the Liveboard, and the associated user views are not carried forward. +Personalized views are stored as user-owned objects linked to the Liveboard’s GUID. When an admin imports a Liveboard TML that matches an existing GUID, the import operation overwrites the Liveboard, and the associated user views are not carried forward. + +This happens because personalized views are created and usually owned by end users in a different environment (likely a Prod instance). They are not included in Liveboard TML files exported from a development or staging environment, so the import has no record of them. Workarounds:: . Import as a non-admin user - From c3d23973cd9a8e6dfd14bf56dc1333b4fdcfd0bf Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Thu, 6 Aug 2026 13:42:55 +0530 Subject: [PATCH 004/154] edited for Siddhant's input --- modules/ROOT/pages/tml.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/tml.adoc b/modules/ROOT/pages/tml.adoc index d53b7d018..127583da2 100644 --- a/modules/ROOT/pages/tml.adoc +++ b/modules/ROOT/pages/tml.adoc @@ -124,7 +124,7 @@ If the import is performed by an administrator account, all personalized views s Why this happens?:: Personalized views are stored as user-owned objects linked to the Liveboard’s GUID. When an admin imports a Liveboard TML that matches an existing GUID, the import operation overwrites the Liveboard, and the associated user views are not carried forward. - ++ This happens because personalized views are created and usually owned by end users in a different environment (likely a Prod instance). They are not included in Liveboard TML files exported from a development or staging environment, so the import has no record of them. Workarounds:: From 2b6514238f70216e8a72cdf4ce77f30827472c9f Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Fri, 7 Aug 2026 14:08:07 +0530 Subject: [PATCH 005/154] removed beta label for Coll from nav --- modules/ROOT/pages/common/nav-in-product-help.adoc | 2 +- modules/ROOT/pages/common/nav-rest-api.adoc | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/ROOT/pages/common/nav-in-product-help.adoc b/modules/ROOT/pages/common/nav-in-product-help.adoc index 1220e40da..73d3dedd9 100644 --- a/modules/ROOT/pages/common/nav-in-product-help.adoc +++ b/modules/ROOT/pages/common/nav-in-product-help.adoc @@ -232,7 +232,7 @@ REST APIs ** link:{{navprefix}}/style-customization-apis[Style customization APIs] ** link:{{navprefix}}/audit-logs[Audit logs] ** link:{{navprefix}}/tml[TML] -** link:{{navprefix}}/collections[Collections ^BETA^] +** link:{{navprefix}}/collections[Collections] ** link:{{navprefix}}/connections[Connections] ** link:{{navprefix}}/connection-config[Connection configuration] ** link:{{navprefix}}/input-tables-api[Input Tables API] diff --git a/modules/ROOT/pages/common/nav-rest-api.adoc b/modules/ROOT/pages/common/nav-rest-api.adoc index fe44ba50c..3ab94642e 100644 --- a/modules/ROOT/pages/common/nav-rest-api.adoc +++ b/modules/ROOT/pages/common/nav-rest-api.adoc @@ -30,7 +30,7 @@ REST APIs *** link:{{navprefix}}/spotter-nl-instructions[Data model instructions APIs ^BETA^] ** link:{{navprefix}}/audit-logs[Audit logs] ** link:{{navprefix}}/tml[TML] -** link:{{navprefix}}/collections[Collections ^BETA^] +** link:{{navprefix}}/collections[Collections] ** link:{{navprefix}}/connections[Connections] ** link:{{navprefix}}/connection-config[Connection configuration] ** link:{{navprefix}}/manual-translation-api[Manual translations] From 2117f9168a33babf2f25704fbfea59c65fef0474 Mon Sep 17 00:00:00 2001 From: Justin Mathew Date: Fri, 7 Aug 2026 13:39:33 +0530 Subject: [PATCH 006/154] SCAL-330848 Replace record_size = -1 guidance with pagination warning Applies the docs team's revised copy so the public docs match the REST API Playground help text updated in SCAL-330570. Pages that recommended record_size = -1 now carry the approved warning; code samples that used -1 use a bounded page size instead. SCAL-330848 --- modules/ROOT/pages/abac_rls-variables.adoc | 2 +- modules/ROOT/pages/collections.adoc | 2 +- modules/ROOT/pages/data-report-v2-api.adoc | 7 ++++++- modules/ROOT/pages/deploy-with-tml-apis.adoc | 2 +- modules/ROOT/pages/rest-api-v2-groups-search.adoc | 5 ++++- modules/ROOT/pages/rest-api-v2-metadata-search.adoc | 5 ++++- modules/ROOT/pages/rest-api-v2-users-search.adoc | 5 ++++- .../pages/react-components/react-components_lesson-03.adoc | 3 ++- 8 files changed, 23 insertions(+), 8 deletions(-) diff --git a/modules/ROOT/pages/abac_rls-variables.adoc b/modules/ROOT/pages/abac_rls-variables.adoc index 66bf24e44..deb0c734b 100644 --- a/modules/ROOT/pages/abac_rls-variables.adoc +++ b/modules/ROOT/pages/abac_rls-variables.adoc @@ -413,7 +413,7 @@ Set the `response_content` parameter to `METADATA_AND_VALUES` to see the values ---- { "record_offset": 0, - "record_size": -1, + "record_size": 50, "response_content": "METADATA_AND_VALUES" } ---- diff --git a/modules/ROOT/pages/collections.adoc b/modules/ROOT/pages/collections.adoc index 2c4e7c00c..4a5cf27ca 100644 --- a/modules/ROOT/pages/collections.adoc +++ b/modules/ROOT/pages/collections.adoc @@ -97,7 +97,7 @@ In your `POST` request body, include the following parameters: |`name_pattern` a|__String__. Optional. Specify any case agnostic pattern to match the name of a Collection. Use `%` to perform a wildcard search by name. |`record_offset` a|__Number__. Optional. The index of the first record to be included. Default value is 0. -|`record_size` a|__Number__. Optional. The total number of records to be searched. Default value is 10. Set to -1 to search across all available collections. +|`record_size` a|__Number__. Optional. The total number of records to be searched. Default value is 10. Do not set this to `-1`; specify an explicit `record_size` and iterate through pages programmatically. |`collection_identifiers` a|__Array__. Optional. GUID of the Collection(s) to be searched. `name_pattern` takes precedence over the `collection_identifiers`. |`created_by_user_identifiers` a|__Array__. Optional. Searches for Collections by the name of the author. |`include_metadata` a|__Boolean__. Optional. When set to `true`, includes the metadata objects within each Collection in the response. diff --git a/modules/ROOT/pages/data-report-v2-api.adoc b/modules/ROOT/pages/data-report-v2-api.adoc index f32d57f79..a73d16087 100644 --- a/modules/ROOT/pages/data-report-v2-api.adoc +++ b/modules/ROOT/pages/data-report-v2-api.adoc @@ -580,7 +580,12 @@ When you make REST API calls to some v2 Data endpoints to query data, the API ma } ---- -You can set `record_size` to `-1` and `record_offset` to `0` for precise and complete results. The APIs return a maximum of 100000 rows of data at any given time. If you must retrieve a higher number of rows in an API call, contact ThoughtSpot Customer Support to increase the row size limit. However, if the record size and number of rows are high, the API may take a while to fetch the data, and the request may time out. +[WARNING] +==== +Do not set `record_size` to `-1`. On ThoughtSpot instances with a large number of objects or users, this can lead to slow responses, excessive logging, and out-of-memory failures. Specify an explicit `record_size` and iterate through pages programmatically. +==== + +The APIs return a maximum of 100000 rows of data at any given time. If you must retrieve a higher number of rows in an API call, contact ThoughtSpot Customer Support to increase the row size limit. However, if the record size and number of rows are high, the API may take a while to fetch the data, and the request may time out. == Runtime overrides The Data API endpoints support the following runtime overrides: diff --git a/modules/ROOT/pages/deploy-with-tml-apis.adoc b/modules/ROOT/pages/deploy-with-tml-apis.adoc index e09eaf7d8..2425adcf9 100644 --- a/modules/ROOT/pages/deploy-with-tml-apis.adoc +++ b/modules/ROOT/pages/deploy-with-tml-apis.adoc @@ -145,7 +145,7 @@ The `/metadata/search` REST API endpoint has parameters to filter on `tag_identi "field_name": order_field, "order": "DESC" }, - "record_size" : -1, + "record_size" : 50, "record_offset": 0 } ---- diff --git a/modules/ROOT/pages/rest-api-v2-groups-search.adoc b/modules/ROOT/pages/rest-api-v2-groups-search.adoc index 779b503cd..2c406b6d8 100644 --- a/modules/ROOT/pages/rest-api-v2-groups-search.adoc +++ b/modules/ROOT/pages/rest-api-v2-groups-search.adoc @@ -24,7 +24,10 @@ Throughout this article, requests and responses will be shown as JSON, without a } ---- -For precise results, you can set `record_size` to `-1` and `record_offset` to `0`. +[WARNING] +==== +Do not set `record_size` to `-1`. On ThoughtSpot instances with a large number of objects or users, this can lead to slow responses, excessive logging, and out-of-memory failures. Specify an explicit `record_size` and iterate through pages programmatically. +==== == Response format diff --git a/modules/ROOT/pages/rest-api-v2-metadata-search.adoc b/modules/ROOT/pages/rest-api-v2-metadata-search.adoc index 109bf50fb..a7620633d 100644 --- a/modules/ROOT/pages/rest-api-v2-metadata-search.adoc +++ b/modules/ROOT/pages/rest-api-v2-metadata-search.adoc @@ -3889,7 +3889,10 @@ By default, the following pagination settings are applied to the API response re } ---- -If you are not using filtering options such as `tag_identifiers`, `type`, `created_by_user_identifiers`, `modified_by_user_identifiers`, `owned_by_user_identifiers`, `exclude_objects`, `include_auto_created_objects`, or `favorite_object_options`, set `record_size` to `-1` and `record_offset` to `0` for precise results. +[WARNING] +==== +Do not set `record_size` to `-1`. On ThoughtSpot instances with a large number of objects or users, this can lead to slow responses, excessive logging, and out-of-memory failures. Specify an explicit `record_size` and iterate through pages programmatically. +==== diff --git a/modules/ROOT/pages/rest-api-v2-users-search.adoc b/modules/ROOT/pages/rest-api-v2-users-search.adoc index fc2e4f099..1d7ebcb58 100644 --- a/modules/ROOT/pages/rest-api-v2-users-search.adoc +++ b/modules/ROOT/pages/rest-api-v2-users-search.adoc @@ -24,7 +24,10 @@ Throughout this article, requests and responses will be shown as JSON, without a } ---- -For precise results, you can set `record_size` to `-1` and `record_offset` to `0`. +[WARNING] +==== +Do not set `record_size` to `-1`. On ThoughtSpot instances with a large number of objects or users, this can lead to slow responses, excessive logging, and out-of-memory failures. Specify an explicit `record_size` and iterate through pages programmatically. +==== == Response format The response from any call to `users/search` will resemble the following: diff --git a/modules/tutorials/pages/react-components/react-components_lesson-03.adoc b/modules/tutorials/pages/react-components/react-components_lesson-03.adoc index 9baf18f7b..34ac53326 100644 --- a/modules/tutorials/pages/react-components/react-components_lesson-03.adoc +++ b/modules/tutorials/pages/react-components/react-components_lesson-03.adoc @@ -112,7 +112,8 @@ For endpoints that accept request parameters body, declare a `const` and set it ---- // Define the options for the metadata/search call const metadataOptions = { - record_size: -1, + record_offset: 0, + record_size: 50, include_headers: true, metadata: [ { From 7ebf8198ddedca21265dd321b6fe3fc27f397b2d Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Tue, 11 Aug 2026 13:10:31 +0530 Subject: [PATCH 007/154] SCAL-295712 --- modules/ROOT/pages/api-changelog.adoc | 2 + modules/ROOT/pages/embed-pinboard.adoc | 95 +++++++++++++++++++------- modules/ROOT/pages/whats-new.adoc | 4 +- 3 files changed, 73 insertions(+), 28 deletions(-) diff --git a/modules/ROOT/pages/api-changelog.adoc b/modules/ROOT/pages/api-changelog.adoc index dabe5cc70..0619c8767 100644 --- a/modules/ROOT/pages/api-changelog.adoc +++ b/modules/ROOT/pages/api-changelog.adoc @@ -40,6 +40,8 @@ Enables the xref:embed-pinboard.adoc#_liveboard_grouping_and_styling[Liveboard s * `isEnhancedFilterInteractivityEnabled` + Enables interactive filter chips that allow users to add, update, or remove filters in an embedded Liveboard. +For more information, see xref:embed-pinboard.adoc#common-customizations[Common customization options in Liveboard embedding]. + |[tag greenBackground]#NEW FEATURE# a| [discrete] diff --git a/modules/ROOT/pages/embed-pinboard.adoc b/modules/ROOT/pages/embed-pinboard.adoc index acabc5b2a..0f2c70d79 100644 --- a/modules/ROOT/pages/embed-pinboard.adoc +++ b/modules/ROOT/pages/embed-pinboard.adoc @@ -10,7 +10,6 @@ This page explains how to embed a ThoughtSpot Liveboard in your web page, portal A ThoughtSpot Liveboard is an interactive dashboard that presents a collection of visualizations pinned by a user. - == Import the LiveboardEmbed package Import the `LiveboardEmbed` SDK library to your application environment: @@ -137,8 +136,48 @@ const liveboardEmbed = new LiveboardEmbed(document.getElementById('ts-embed'), { When `fullHeight` is set to `true`, the SDK ignores the `isLiveboardHeaderSticky:true` setting, and the Liveboard header is not sticky. ==== -=== Customize Liveboard tabs +[#compact-header] +=== Enable compact Liveboard header +By default, embedded Liveboards display a full-height header bar that contains the Liveboard title, description, filter chips, tab navigation, and action menu. You can switch to a more space-efficient layout by enabling the compact header. + +The compact header reduces the vertical footprint of the header area, integrates tabs and filter chips into a single condensed row, and moves the *Edit* button into the header's overflow action menu. + +To enable the compact header, set `isLiveboardCompactHeaderEnabled` to `true` in the `LiveboardViewConfig` object. Note that the `isLiveboardCompactHeaderEnabled` attribute is set to `true` by default on all ThoughtSpot embedded instances using Visual Embed SDK v1.51.0 or later. + +[source,JavaScript] +---- +const liveboardEmbed = new LiveboardEmbed(document.getElementById('ts-embed'), { + //... other embed config properties + isLiveboardCompactHeaderEnabled: true, +}); +---- + +When `isLiveboardCompactHeaderEnabled` is `true`, the following UI changes apply compared to the standard header: + +[width="100%",cols="2,4",options="header"] +|==== +|Area |Change +|Header height |The header renders in a condensed, shorter height to maximize the visible content area. +|Edit button |The *Edit* button is removed from the top-level header and is accessible from the header overflow (*...*) menu. +|Filter chips |Filter chips are rendered inside the compact header's integrated filter row, replacing the separate floating filter panel. +|Tabs |The tab bar is incorporated into the compact header row, rather than appearing as a separate element below the header. +|Sticky scroll behavior |The scroll threshold at which the sticky header attaches to the top of the viewport is recalculated for the compact header's shorter height. This may affect the scroll position at which the header becomes sticky compared to the standard header. +|| +|==== + +==== Hiding the Liveboard title in compact header +In the compact header, you can hide the Liveboard title by setting `showLiveboardTitle` to `false` in the `LiveboardViewConfig` object: +[source,JavaScript] +---- +const liveboardEmbed = new LiveboardEmbed(document.getElementById('ts-embed'), { + //... other embed config properties + isLiveboardCompactHeaderEnabled: true, + showLiveboardTitle: false, +}); +---- + +=== Customize Liveboard tabs By default, the first tab created on a Liveboard is set as the home tab. You can set any tab as an active tab using the `activeTabId` property in the Visual Embed SDK as shown in the example here: [source,JavaScript] @@ -163,6 +202,34 @@ The `activeTabId` property is available only in the `LiveboardEmbed` package and For example, a template Liveboard with many different key performance indicators (KPIs) could be reduced to a smaller set by giving a user an interface to select the particular visualizations to show, storing their selections, and using that saved set of visualization globally unique identifiers (GUIDs) as the array for `visibleVizs` on page load (there is an equivalent xref:embed-events.adoc[HostEvent] called `SetVisibleVizs` to make an update after the Liveboard has loaded). +=== Customizing filter visibility +To hide the entire header area, including filters and the Liveboard menu, set `hideLiveboardHeader` to `true`. You can then trigger filter interactions programmatically using host events. + +[source,JavaScript] +---- +const embed = new LiveboardEmbed('#embed', { + ... // other liveboard view config + hideLiveboardHeader:true, +}); +---- + +If the Liveboard has multiple tabs and the compact header is enabled, you can set `hideIrrelevantChipsInLiveboardTabs` to `true` to hide filters that are not relevant to the current tab in an embedded Liveboard. Note that `hideIrrelevantChipsInLiveboardTabs` is set to `true` by default on all ThoughtSpot embedded instances using Visual Embed SDK v1.51.0 or later. + +[source,JavaScript] +---- +const liveboardEmbed = new LiveboardEmbed(document.getElementById('ts-embed'), { + //... other embed config properties + isLiveboardCompactHeaderEnabled: true, + hideIrrelevantChipsInLiveboardTabs: true, +}); +---- + +When `hideIrrelevantChipsInLiveboardTabs` is `true`: + +* Filter chips backed by data sources that are *not used by any visualization on the active tab* are hidden automatically when the user switches tabs. +* A *Show irrelevant filters* toggle button appears in the filter row when at least one chip is hidden, allowing users to temporarily reveal all chips. +* When the user clicks *Show irrelevant filters*, a complementary *Hide irrelevant filters* button appears to restore the filtered view. + [#noteTiles] === Add Note tiles You can add a link:https://docs.thoughtspot.com/cloud/latest/liveboard-notes[Liveboard Note tile, window=_blank] with custom text, images, and links on an embedded Liveboard. @@ -234,30 +301,6 @@ beyond are silently dropped without an error or warning. For more information, s xref:runtime-filters.adoc#_maximum_filter_count[Runtime filter limit]. ==== -==== Customizing filter visibility -To hide filters in an embedded Liveboard, you can use the following options: - -* Set `hideLiveboardHeader` to `true` to hide the entire header area, including filters and the Liveboard menu. You can then trigger filter interactions programmatically using host events. -+ -[source,JavaScript] ----- -const embed = new LiveboardEmbed('#embed', { - ... // other liveboard view config - hideLiveboardHeader:true, -}); ----- - -* If the Liveboard compact header is enabled, set `hideIrrelevantChipsInLiveboardTabs` to `true` to hide filters that are not relevant to the current tab in an embedded Liveboard. -+ -[source,JavaScript] ----- -const embed = new LiveboardEmbed('#embed', { - ... // other liveboard view config - isLiveboardCompactHeaderEnabled: true, - hideIrrelevantChipsInLiveboardTabs: true, -}); ----- - ==== Updating filters Use the following host events in the Visual Embed SDK to update filters: diff --git a/modules/ROOT/pages/whats-new.adoc b/modules/ROOT/pages/whats-new.adoc index bb7fcb470..3541b2526 100644 --- a/modules/ROOT/pages/whats-new.adoc +++ b/modules/ROOT/pages/whats-new.adoc @@ -52,9 +52,9 @@ Embedded Spotter interface supports onboarding starter prompts to guide first-ti The following features, previously in Early Access, are now generally available and enabled by default on ThoughtSpot Embedded instances: * Hide irrelevant filters (`hideIrrelevantChipsInLiveboardTabs`) + -Hides filters that are not relevant to the displayed visualization in a tab. +xref:embed-pinboard.adoc#_customizing_filter_visibility[Hides filters] that are not relevant to the displayed visualization in a tab. * Compact header (`isLiveboardCompactHeaderEnabled`) + -Enables compact header layout in embedded Liveboards. +Enables xref:embed-pinboard.adoc#compact-header[compact header layout] in embedded Liveboards. * Cover page filtering options (`coverAndFilterOptionInPDF`) + Enables the *Include cover page* and *Include filter page(s)* checkboxes in the Liveboard download modal. * Liveboard styling and grouping (isLiveboardMasterpiecesEnabled) + From fec4dcc5f4f6ae7d19e2371bb52ae4c8880230e0 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Tue, 11 Aug 2026 14:23:20 +0530 Subject: [PATCH 008/154] compact header breaking change --- modules/ROOT/pages/whats-new.adoc | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/modules/ROOT/pages/whats-new.adoc b/modules/ROOT/pages/whats-new.adoc index 3541b2526..56a89557d 100644 --- a/modules/ROOT/pages/whats-new.adoc +++ b/modules/ROOT/pages/whats-new.adoc @@ -38,8 +38,7 @@ a| [discrete] ==== Spotter embedding -Spotter Analysts:: -[earlyAccess eaBackground]#Early Access# + +Spotter Analysts [earlyAccess eaBackground]#Early Access#:: Spotter now includes an *Analysts* panel in the sidebar that surfaces dedicated Spotter Analyst agents. Each Analyst is scoped to a specific data model and skill set, enabling your embedded users to start focused AI-driven conversations without manually selecting a data source. For more information, see xref:customize-spotter-embed.adoc#_spotter_analysts[Customize Spotter embed]. Spotter onboarding starter prompts:: @@ -48,13 +47,13 @@ Embedded Spotter interface supports onboarding starter prompts to guide first-ti --- [discrete] -==== Liveboard embedding +==== Liveboard embedding enhancements The following features, previously in Early Access, are now generally available and enabled by default on ThoughtSpot Embedded instances: * Hide irrelevant filters (`hideIrrelevantChipsInLiveboardTabs`) + xref:embed-pinboard.adoc#_customizing_filter_visibility[Hides filters] that are not relevant to the displayed visualization in a tab. * Compact header (`isLiveboardCompactHeaderEnabled`) + -Enables xref:embed-pinboard.adoc#compact-header[compact header layout] in embedded Liveboards. +Enables in compact header in embedded Liveboards. For information about breaking changes and the affected elements, see xref:embed-pinboard.adoc#compact-header[compact Liveboard header]. * Cover page filtering options (`coverAndFilterOptionInPDF`) + Enables the *Include cover page* and *Include filter page(s)* checkboxes in the Liveboard download modal. * Liveboard styling and grouping (isLiveboardMasterpiecesEnabled) + From eb9c784fdbc2ae75b43c906e8681de54675d46f1 Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Tue, 11 Aug 2026 22:23:30 +0530 Subject: [PATCH 009/154] SCAL-318536 --- modules/ROOT/pages/embed-pinboard.adoc | 6 +++-- modules/ROOT/pages/filters_overview.adoc | 6 +++-- modules/ROOT/pages/runtime-filters.adoc | 28 ++++++++++++++--------- modules/ROOT/pages/runtime-overrides.adoc | 9 ++++---- 4 files changed, 30 insertions(+), 19 deletions(-) diff --git a/modules/ROOT/pages/embed-pinboard.adoc b/modules/ROOT/pages/embed-pinboard.adoc index 0f2c70d79..80de55335 100644 --- a/modules/ROOT/pages/embed-pinboard.adoc +++ b/modules/ROOT/pages/embed-pinboard.adoc @@ -296,8 +296,10 @@ To view specific data across the tables and charts on an embedded Liveboard, use [IMPORTANT] ==== -The SDK processes up to 49 runtime filters per embed. Any objects at index 50 or -beyond are silently dropped without an error or warning. For more information, see +Runtime filter limits vary by input path. URL-based runtime filters are capped at 50. +When using the Visual Embed SDK `runtimeFilters` property, the limit is configurable by a +ThoughtSpot administrator, with a default and maximum of 1,000. Filters beyond the enforced +limit are silently dropped without an error or warning. For more information, see xref:runtime-filters.adoc#_maximum_filter_count[Runtime filter limit]. ==== diff --git a/modules/ROOT/pages/filters_overview.adoc b/modules/ROOT/pages/filters_overview.adoc index d4c0d9849..f76e75d8f 100644 --- a/modules/ROOT/pages/filters_overview.adoc +++ b/modules/ROOT/pages/filters_overview.adoc @@ -28,8 +28,10 @@ You can define xref:runtime-filters.adoc[runtime filters] and xref:runtime-param [NOTE] ==== * Runtime filters do not display as UI filter components. -* The SDK processes at most 49 entries per embed. Any objects at index 50 or -beyond are silently dropped without an error or warning. See +* Runtime filter limits vary by input path. URL-based runtime filters are capped at 50. +When using the Visual Embed SDK `runtimeFilters` property, the limit is configurable by a +ThoughtSpot administrator, with a default and maximum of 1,000. Filters beyond the enforced +limit are silently dropped without an error or warning. See xref:runtime-filters.adoc#_maximum_filter_count[Runtime filter limit] for more information. ==== diff --git a/modules/ROOT/pages/runtime-filters.adoc b/modules/ROOT/pages/runtime-filters.adoc index 338c9a5d5..d228cbec0 100644 --- a/modules/ROOT/pages/runtime-filters.adoc +++ b/modules/ROOT/pages/runtime-filters.adoc @@ -46,28 +46,34 @@ This attribute is defined as `val1`, `val2`, `val3` in the object URLs and REST Some operators like `EQ` and `LE` accept a single operand, whereas `BW_INC_MAX`, `BW_INC_MIN`, `BW_INC`, `BW`, and `IN` accept multiple operands. === Maximum filter count +ThoughtSpot enforces separate filter count limits depending on how runtime filters are applied: -The SDK processes a maximum of 49 runtime filters per embedded object. +URL-based runtime filters:: -The internal constant `MAX_RUNTIME_FILTERS` is set to `50`, but the +URL-based runtime filters are capped at exactly 50. This limit is fixed and cannot be configured. The internal constant `MAX_RUNTIME_FILTERS` is set to `50`, but the parsing loop runs from index `1` up to (but not including) `50` (`index < MAX_RUNTIME_FILTERS`). This means filter values `col1`/`op1`/`val1` through `col49`/`op49`/`val49` are processed; `col50` and above are ignored. -This applies to both input paths: - -* URL query parameters: filter values appended to the embed URL -(`col1=`, `op1=`, `val1=`, `col2=`, …) -* `runtimeFilters` embed config property: filters passed as an array in the -SDK initialization config for `LiveboardEmbed`, `AppEmbed`, and -`SearchEmbed` - [IMPORTANT] ==== When the number of runtime filters exceeds 49, filters beyond that index are silently dropped. No error is thrown, no warning is emitted, and no embed event is fired. The embedded object renders using only the first 49 filters -without any indication that additional filters were discarded. This silent-drop behavior means that, if your application passes 60 runtime filters, the last 11 are ignored without any notification to the developer. Always validate filter counts in your application before passing them to the SDK. +without any indication that additional filters were discarded. +==== + +Embed payload runtime filters (Visual Embed SDK):: + +When you pass runtime filters as an array in the SDK initialization config for `LiveboardEmbed`, `AppEmbed`, `SpotterEmbed` and +`SearchEmbed` using the `runtimeFilters` property in the Visual Embed SDK, ThoughtSpot applies a configurable limit. The default and maximum value is 1000 filters. + +ThoughtSpot administrators can configure this limit for their instance. The value must be between 1 and 1000. +To check or update the configured limit, contact your ThoughtSpot administrator. + +[IMPORTANT] +==== +Regardless of the filter path, filters beyond the enforced limit are silently dropped. No error is thrown, no warning is emitted, and no embed event is fired. The embedded object renders using only the filters within the allowed count. Always validate filter counts in your application before passing them to the SDK. ==== === Supported data types diff --git a/modules/ROOT/pages/runtime-overrides.adoc b/modules/ROOT/pages/runtime-overrides.adoc index 4176940fc..96ef02ad6 100644 --- a/modules/ROOT/pages/runtime-overrides.adoc +++ b/modules/ROOT/pages/runtime-overrides.adoc @@ -21,10 +21,11 @@ Developers can set runtime filters in the Visual Embed SDK for the following emb After the object loads, runtime filters can be xref:runtime-filters.adoc#_adjust_runtime_filters_using_sdk_events[adjusted using the SDK events]. -WARNING: The SDK processes at most 49 entries per embed. Any objects at index 50 or -beyond are silently dropped without an error or warning. See -xref:runtime-filters.adoc#_maximum_filter_count[Runtime filter limit] for -more information. +WARNING: Runtime filter limits vary by input path. URL-based runtime filters are capped at 50. +When using the Visual Embed SDK `runtimeFilters` property, the limit is configurable by a +ThoughtSpot administrator, with a default and maximum of 1,000. Filters beyond the enforced +limit are silently dropped without an error or warning. See +xref:runtime-filters.adoc#_maximum_filter_count[Runtime filter limit] for more information. == Runtime Parameters From e85138325ed6bb92b40bafbf28a0acaa6b260311 Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Tue, 11 Aug 2026 22:42:41 +0530 Subject: [PATCH 010/154] SCAL-318536 --- modules/ROOT/pages/runtime-filters.adoc | 8 -------- 1 file changed, 8 deletions(-) diff --git a/modules/ROOT/pages/runtime-filters.adoc b/modules/ROOT/pages/runtime-filters.adoc index d228cbec0..de21f1bf3 100644 --- a/modules/ROOT/pages/runtime-filters.adoc +++ b/modules/ROOT/pages/runtime-filters.adoc @@ -55,14 +55,6 @@ parsing loop runs from index `1` up to (but not including) `50` (`index < MAX_RUNTIME_FILTERS`). This means filter values `col1`/`op1`/`val1` through `col49`/`op49`/`val49` are processed; `col50` and above are ignored. -[IMPORTANT] -==== -When the number of runtime filters exceeds 49, filters beyond that index are -silently dropped. No error is thrown, no warning is emitted, and no embed -event is fired. The embedded object renders using only the first 49 filters -without any indication that additional filters were discarded. -==== - Embed payload runtime filters (Visual Embed SDK):: When you pass runtime filters as an array in the SDK initialization config for `LiveboardEmbed`, `AppEmbed`, `SpotterEmbed` and From b206ec4e693b6467333b39208f3db5b75a8412f0 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Thu, 6 Aug 2026 08:26:22 +0530 Subject: [PATCH 011/154] SCAL-330067 updates --- .../pages/mcp-server-client-connection.adoc | 35 ++++++++++++++++++- 1 file changed, 34 insertions(+), 1 deletion(-) diff --git a/modules/ROOT/pages/mcp-server-client-connection.adoc b/modules/ROOT/pages/mcp-server-client-connection.adoc index e23efaa30..82cb6fd91 100644 --- a/modules/ROOT/pages/mcp-server-client-connection.adoc +++ b/modules/ROOT/pages/mcp-server-client-connection.adoc @@ -124,7 +124,6 @@ OAuth clients can be registered in one of the following ways: + To register a client, visit link:https://agent.thoughtspot.app/clients[ThoughtSpot MCP OAuth Client Registration, window=_blank]. When registering the OAuth client, add your ThoughtSpot instance URL to the appropriate field. This ensures that users are not prompted to enter the instance URL during the OAuth flow, and the OAuth redirect returns correctly to your ThoughtSpot environment after login. - == Verifying integration After the MCP Server is connected, some clients show *ThoughtSpot Data Sources* under a *Resources* or *Datasets* section. @@ -134,6 +133,40 @@ To verify the integration: . Verify that MCP tools are being called to generate responses. See the xref:mcp-tool-reference-guide.adoc[MCP tool reference guide] for information about tool calls. . Try the Liveboard creation request and verify whether a Liveboard is added to your ThoughtSpot application. +== Using the ThoughtSpot skill with skill-aware clients +Some LLM clients, such as Claude, support skills—packaged sets of instructions and best practices that an agent can load on demand to perform specific tasks more reliably. +Alongside the ThoughtSpot Spotter MCP Server, ThoughtSpot provides a companion skill that helps skill-aware clients use the MCP tools more effectively. For example, routing questions intelligently, streaming its thinking as it works, and surfacing ThoughtSpot's own visualizations instead of generating charts. + +[NOTE] +==== +The skill is installed separately from the connector. Connecting the ThoughtSpot Spotter connector (or configuring the MCP server) gives your client access to the available tools. Installing the skill doesn't provide the tools themselves; instead, it helps the client understand when and how to orchestrate those tools effectively. You can use the MCP server without the skill, but clients that support skills generally produce better results when both the connector and the skill are installed. +==== + +=== Before you begin + +* Connect the ThoughtSpot Spotter MCP Server to your client. +See xref:mcp-server-client-connection.adoc#_using_thoughtspot_spotter_with_chatgpt_and_claude[Using ThoughtSpot Spotter with ChatGPT and Claude] and the connection sections above. +* Confirm your client supports skills. +Clients without skill support can still use the MCP Server directly; the skill is an enhancement, not a requirement. + +=== Adding the skill + +. Get the ThoughtSpot skill (`analyzing-data-with-thoughtspot`) from the link:https://github.com/thoughtspot/mcp-server/tree/main/skills[ThoughtSpot MCP Server repository, window=_blank]. +. Add the skill in your client, following the client's documentation for installing and enabling skills. +. Confirm the skill is enabled and loaded in your client. + +=== Verifying the skill + +. Start a chat session with the agent and ask a data question. +. Verify that the ThoughtSpot MCP tools are being called to generate the response. +See the xref:mcp-tool-reference-guide.adoc[MCP tool reference guide] for information about tool calls. +. Confirm the skill is influencing behavior. For example, more accurate data-context selection, cleaner chart generation, and successful Liveboard creation from the conversation. + +[NOTE] +==== +Skill availability and installation steps may vary by client. Refer to your client's documentation for instructions on adding and managing skills. +==== + == Troubleshooting errors MCP Server is not connected:: From 134cf5d7a39c4308e0a0522cb6fab504700ddf18 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Thu, 6 Aug 2026 08:55:48 +0530 Subject: [PATCH 012/154] menu and css edits for typedoc files --- modules/ROOT/pages/common/nav-mcp-server.adoc | 4 +-- src/assets/styles/index.scss | 25 +++++++++++++++++++ 2 files changed, 27 insertions(+), 2 deletions(-) diff --git a/modules/ROOT/pages/common/nav-mcp-server.adoc b/modules/ROOT/pages/common/nav-mcp-server.adoc index 7f98f2117..e1be3a313 100644 --- a/modules/ROOT/pages/common/nav-mcp-server.adoc +++ b/modules/ROOT/pages/common/nav-mcp-server.adoc @@ -8,8 +8,8 @@ ThoughtSpot Spotter MCP Server * link:{{navprefix}}/mcp-integration[Overview] -** link:{{navprefix}}/mcp-server-spotter3[MCP Server with Spotter 3] -** link:{{navprefix}}/mcp-server-legacy[Legacy MCP Server architecture and tools] +* link:{{navprefix}}/mcp-server-spotter3[MCP Server with Spotter 3] +* link:{{navprefix}}/mcp-server-legacy[Legacy MCP Server architecture and tools] * link:{{navprefix}}/connect-mcp-server-to-clients[Connecting MCP Server to clients] * link:{{navprefix}}/custom-chatbot-integration-mcp[Integrating MCP Server in a custom app] diff --git a/src/assets/styles/index.scss b/src/assets/styles/index.scss index baf0ec97c..6ecb6ed39 100644 --- a/src/assets/styles/index.scss +++ b/src/assets/styles/index.scss @@ -1100,6 +1100,31 @@ a.anchor { background-position: -136px -68px; } } + +#wrapper[data-theme='dark'], +#docsModal[data-theme='dark'] { + .typedoc-Type_alias a, + .typedoc-Function a { + color: #71a1f4; + } + .typedoc-Type_alias :before, + .typedoc-Function :before { + background-image: none; + background-color: #71a1f4; + -webkit-mask-repeat: no-repeat; + mask-repeat: no-repeat; + -webkit-mask-image: url(../icons/icons.png); + mask-image: url(../icons/icons.png); + } + .typedoc-Type_alias :before { + -webkit-mask-position: 0px -170px; + mask-position: 0px -170px; + } + .typedoc-Function :before { + -webkit-mask-position: -136px -68px; + mask-position: -136px -68px; + } +} .header-banner { min-height: 240px; background: var(--header-banner-background); From 9ea4df8a30f2f9edaa2d381f0d868ffe550f7c72 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Tue, 11 Aug 2026 10:51:51 +0530 Subject: [PATCH 013/154] changelog update --- modules/ROOT/pages/mcp-server-changelog.adoc | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/modules/ROOT/pages/mcp-server-changelog.adoc b/modules/ROOT/pages/mcp-server-changelog.adoc index abb14bda8..96ab29bb6 100644 --- a/modules/ROOT/pages/mcp-server-changelog.adoc +++ b/modules/ROOT/pages/mcp-server-changelog.adoc @@ -24,6 +24,25 @@ This changelog lists the new features, enhancements, and other changes introduce // *Affects:* Developers, Administrators, End Users // ============================================================ +== August 2026 +*API version string:* `?api-version=2026-05-01` + +*Upgrade notes*: Existing integrations using `?api-version=2026-05-01` or `?api-version=latest` will be automatically upgraded. + +[.cl-table, cols="1,4", frame=none, grid=none] +|==== +a| +[.cl-label] +*2026-08-10* + +a| + +[discrete] +==== ThoughtSpot skill for skill-aware LLM clients [.version-badge.new]#New# +A companion skill, `analyzing-data-with-thoughtspot` is now available for LLM clients that support skills, such as Claude. +Install the skill alongside the ThoughtSpot Spotter MCP Server to improve how the client orchestrates ThoughtSpot MCP tools, including smarter routing of data questions, real-time progress narration during polling, and surfacing ThoughtSpot-generated visualization links instead of regenerating charts. + +For more information, see xref:mcp-server-client-connection.adoc#_using_the_thoughtspot_skill_with_skill_aware_clients[Using the ThoughtSpot skill with skill-aware clients]. +|==== == July 2026 *API version string:* `?api-version=2026-05-01` + From 89804e22ef6947fadb77cd78dbd74edb3b36f8ca Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Tue, 11 Aug 2026 20:18:26 +0530 Subject: [PATCH 014/154] changelog edits --- modules/ROOT/pages/mcp-server-changelog.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/ROOT/pages/mcp-server-changelog.adoc b/modules/ROOT/pages/mcp-server-changelog.adoc index 96ab29bb6..9938078e4 100644 --- a/modules/ROOT/pages/mcp-server-changelog.adoc +++ b/modules/ROOT/pages/mcp-server-changelog.adoc @@ -32,7 +32,7 @@ This changelog lists the new features, enhancements, and other changes introduce |==== a| [.cl-label] -*2026-08-10* +*2026-05-01* a| @@ -52,7 +52,7 @@ For more information, see xref:mcp-server-client-connection.adoc#_using_the_thou |==== a| [.cl-label] -*2026-07-10* +*2026-05-01* a| From 23aaa8307875f2a826eb4a1575bea9ab0d4e90d3 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Tue, 11 Aug 2026 21:43:05 +0530 Subject: [PATCH 015/154] edits --- modules/ROOT/pages/mcp-server-changelog.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/mcp-server-changelog.adoc b/modules/ROOT/pages/mcp-server-changelog.adoc index 9938078e4..9fad5a7c1 100644 --- a/modules/ROOT/pages/mcp-server-changelog.adoc +++ b/modules/ROOT/pages/mcp-server-changelog.adoc @@ -37,7 +37,7 @@ a| a| [discrete] -==== ThoughtSpot skill for skill-aware LLM clients [.version-badge.new]#New# +==== ThoughtSpot skill for skill-aware LLM clients A companion skill, `analyzing-data-with-thoughtspot` is now available for LLM clients that support skills, such as Claude. Install the skill alongside the ThoughtSpot Spotter MCP Server to improve how the client orchestrates ThoughtSpot MCP tools, including smarter routing of data questions, real-time progress narration during polling, and surfacing ThoughtSpot-generated visualization links instead of regenerating charts. From cdc94a8c83647a948fbeb91b22c040b752302331 Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Wed, 12 Aug 2026 10:11:46 +0530 Subject: [PATCH 016/154] edited based on feedback --- modules/ROOT/pages/embed-pinboard.adoc | 2 +- modules/ROOT/pages/filters_overview.adoc | 2 +- modules/ROOT/pages/runtime-filters.adoc | 6 +++--- modules/ROOT/pages/runtime-overrides.adoc | 8 +++++--- 4 files changed, 10 insertions(+), 8 deletions(-) diff --git a/modules/ROOT/pages/embed-pinboard.adoc b/modules/ROOT/pages/embed-pinboard.adoc index 80de55335..b0c39e1d5 100644 --- a/modules/ROOT/pages/embed-pinboard.adoc +++ b/modules/ROOT/pages/embed-pinboard.adoc @@ -298,7 +298,7 @@ To view specific data across the tables and charts on an embedded Liveboard, use ==== Runtime filter limits vary by input path. URL-based runtime filters are capped at 50. When using the Visual Embed SDK `runtimeFilters` property, the limit is configurable by a -ThoughtSpot administrator, with a default and maximum of 1,000. Filters beyond the enforced +ThoughtSpot administrator, with a default and maximum of 1,000 runtime filters. Filters beyond the enforced limit are silently dropped without an error or warning. For more information, see xref:runtime-filters.adoc#_maximum_filter_count[Runtime filter limit]. ==== diff --git a/modules/ROOT/pages/filters_overview.adoc b/modules/ROOT/pages/filters_overview.adoc index f76e75d8f..fe4672d0d 100644 --- a/modules/ROOT/pages/filters_overview.adoc +++ b/modules/ROOT/pages/filters_overview.adoc @@ -30,7 +30,7 @@ You can define xref:runtime-filters.adoc[runtime filters] and xref:runtime-param * Runtime filters do not display as UI filter components. * Runtime filter limits vary by input path. URL-based runtime filters are capped at 50. When using the Visual Embed SDK `runtimeFilters` property, the limit is configurable by a -ThoughtSpot administrator, with a default and maximum of 1,000. Filters beyond the enforced +ThoughtSpot administrator, with a default and maximum of 1,000 runtime filters. Filters beyond the enforced limit are silently dropped without an error or warning. See xref:runtime-filters.adoc#_maximum_filter_count[Runtime filter limit] for more information. ==== diff --git a/modules/ROOT/pages/runtime-filters.adoc b/modules/ROOT/pages/runtime-filters.adoc index de21f1bf3..745ab1618 100644 --- a/modules/ROOT/pages/runtime-filters.adoc +++ b/modules/ROOT/pages/runtime-filters.adoc @@ -58,10 +58,10 @@ through `col49`/`op49`/`val49` are processed; `col50` and above are ignored. Embed payload runtime filters (Visual Embed SDK):: When you pass runtime filters as an array in the SDK initialization config for `LiveboardEmbed`, `AppEmbed`, `SpotterEmbed` and -`SearchEmbed` using the `runtimeFilters` property in the Visual Embed SDK, ThoughtSpot applies a configurable limit. The default and maximum value is 1000 filters. +`SearchEmbed` using the `runtimeFilters` property in the Visual Embed SDK, ThoughtSpot applies a configurable limit. The default and maximum value is 1000 runtime filters. + +Contact ThoughtSpot support to configure this limit for your instance. The value for the number of filters must be between 1 and 1000. -ThoughtSpot administrators can configure this limit for their instance. The value must be between 1 and 1000. -To check or update the configured limit, contact your ThoughtSpot administrator. [IMPORTANT] ==== diff --git a/modules/ROOT/pages/runtime-overrides.adoc b/modules/ROOT/pages/runtime-overrides.adoc index 96ef02ad6..44093dd9d 100644 --- a/modules/ROOT/pages/runtime-overrides.adoc +++ b/modules/ROOT/pages/runtime-overrides.adoc @@ -21,12 +21,14 @@ Developers can set runtime filters in the Visual Embed SDK for the following emb After the object loads, runtime filters can be xref:runtime-filters.adoc#_adjust_runtime_filters_using_sdk_events[adjusted using the SDK events]. -WARNING: Runtime filter limits vary by input path. URL-based runtime filters are capped at 50. +[IMPORTANT] +==== +Runtime filter limits vary by input path. URL-based runtime filters are capped at 50. When using the Visual Embed SDK `runtimeFilters` property, the limit is configurable by a -ThoughtSpot administrator, with a default and maximum of 1,000. Filters beyond the enforced +ThoughtSpot administrator, with a default and maximum of 1,000 runtime filters. Filters beyond the enforced limit are silently dropped without an error or warning. See xref:runtime-filters.adoc#_maximum_filter_count[Runtime filter limit] for more information. - +==== == Runtime Parameters Parameters allow users to visualize data by running different scenarios with adjustable values. You can use Parameters within formulas when analyzing your data via Search, Liveboards, or Answers. From 21fa9bb3dcd52d82b9845a730609ae07a11aef66 Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Wed, 12 Aug 2026 12:29:40 +0530 Subject: [PATCH 017/154] collections sdk support --- modules/ROOT/pages/collections.adoc | 8 ++--- .../ROOT/pages/customize-nav-full-embed.adoc | 30 +++++++++++++++++++ 2 files changed, 34 insertions(+), 4 deletions(-) diff --git a/modules/ROOT/pages/collections.adoc b/modules/ROOT/pages/collections.adoc index 4a5cf27ca..62cabb52c 100644 --- a/modules/ROOT/pages/collections.adoc +++ b/modules/ROOT/pages/collections.adoc @@ -9,10 +9,10 @@ ThoughtSpot now provides REST APIs that enable developers to organize different ThoughtSpot objects into an organizational container called *Collections*. These objects can be Liveboards, Answers, data models, tables, and even other Collections. Collections provide a powerful way to manage your data assets, making discovery and collaboration easier, while ensuring the integrity of embedded workflows. -[NOTE] -==== -The Collections APIs are in Beta and disabled by default on ThoughtSpot instances. To enable these APIs on your instance, contact ThoughtSpot Support. -==== +You can also embed the Collections page directly in your application using the Visual Embed SDK. +To navigate users to the Collections page in full application embedding, set `pageId` to `Page.Collections` in `AppViewConfig`. +For more information, see xref:customize-nav-full-embed.adoc#_navigate_to_the_collections_page[Navigate to the Collections page]. + == Before you begin diff --git a/modules/ROOT/pages/customize-nav-full-embed.adoc b/modules/ROOT/pages/customize-nav-full-embed.adoc index b90c71995..92d34d7b5 100644 --- a/modules/ROOT/pages/customize-nav-full-embed.adoc +++ b/modules/ROOT/pages/customize-nav-full-embed.adoc @@ -104,6 +104,31 @@ const embed = new AppEmbed("#embed", { == Command palette availability in embed In ThoughtSpot application, users can open the link:https://docs.thoughtspot.com/cloud/latest/thoughtspot-homepage#command-palette[command palette] by pressing kbd:[Cmd+K] on macOS or kbd:[Ctrl+K] on Windows to quickly navigate to objects and perform actions. However, when you embed ThoughtSpot, this feature is disabled and embedded pages include only the standard object search experience. +== Navigate to the Collections page + +To set the Collections page as the default landing page for full application embedding, use `Page.Collections` in the `pageId` property of `AppViewConfig`. + +// SOURCE: https://github.com/thoughtspot/visual-embed-sdk/blob/master/src/embed/app.ts + +[source,JavaScript] +---- +import { AppEmbed, Page } from '@thoughtspot/visual-embed-sdk'; + +const embed = new AppEmbed('#tsEmbed', { + // ... other embed view config + pageId: Page.Collections, + showPrimaryNavbar: true, +}); +embed.render(); +---- + +You can also use `navigateToPage` to route users to the Collections page programmatically after the app loads: + +[source,JavaScript] +---- +appEmbed.navigateToPage('collections'); +---- + == Customize the left navigation panel on the home page In the V3 and V4 experience modes, the left navigation panel on the *Insights* > *Home* page includes menu items such as *Spotter*, *Answers*, *Liveboards*, *SpotIQ Analysis*, *Monitor Subscriptions*, and more. You can hide this navigation panel by setting the `hideHomepageLeftNav` property to `true` in the SDK. Note that this attribute hides the left navigation only on the home page. @@ -181,6 +206,11 @@ To show or hide the *Scheduled Liveboards* section in the | [tag greenBackground tick]#✓# Supported | [tag greenBackground tick]#✓# Supported +| `HomeLeftNavItem.Collections` + +To show or hide the *Collections* menu item in the *Insights* left navigation panel. +| [tag greenBackground tick]#✓# Supported +| [tag greenBackground tick]#✓# Supported + |==== From 238fb9322060d9f4f0df40916461f484df416d13 Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Wed, 12 Aug 2026 13:48:17 +0530 Subject: [PATCH 018/154] highlighted coll changes --- modules/ROOT/pages/collections.adoc | 4 ++-- modules/ROOT/pages/customize-nav-full-embed.adoc | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/modules/ROOT/pages/collections.adoc b/modules/ROOT/pages/collections.adoc index 62cabb52c..614c2d713 100644 --- a/modules/ROOT/pages/collections.adoc +++ b/modules/ROOT/pages/collections.adoc @@ -9,9 +9,9 @@ ThoughtSpot now provides REST APIs that enable developers to organize different ThoughtSpot objects into an organizational container called *Collections*. These objects can be Liveboards, Answers, data models, tables, and even other Collections. Collections provide a powerful way to manage your data assets, making discovery and collaboration easier, while ensuring the integrity of embedded workflows. -You can also embed the Collections page directly in your application using the Visual Embed SDK. +#You can also embed the Collections page directly in your application using the Visual Embed SDK. To navigate users to the Collections page in full application embedding, set `pageId` to `Page.Collections` in `AppViewConfig`. -For more information, see xref:customize-nav-full-embed.adoc#_navigate_to_the_collections_page[Navigate to the Collections page]. +For more information, see xref:customize-nav-full-embed.adoc#_navigate_to_the_collections_page[Navigate to the Collections page].# == Before you begin diff --git a/modules/ROOT/pages/customize-nav-full-embed.adoc b/modules/ROOT/pages/customize-nav-full-embed.adoc index 92d34d7b5..f28daee1d 100644 --- a/modules/ROOT/pages/customize-nav-full-embed.adoc +++ b/modules/ROOT/pages/customize-nav-full-embed.adoc @@ -104,7 +104,7 @@ const embed = new AppEmbed("#embed", { == Command palette availability in embed In ThoughtSpot application, users can open the link:https://docs.thoughtspot.com/cloud/latest/thoughtspot-homepage#command-palette[command palette] by pressing kbd:[Cmd+K] on macOS or kbd:[Ctrl+K] on Windows to quickly navigate to objects and perform actions. However, when you embed ThoughtSpot, this feature is disabled and embedded pages include only the standard object search experience. -== Navigate to the Collections page +== #Navigate to the Collections page# To set the Collections page as the default landing page for full application embedding, use `Page.Collections` in the `pageId` property of `AppViewConfig`. @@ -207,7 +207,7 @@ To show or hide the *Scheduled Liveboards* section in the | [tag greenBackground tick]#✓# Supported | `HomeLeftNavItem.Collections` + -To show or hide the *Collections* menu item in the *Insights* left navigation panel. +#To show or hide the *Collections* menu item in the *Insights* left navigation panel.# | [tag greenBackground tick]#✓# Supported | [tag greenBackground tick]#✓# Supported From db8f9bfd96396e4fdd2a67279707a8e95a5de349 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Wed, 12 Aug 2026 19:40:45 +0530 Subject: [PATCH 019/154] docs: add Snowflake Semantic View integration API reference (SCAL-309867) New page covering the four semantic-integrations REST API v2.0 endpoints introduced in 26.9.0.cl: create, search, import, and delete. Parameters, required privileges, enums, and response fields sourced directly from prism/src/public-apis/semantic-integrations.graphql and the description docs in scaligent master." --- .../ROOT/pages/semantic-integrations-api.adoc | 409 ++++++++++++++++++ 1 file changed, 409 insertions(+) create mode 100644 modules/ROOT/pages/semantic-integrations-api.adoc diff --git a/modules/ROOT/pages/semantic-integrations-api.adoc b/modules/ROOT/pages/semantic-integrations-api.adoc new file mode 100644 index 000000000..4fc5ead75 --- /dev/null +++ b/modules/ROOT/pages/semantic-integrations-api.adoc @@ -0,0 +1,409 @@ += Snowflake Semantic View integration APIs +:toc: true +:toclevels: 3 + +:page-title: Snowflake Semantic View integration APIs +:page-pageid: semantic-integrations-api +:page-description: Use the ThoughtSpot REST API v2.0 endpoints to create, search, import, and delete Snowflake Semantic View integration configurations programmatically. + +// SOURCE: SCAL-309867 +// SOURCE: scaligent/prism/src/public-apis/semantic-integrations.graphql (master) +// SOURCE: scaligent/prism/src/public-apis/docs/descriptions/semantic-integrations/ (master) + +ThoughtSpot 26.9.0.cl introduces REST API v2.0 endpoints for managing Snowflake Semantic View integrations. These APIs allow administrators and data managers to create, search, import, and delete semantic integration configurations programmatically, without using the ThoughtSpot UI. + +== Overview + +Snowflake Semantic Views provide a governed semantic layer for data in Snowflake, including named measures, dimensions, and business-logic formulas. When you create a semantic integration in ThoughtSpot, the platform reads the semantic view definition from Snowflake and generates a corresponding ThoughtSpot data model (Worksheet). The model inherits the column names, descriptions, and formula definitions from the Snowflake Semantic View. + +You can use the semantic integration APIs to automate the following tasks: + +* Create a semantic integration that links a Snowflake Semantic View to a ThoughtSpot data model. +* Search and list existing semantic integrations. +* Re-import a semantic integration to refresh the ThoughtSpot model after the source Snowflake Semantic View has changed. +* Delete a semantic integration and its generated ThoughtSpot model. + +[NOTE] +==== +The semantic integration APIs are available on ThoughtSpot Cloud instances from 26.9.0.cl. +Snowflake is the only supported CDW connector type (`RDBMS_SNOWFLAKE`). +==== + +== Prerequisites + +To use these APIs, the authenticated user must have one of the following privileges: + +* `ADMINISTRATION` (*Can administer ThoughtSpot*) +* `DATAMANAGEMENT` (*Can manage data*) + +If Role-Based Access Control (RBAC) is enabled on your instance, the user must also have: + +* `CAN_CREATE_OR_EDIT_CONNECTIONS` (*Can create/edit Connections*) +* *Can manage data models* + +== API endpoints + +[width="100%"] +[options="header"] +|===== +| Method | Endpoint | Description +| `POST` | `/api/rest/2.0/semantic-integrations/create` | Creates a new semantic integration by reading a Snowflake Semantic View and generating a ThoughtSpot data model. +| `POST` | `/api/rest/2.0/semantic-integrations/search` | Returns a list of semantic integrations matching the specified filter criteria. +| `POST` | `/api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/import` | Re-imports semantic updates from the CDW source and refreshes the associated ThoughtSpot data model. +| `POST` | `/api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/delete` | Deletes a semantic integration and its generated ThoughtSpot data model. +|===== + +[#create-semantic-integration] +== Create a semantic integration + +`POST /api/rest/2.0/semantic-integrations/create` + +Creates a new semantic integration by reading the specified Snowflake Semantic View and generating a corresponding ThoughtSpot data model. On success, the response includes the integration GUID, the generated model GUID, and a per-formula import report. + +=== Required privileges + +`ADMINISTRATION` or `DATAMANAGEMENT`. If RBAC is enabled: `CAN_CREATE_OR_EDIT_CONNECTIONS` and *Can manage data models*. + +=== Request parameters + +[width="100%"] +[options="header"] +|===== +| Parameter | Type | Required | Description +| `connection_identifier` | String | Yes | GUID or name of the Snowflake connection in ThoughtSpot. +| `name` | String | Yes | Display name for the semantic integration. Must be unique. +| `database_name` | String | Yes | Database name in the Snowflake CDW that contains the semantic view. +| `schema_name` | String | Yes | Schema name in the Snowflake CDW that contains the semantic view. +| `semantic_view_name` | String | Yes | Name of the Snowflake Semantic View to integrate. +| `type` | String | Yes | CDW connector type. Only accepted value: `RDBMS_SNOWFLAKE`. +| `description` | String | No | Optional description for the semantic integration. +| `tags` | Array | No | Tag GUIDs or names to associate with the integration. +|===== + +=== Response fields + +[width="100%"] +[options="header"] +|===== +| Field | Type | Description +| `id` | String | GUID of the newly created semantic integration. +| `name` | String | Display name of the semantic integration. +| `model_id` | String | GUID of the ThoughtSpot data model generated for this integration. +| `model_name` | String | Display name of the generated ThoughtSpot data model. +| `semantic_report` | Object | Per-formula import report. See <<_semantic_report_fields>>. +|===== + +[#semantic-report-fields] +=== Semantic report fields + +The `semantic_report` object contains a summary and a list of per-formula import results. + +`summary` fields: + +[width="100%"] +[options="header"] +|===== +| Field | Type | Description +| `total` | Integer | Total number of formulas in the Snowflake Semantic View. +| `imported` | Integer | Number of formulas successfully imported. +| `failed` | Integer | Number of formulas that failed to import. +| `skipped` | Integer | Number of formulas that were skipped. +|===== + +`formulas` array — each entry contains: + +[width="100%"] +[options="header"] +|===== +| Field | Type | Description +| `id` | String | Formula GUID in the generated ThoughtSpot model. +| `name` | String | Formula name. +| `description` | String | Formula description. +| `source_expression` | String | Original CDW expression. +| `translated_formula` | String | Equivalent ThoughtSpot formula expression. +| `import_status` | String | One of `IMPORTED`, `FAILED`, or `SKIPPED`. +| `change_status` | String | One of `NEW`, `UPDATED`, or `UNCHANGED`. Null on initial create (populated by import). +|===== + +=== Example request + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/semantic-integrations/create' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "connection_identifier": "", + "name": "Sales Semantic View", + "database_name": "SALES_DB", + "schema_name": "PUBLIC", + "semantic_view_name": "SALES_SEMANTIC_VIEW", + "type": "RDBMS_SNOWFLAKE", + "description": "Semantic integration for the Sales Snowflake Semantic View" +}' +---- + +=== Example response + +[source,JSON] +---- +{ + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Sales Semantic View", + "model_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", + "model_name": "Sales Semantic View", + "semantic_report": { + "summary": { + "total": 5, + "imported": 4, + "failed": 0, + "skipped": 1 + }, + "formulas": [ + { + "id": "formula-guid-001", + "name": "Total Revenue", + "description": "Sum of all revenue", + "source_expression": "SUM(revenue)", + "translated_formula": "sum(revenue)", + "import_status": "IMPORTED", + "change_status": null + } + ] + } +} +---- + +[#search-semantic-integrations] +== Search semantic integrations + +`POST /api/rest/2.0/semantic-integrations/search` + +Returns a paginated list of semantic integrations matching the specified criteria. Returns all integrations if no filters are specified. + +=== Required privileges + +`ADMINISTRATION` or `DATAMANAGEMENT`. If RBAC is enabled: `CAN_CREATE_OR_EDIT_CONNECTIONS` and *Can manage data models*. + +=== Request parameters + +[width="100%"] +[options="header"] +|===== +| Parameter | Type | Required | Description +| `pattern` | String | No | Substring filter to narrow search results by integration name. +| `author_identifiers` | Array | No | Filter by the GUID or username of the user who created the integration. +| `connection_identifiers` | Array | No | Filter by the GUID or name of the Snowflake connection associated with the integration. +| `sort_options` | Object | No | Sort configuration. See <<_sort_options>>. +| `record_offset` | Integer | No | Number of records to skip for pagination. Minimum: 0. Default: 0. +| `record_size` | Integer | No | Maximum number of records to return. Use `0` to return all records. Default: 10. +|===== + +[#sort-options] +==== Sort options + +[width="100%"] +[options="header"] +|===== +| Field | Type | Description +| `field_name` | String | Sort field. One of: `NAME`, `AUTHOR`, `CREATED_TIME`, `MODIFIED_TIME`. +| `order` | String | Sort direction. `ASC` for ascending, `DESC` for descending. +|===== + +=== Response fields + +Returns an array of objects, each with the following fields: + +[width="100%"] +[options="header"] +|===== +| Field | Type | Description +| `id` | String | GUID of the semantic integration. +| `name` | String | Display name of the semantic integration. +| `description` | String | Description of the semantic integration. Null if not set. +| `model_id` | String | GUID of the associated ThoughtSpot data model. +| `model_name` | String | Display name of the associated ThoughtSpot data model. +| `import_type` | String | How the semantic definition was sourced. `CDW` for Snowflake Semantic View; `FILE` for file upload. +| `type` | String | CDW connector type. Currently always `RDBMS_SNOWFLAKE`. +| `connection_id` | String | GUID of the Snowflake connection. +| `connection_name` | String | Display name of the Snowflake connection. +| `author_id` | String | GUID of the user who created the integration. +| `author_name` | String | Username of the user who created the integration. +| `creation_time_in_millis` | Float | Creation time in Unix epoch milliseconds. +| `modification_time_in_millis` | Float | Last modification time in Unix epoch milliseconds. +| `tags` | Array | Tags associated with the integration, each with `id` and `name`. +|===== + +=== Example request + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/semantic-integrations/search' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "connection_identifiers": [""], + "sort_options": { + "field_name": "MODIFIED_TIME", + "order": "DESC" + }, + "record_size": 20, + "record_offset": 0 +}' +---- + +[#import-semantic-integration] +== Import a semantic integration + +`POST /api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/import` + +Re-imports semantic updates from the Snowflake CDW source for an existing integration, and rebuilds the corresponding ThoughtSpot data model. Use this endpoint after the source Snowflake Semantic View has been updated (formulas added, removed, or modified) to bring the ThoughtSpot model back in line with the CDW definition. + +[NOTE] +==== +Importing updates is not supported for integrations created using the file upload option in the ThoughtSpot UI. To refresh a file-upload-based integration, use the ThoughtSpot UI. +==== + +The import operation: + +* Preserves the integration GUID, name, and `model_id`. Only the formula set is refreshed. +* Returns the same `semantic_report` response as create, with an additional `change_status` per formula indicating whether each formula is `NEW`, `UPDATED`, or `UNCHANGED` since the previous import. + +=== Required privileges + +`ADMINISTRATION` or `DATAMANAGEMENT`. If RBAC is enabled: `CAN_CREATE_OR_EDIT_CONNECTIONS` and *Can manage data models*. + +=== Path parameters + +[width="100%"] +[options="header"] +|===== +| Parameter | Type | Required | Description +| `semantic_integration_identifier` | String | Yes | GUID or name of the semantic integration to re-import. +|===== + +=== Response fields + +Same as <>, with the addition of the `change_status` field in each formula entry: + +[width="100%"] +[options="header"] +|===== +| `change_status` value | Description +| `NEW` | Formula is new since the previous import. +| `UPDATED` | Formula definition changed since the previous import. +| `UNCHANGED` | Formula is unchanged since the previous import. +|===== + +=== Example request + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/semantic-integrations/Sales%20Semantic%20View/import' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + --data-raw '{}' +---- + +=== Example response + +[source,JSON] +---- +{ + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Sales Semantic View", + "model_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", + "model_name": "Sales Semantic View", + "semantic_report": { + "summary": { + "total": 6, + "imported": 5, + "failed": 0, + "skipped": 1 + }, + "formulas": [ + { + "id": "formula-guid-001", + "name": "Total Revenue", + "description": "Sum of all revenue", + "source_expression": "SUM(revenue)", + "translated_formula": "sum(revenue)", + "import_status": "IMPORTED", + "change_status": "UNCHANGED" + }, + { + "id": "formula-guid-002", + "name": "Net Profit", + "description": "Revenue minus costs", + "source_expression": "SUM(revenue) - SUM(costs)", + "translated_formula": "sum(revenue) - sum(costs)", + "import_status": "IMPORTED", + "change_status": "NEW" + } + ] + } +} +---- + +[#delete-semantic-integration] +== Delete a semantic integration + +`POST /api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/delete` + +Permanently deletes the specified semantic integration and its generated ThoughtSpot data model from the system. + +[WARNING] +==== +Deletion is permanent and cannot be undone. If you need to restore the integration, use the `create` endpoint to re-import the Snowflake Semantic View. +==== + +=== Required privileges + +`ADMINISTRATION` or `DATAMANAGEMENT`. If RBAC is enabled: `CAN_CREATE_OR_EDIT_CONNECTIONS` and *Can manage data models*. + +=== Path parameters + +[width="100%"] +[options="header"] +|===== +| Parameter | Type | Required | Description +| `semantic_integration_identifier` | String | Yes | GUID or name of the semantic integration to delete. +|===== + +=== Example request + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/semantic-integrations/Sales%20Semantic%20View/delete' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + --data-raw '{}' +---- + +A successful delete returns HTTP `200` with an empty response body. + +== Error responses + +[width="100%"] +[options="header"] +|===== +| Code | Description +| 400 | Bad Request — required parameter missing or invalid value (for example, unsupported `type`). +| 401 | Unauthorized — authentication token missing, expired, or invalid. +| 403 | Forbidden — the caller lacks the required privilege. +| 404 | Not Found — no semantic integration exists with the given identifier. +|===== + +== Related resources + +* xref:connections.adoc[Data connections] +* xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog] +* xref:rest-api-v2-reference.adoc[REST API v2.0 reference] From d188100425015d7c7925e9446002274cfaee6d97 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 17 Aug 2026 09:31:00 +0530 Subject: [PATCH 020/154] test: verify write access --- modules/ROOT/pages/.write-test | 1 + 1 file changed, 1 insertion(+) create mode 100644 modules/ROOT/pages/.write-test diff --git a/modules/ROOT/pages/.write-test b/modules/ROOT/pages/.write-test new file mode 100644 index 000000000..0e808f9c2 --- /dev/null +++ b/modules/ROOT/pages/.write-test @@ -0,0 +1 @@ +write access test - delete me \ No newline at end of file From a2f4016b29db53d0179e3bd7e09567e194bee0be Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 17 Aug 2026 09:40:29 +0530 Subject: [PATCH 021/154] docs: add 26.9.0.cl REST API changelog entries (SCAL-306069, SCAL-309867, SCAL-306173, SCAL-320899, SCAL-317550, SCAL-307284, SCAL-312738, SCAL-277656) --- modules/ROOT/pages/rest-apiv2-changelog.adoc | 1381 ++++-------------- 1 file changed, 249 insertions(+), 1132 deletions(-) diff --git a/modules/ROOT/pages/rest-apiv2-changelog.adoc b/modules/ROOT/pages/rest-apiv2-changelog.adoc index 22e0cfcaf..eaeeff350 100644 --- a/modules/ROOT/pages/rest-apiv2-changelog.adoc +++ b/modules/ROOT/pages/rest-apiv2-changelog.adoc @@ -8,6 +8,122 @@ This changelog lists the features and enhancements introduced in REST API v2.0. For information about new features and enhancements available for embedded analytics, see xref:whats-new.adoc[What's New]. +== Version 26.9.0.cl, September 2026 + +=== Answer Export API enhancements — General Availability + +// SOURCE: SCAL-306069 + +The `POST /api/rest/2.0/report/answer` endpoint is generally available from 26.9.0.cl. The `isAnswerExportV2Enabled` flag is enabled by default on all ThoughtSpot Cloud instances. The following enhancements are included in this release: + +Pinned Answer export:: +Pass `viz_guid` to export a pinned Answer (a visualization on a Liveboard) directly. Liveboard-level filters and runtime overrides are applied automatically. The `metadata_identifier` must be the parent Liveboard GUID or name. + +Personalized View support:: +Pass `personalised_view_identifier` to export data from a specific Personalized View of a Liveboard. + +Spotter Answer export:: +XLSX and PDF export formats are now supported for Spotter-generated (ad hoc) Answers, in addition to CSV and PNG. + +Custom PNG dimensions:: +Use `x_resolution` and `y_resolution` parameters to specify custom pixel dimensions for PNG exports. Accepted range: 600–3840 px per axis. + +Display scaling:: +Use `scaling_factor` (range: 80–400) to adjust the relative size of chart elements in a PNG export without cropping the image. + +Dynamic file naming:: +Exported files are automatically named based on the Answer title with the correct file extension (`.png`, `.pdf`, `.csv`, `.xlsx`) appended. + +For more information, see xref:data-report-v2-api.adoc#answer-report[Answer Report API]. + +=== Snowflake Semantic View integration APIs + +// SOURCE: SCAL-309867 + +ThoughtSpot 26.9.0.cl introduces REST API v2.0 endpoints for managing Snowflake Semantic View integrations programmatically. These APIs allow administrators and data managers to create, search, import, and delete semantic integration configurations without using the ThoughtSpot UI. + +[width="100%"] +[options="header"] +|===== +| Method | Endpoint | Description +| `POST` | `/api/rest/2.0/semantic-integrations/create` | Creates a new semantic integration by reading a Snowflake Semantic View and generating a ThoughtSpot data model. +| `POST` | `/api/rest/2.0/semantic-integrations/search` | Returns a list of semantic integrations matching the specified filter criteria. +| `POST` | `/api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/import` | Re-imports semantic updates from Snowflake and refreshes the associated ThoughtSpot data model. +| `POST` | `/api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/delete` | Deletes a semantic integration and its generated ThoughtSpot data model. +|===== + +For more information, see xref:semantic-integrations-api.adoc[Snowflake Semantic View integration APIs]. + +=== Spotter Memory — General Availability + +// SOURCE: SCAL-306173 + +The Spotter Memory feature is generally available from 26.9.0.cl. The memory APIs introduced in 26.8.0.cl (`POST /api/rest/2.0/ai/memory/import` and `POST /api/rest/2.0/ai/memory/export`) are enabled by default on all ThoughtSpot Cloud instances. Administrators can manage and audit Spotter training data programmatically without enabling a feature flag. + +For more information, see xref:spotter-ai-memory-api.adoc[Spotter memory APIs]. + +=== Spotter Agent — Conversation sharing APIs + +// SOURCE: SCAL-306173 (aug.26.mt) + +ThoughtSpot 26.9.0.cl introduces REST API v2.0 endpoints for sharing saved Spotter agent conversations with other users or groups. + +[width="100%"] +[options="header"] +|===== +| Method | Endpoint | Description +| `POST` | `/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` | Shares a saved Spotter conversation with specified principals. Use `grant` and `revoke` arrays to manage access. Shared conversations are always `READ_ONLY`. +| `GET` | `/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content` | Returns the content of a shared Spotter conversation — messages, data sources, and answer details. +| `GET` | `/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info` | Returns sharing metadata — the list of principals the conversation is shared with and their access levels. +|===== + +For more information, see xref:spotter-agent-apis.adoc#_sharing_spotter_conversations[Sharing Spotter conversations]. + +=== KPI Sparkline setting in metadata search response + +// SOURCE: SCAL-320899 + +The `POST /api/rest/2.0/metadata/search` API response now includes the `isSparklineEnabled` field in the `AnswerSpecHeader` object for KPI chart type answers. This boolean field indicates whether the sparkline trend line is enabled for the KPI visualization. + +* `true` — the sparkline trend line is enabled. +* `false` — the sparkline is disabled. +* Absent — the answer was saved before this release and has not been re-saved. Treat an absent field as unknown, not as `false`. + +=== Outline Encoding — BYOC Muze + +// SOURCE: SCAL-317550 + +ThoughtSpot 26.9.0.cl promotes mark outline color to a first-class data-driven encoding channel in the Muze charting library (BYOC). Developers building custom charts with Muze can now bind a data field to `encoding.outline` to produce ordinal color palettes (for categorical fields) or continuous gradient ramps (for measures), with full legend rendering and legend-to-mark interaction. + +The static `outline` config (`{ fill, color, width, dash }`) remains fully backward compatible. Width and dash remain per-datum value functions. Text marks are out of scope for outline encoding. Supported mark types in 26.9.0.cl: Point, Bar, Arc. + +=== Personalized Views TML portability — General Availability + +// SOURCE: SCAL-307284 + +The Personalized Views TML portability feature introduced as Early Access in 26.8.0.cl is generally available from 26.9.0.cl. + +* The `author` field in Personalized View TML maps to the view owner's username or email, ensuring ownership is retained when a Liveboard is promoted across clusters or orgs. +* The `obj_id` field provides a stable cross-environment identifier for Personalized Views. +* Smart merge import: when importing a Liveboard TML that contains Personalized Views, ThoughtSpot preserves views that exist only in the target environment, appends new views from the imported TML, and updates views present in both. + +For more information, see xref:tml.adoc#personalized-views-portability[Personalized Views portability in TML]. + +=== Connection configuration — Scheduled Liveboards process type + +// SOURCE: SCAL-312738 + +ThoughtSpot 26.9.0.cl adds `SCHEDULED_LIVEBOARDS` as a new process type for Embrace connection configurations. Administrators can assign the Scheduled Liveboards process to a connection configuration, enabling ThoughtSpot to use the associated credentials when running scheduled Liveboard delivery jobs. Configurable via: + +* `POST /api/rest/2.0/connection/configuration/create` +* `PUT /api/rest/2.0/connection/configuration/{configuration_identifier}/update` + +=== AI Context — Spotter Optimization tab + +// SOURCE: SCAL-277656 + +The AI Context generation CTA has moved to the *Spotter Optimization* tab in 26.9.0.cl. This is a UX-only change with no API surface changes. Users now receive in-product notifications on completion or failure of context generation. New *Stop* and *Clear existing context* controls replace the previous Cancel and Delete buttons. + == Version 26.8.0.cl, August 2026 === Spotter AI APIs @@ -131,1236 +247,237 @@ Uploads a custom font file to ThoughtSpot. Returns custom fonts uploaded to the instance. * `PUT /api/rest/2.0/customization/styles/fonts/{font_identifier}/update` + -Updates the display name, weight, style, or color of an existing custom font. - -* `POST /api/rest/2.0/customization/styles/fonts/delete` + -Deletes one or more custom fonts from the font library. - -Logo export:: +Updates a custom font configuration. -* `POST /api/rest/2.0/customization/styles/logos/export` + -Exports the current logo files as a ZIP archive containing the default logo and the wide logo. +* `DELETE /api/rest/2.0/customization/styles/fonts/{font_identifier}/delete` + +Deletes a custom font. -For more information, see xref:customize-style-api.adoc[Style customization APIs]. +For more information, see xref:style-customization-api.adoc[Style customization APIs]. -=== Manual translation APIs -The manual translation API endpoints allow you to import, export, and delete translations of terms and labels that can be presented to the user based on their locale settings. +=== Tags API -* `POST /api/rest/2.0/localizations/manual-translation/import` + -Allows importing a CSV file containing translated terms and labels. -* `POST /api/rest/2.0/localizations/manual-translation/locales/{locale}/export` + -Retrieves all translations for a specific locale as a JSON map. -* `POST /api/rest/2.0/localizations/manual-translation/export` + -Downloads all manually translated terms and labels in the Org context as a CSV file. -* `POST /api/rest/2.0/localizations/manual-translation/delete` + -Deletes all manual translations from the Org. +New API endpoint:: +`POST /api/rest/2.0/tags/assign` + +Assigns tags to one or more metadata objects. The API request must include the tag identifier and a list of metadata object identifiers with their type. -For more information, see xref:manual-translation.adoc[Manual translations]. +=== Groups API -=== REST API Python SDK -The REST API Python SDK library artifacts are now available on link:https://pypi.org/project/thoughtspot-rest-api-sdk/[PyPI, window=_blank]. For information about how to install and use the SDK, see xref:rest-api-python-sdk.adoc[Python SDK]. +New API endpoint:: +`POST /api/rest/2.0/groups/{group_identifier}/users/remove` + +Removes users from a group. Specify the group identifier in the path and include the list of user identifiers in the request body. == Version 26.6.0.cl, June 2026 === Spotter AI APIs -Stop in-progress agent response:: - -* `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response` + -Stops a Spotter agent response that is currently in progress for a given conversation session. - -For more information, see xref:spotter-agent-apis.adoc#_stop_an_in_progress_agent_response[Stop an in-progress agent response]. - -=== Authentication -The following new endpoints allow searching for the authentication configuration at the cluster or Org level, and also allow enabling and disabling authentication. These endpoints currently support only trusted authentication. - -* `POST /api/rest/2.0/auth/configure` + -Enables or disables authentication at cluster or Org level for the specified auth type. -* `POST /api/rest/2.0/auth/search` + -Returns the authentication configuration for the specified auth type at cluster and Org level. - -=== Connection deactivate and activate API [beta betaBackground]^Beta^ - -// SOURCE: SCAL-294844, SCAL-294845, SCAL-278132 - -ThoughtSpot introduces REST API v2.0 endpoints to programmatically deactivate and activate data connections: - -* `POST /api/rest/2.0/connections/{connection_identifier}/status` + -Deactivates or activates a connection. - -=== Answer report API enhancements [earlyAccess eaBackground]#Early Access# +Answer Report API [earlyAccess eaBackground]#Early Access#:: +ThoughtSpot introduces the `POST /api/rest/2.0/report/answer` API endpoint to export Answer data programmatically. This endpoint supports saved Answers and returns data in `CSV`, `XLSX`, `PDF`, or `PNG` format. -The `POST /api/rest/2.0/report/answer` API endpoint introduces the following enhancements: +For more information, see xref:data-report-v2-api.adoc#answer-report[Answer Report API]. -Pinned Answer export:: -// SOURCE: SCAL-236681, SCAL-306548 -You can now export a pinned Answer directly from a Liveboard using the Answer report API. -To export a pinned Answer, specify the `viz_guid` parameter in your API request. -Exports from this endpoint inherently respect Liveboard-level filters, Runtime Filters, Column security rules, and JWT token context. -+ -To export a specific personalized view of a pinned Answer, include the `personalised_view_identifier` parameter. +Stop response API:: +ThoughtSpot introduces the `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response` API endpoint to stop an in-progress Spotter agent response. The conversation session remains active after the response stops. -Spotter Answer export:: -XLSX and PDF export formats are now supported for Spotter (conversational) Answers. +=== Orgs and Users API -Custom PNG dimensions:: -PNG exports now support custom dimensions via the following new parameters: -+ -* `x_resolution`: Sets the export width in pixels. Valid range: 600–3840 px. -* `y_resolution`: Sets the export height in pixels. Valid range: 600–3840 px. - -Display scaling:: -A new `scaling` parameter allows you to adjust the relative size of visual elements in PNG exports without cropping. -Valid range: 80–500%. +Import users from SCIM:: +ThoughtSpot 26.6.0.cl introduces the `POST /api/rest/2.0/users/import` API endpoint to import users from a SCIM provider to ThoughtSpot. The API request must include the user details in the SCIM format. -Automatic file naming:: -The API now automatically names exported files based on the Answer title and appends the correct file extension (`.png`, `.pdf`, `.csv`, or `.xlsx`). - -Contact ThoughtSpot Support to enable these settings for PNG downloads on your ThoughtSpot instance. -For more information, see xref:data-report-v2-api.adoc#_answer_report_api[Answer report API documentation]. - -=== Share metadata API: Collections support [beta betaBackground]^Beta^ - -The `POST /api/rest/2.0/security/metadata/share` endpoint now supports sharing Collections. +=== Roles API -To share a Collection, set `metadata_type` to `COLLECTION` in the request body. -For more information, see xref:collections.adoc#share-collection[Share a Collection]. +`GET /api/rest/2.0/roles` deprecated:: +The `GET /api/rest/2.0/roles` endpoint is deprecated in 26.6.0.cl. Use `POST /api/rest/2.0/roles/search` instead. == Version 26.5.0.cl, May 2026 -=== Sync connection metadata attributes -You can now synchronize connection metadata attributes from your Cloud Data Warehouse (CDW) with ThoughtSpot by sending a request to the `POST /api/rest/2.0/connections/{connection_identifier}/resync-metadata` API endpoint. - -=== Spotter APIs - -==== New API endpoints - -The following new endpoints allow sending messages to an active conversation -session with a Spotter agent. - -* `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send` + -Allows sending a message to an active Spotter AI conversation and returns a synchronous response. -* `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream` + -Allows sending to an active Spotter AI conversation and returns the response as a real-time Server-Sent Events (SSE) stream. - -These new endpoints replace the legacy agent conversation and SSE streaming APIs. - -==== Deprecated endpoints [.version-badge.deprecated]#Deprecated# - -* `POST /api/rest/2.0/ai/agent/{conversation_identifier}/converse` + -Replaced by `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send`. - -* `POST /api/rest/2.0/ai/agent/converse/sse` + -Replaced by `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream` - -These endpoints are deprecated and will be removed in a future release. Embedding applications and integrations using these APIs are advised to migrate to the new API endpoints for improved experience. - -==== Enhancements to conversation creation API [.version-badge.breaking]#Breaking# - -The following enhancements have been introduced for the conversation creation operation workflow with the `POST /api/rest/2.0/ai/agent/conversation/create` API endpoint: - -metadata_context:: -To define the conversation context, the API request must include the `metadata_context` parameter with one of the following values: - -* `AUTO_MODE`: Automatically discovers and selects the most relevant datasets for the user's queries. -* `DATA_SOURCE`: Sets the target context as the data source. You must specify at least one data source ID. -** To set a single data source object metadata context, specify a `data_source_identifier`. -** For multi-data source context, specify the `data_source_identifiers`. -+ -[IMPORTANT] -==== -The `data_source` and `guid` attributes are deprecated in the 26.5.0.cl release version. Integrations using these parameters in ThoughtSpot versions 26.2.0.cl through 26.4.0.cl will continue to work until further notice. However, ThoughtSpot recommends using either `AUTO_MODE` or `DATA_SOURCE` with `data_source_identifier` or `data_source_identifiers` for the metadata context. -==== - -Other context options:: -The `answer_context` and `liveboard_context` are removed and no longer supported. Any existing integration or embedding application passing `answer_context` or `liveboard_context` in the request body must update their workflows to use the `AUTO_MODE` or `DATA_SOURCE` option. - -Enable save chat:: -The `enable_save_chat` parameter, when set to `true`, saves the conversation. - -API response:: -The API response now returns the `conversation_identifier`, which is used in all -subsequent send message or SSE streaming calls. - -=== Liveboard report API enhancements [beta betaBackground]^Beta^ -The `POST /api/rest/2.0/report/liveboard` API endpoint enhances the PDF downloads by introducing the following parameters: - -* `"page_size": "CONTINUOUS"` for a seamless PDF export that matches the full length of your Liveboard. Unlike the A4 format, which introduces forced page breaks between visualizations, this continuous flow maintains your exact design and intended layout. -* `zoom_level` offers various download size options to suit the viewer's screen dimensions, thereby enhancing legibility. This can be set only when `page_size` is specified as `CONTINUOUS`. +=== Spotter AI APIs -For more information, see xref:data-report-v2-api.adoc#_liveboard_report_api[Liveboard Report API documentation]. +Conversation API updates:: +The following Spotter Agent API endpoints are deprecated in 26.5.0.cl: -=== Metadata search API enhancements +* `POST /api/rest/2.0/ai/agent/{conversation_identifier}/converse` — use `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send` instead. +* `POST /api/rest/2.0/ai/agent/converse/sse` — use `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream` instead. -Personalized Views in metadata search:: -The `POST /api/rest/2.0/metadata/search` API endpoint introduces the `include_personalised_views` request parameter. +The new API endpoints introduce breaking changes in the request and response format. For more information, see xref:spotter-agent-apis.adoc[Spotter Agent APIs]. -When both `include_details: true` and `include_personalised_views: true` are specified in the request, the API returns a `personalised_views` array in the `metadata_detail` object for `LIVEBOARD` metadata type responses. +=== Connections API -This allows you to retrieve the full list of Personalized Views associated with a Liveboard in a single API call, without requiring a separate TML export. +New API endpoints:: +* `POST /api/rest/2.0/connection/configuration/create` — Creates a connection configuration for an Embrace connection. +* `PUT /api/rest/2.0/connection/configuration/{configuration_identifier}/update` — Updates an existing connection configuration. +* `POST /api/rest/2.0/connection/configuration/search` — Searches for connection configurations. +* `DELETE /api/rest/2.0/connection/configuration/{configuration_identifier}/delete` — Deletes a connection configuration. -For more information, see xref:rest-api-v2-metadata-search.adoc#_include_personalised_views[Search metadata API]. +=== Metadata API -=== TML API enhancements -The previous limit of 100 Personalized Views per Liveboard on TML import has been removed. You can now import all associated Personalized Views of a Liveboard without any views being dropped. For more information, see the xref:tml-api.adoc[TML API documentation]. +New `record_size` default:: +The default value for `record_size` in `POST /api/rest/2.0/metadata/search` has changed from 10 to 20. == Version 26.4.0.cl, April 2026 -=== Variable API endpoints -The following endpoints are introduced for bulk delete and update operations for variables: - -* `POST /api/rest/2.0/template/variables/{identifier}/update-values` + -Assigns multiple values to a variable and sets the scope for variable values in a single API request. -* `POST /api/rest/2.0/template/variables/delete` + -Deletes one or more variables in a single API request. - -These new API endpoints replace the following legacy API endpoints deprecated in 26.4.0.cl. - -* `POST /api/rest/2.0/template/variables/{identifier}/delete` -* `POST /api/rest/2.0/template/variables/update-values` - -Your existing implementation with the legacy API endpoints will continue to work until further notice. However, these endpoints will be removed from ThoughtSpot in a future release. Hence, we recommend updating your workflows to use the API endpoints at your earliest convenience. - -For more information, see xref:variables.adoc[Variable API documentation]. - -=== Metadata parameterization -You can now parameterize multiple fields in a metadata object in a single API request using the `/api/rest/2.0/metadata/parameterize-fields` API endpoint. -This endpoint replaces the legacy `/api/rest/2.0/metadata/parameterize` endpoint, which is deprecated in 26.4.0.cl. - -For more information, see xref:metadata-parameterization.adoc[Metadata parameterization API documentation]. - -=== Webhook integration -This release introduces the following features and enhancements to the webhook integration workflows: - -Custom HTTP headers in webhook requests:: -Administrators can configure custom HTTP headers to send in webhook requests triggered by ThoughtSpot, in addition to the standard HTTP and authentication headers. You can specify these headers in the `additional_headers` attribute during webhook creation (`/api/rest/2.0/webhooks/create`) and update (`/api/rest/2.0/webhooks/{webhook_identifier}/update`) via REST APIs. - -Webhook connection validation:: -You can now validate a webhook connection by sending a test payload via an API request to the `/api/rest/2.0/system/communication-channels/validate` endpoint. The API returns a response indicating the connection and authentication status for a given webhook connection. - -Webhook monitoring:: -To monitor the status of webhook jobs and scheduled events, ThoughtSpot introduces the `/api/rest/2.0/jobs/history/communication-channels/search` API endpoint. - -For more information, see xref:webhooks-comm-channel.adoc[Webhook configuration validation and monitoring]. - -=== Collections API endpoints - -The following APIs are introduced for Collections: - -* `POST /api/rest/2.0/collections/create` [beta betaBackground]^Beta^ + -Creates a new Collection. -* `POST /api/rest/2.0/collections/search` [beta betaBackground]^Beta^ + -Searches for a Collection in ThoughtSpot -* `POST /api/rest/2.0/collections/{collection_identifier}/update` [beta betaBackground]^Beta^ + -Updates an existing Collection -* `POST /api/rest/2.0/collections/delete` [beta betaBackground]^Beta^ + -Deletes a Collection - -For more information, see xref:collections.adoc[Collections]. - -=== Email customization API enhancements - -The `template_properties` parameter now has the `hide_logo_url` elements for email template customization. Set it to `true` to entirely hide the logo component in the ThoughtSpot notification emails. - -=== Spotter API enhancements -Spotter AI APIs now support the following error responses: - -* 401 Unauthorized: authentication token is missing, expired, or invalid. -* 403 Forbidden: the authenticated user does not have `CAN_USE_SPOTTER` privilege or view access to the underlying metadata sources. +=== Authentication -=== Pivot table .xlsx exports -The following API endpoints now support pivot tables in `.xlsx` downloads with full visual and structural parity: +Token expiry:: +The default token validity for `POST /api/rest/2.0/auth/token/full` and `POST /api/rest/2.0/auth/token/object` is now 5 minutes. ThoughtSpot recommends setting `token_expiry_duration` explicitly if your application requires a longer token lifetime. -* `POST /api/rest/2.0/report/answer` -* `POST /api/rest/2.0/schedules/create` +=== Orgs API -To enable pivot formatting on your ThoughtSpot instance, contact ThoughtSpot Support. +`POST /api/rest/2.0/orgs/search` enhancements:: +The API response now includes `user_count` — the number of users in each org — and `status` — active or inactive. == Version 26.3.0.cl, March 2026 -=== Webhook APIs - -The Webhook API allows configuring Amazon S3 buckets as a storage destination for webhook payload delivery. - -* `POST /api/rest/2.0/webhooks/create` + -Configures storage destination for webhook delivery. -* `POST /api/rest/2.0/webhooks/{webhook_identifier}/update` + -Allows modifying storage configuration for a webhook. -* `POST /api/rest/2.0/webhooks/search` + -Retrieves storage configuration details. - -=== Object privilege APIs -Administrators and users with edit access to data models can now use `/api/rest/2.0/security/metadata/manage-object-privilege` to assign object-level permissions to users and groups and control access to Spotter data model instructions. - -To fetch object privileges for a data model, user, or group, use the `/api/rest/2.0/security/metadata/fetch-object-privileges` API endpoint. - -For more information, see xref:spotter-nl-instructions.adoc#_spotter_data_model_instructions_access[Spotter data model instructions access]. - - -=== User API enhancements - -The user APIs now support setting browser language as the default locale for ThoughtSpot users. Administrators can set the `use_browser_language` parameter as the default locale for ThoughtSpot users during the following API operations: - -* When creating a new user via `POST /api/rest/2.0/users/create` + -* When importing users via `POST /api/rest/2.0/users/import` + -* When updating user preferences via `POST /api/rest/2.0/users/{user_identifier}/update` + - -When set to `true`, a user's current locale preference is overridden and the browser's language takes precedence. - -The status of the browser language setting for a given user can also be retrieved using the following API endpoints: +=== Liveboard schedules API -* `POST /api/rest/2.0/users/search` + -* `POST /api/rest/2.0/users/activate` + -* `GET /api/rest/2.0/auth/session/user` + +New API endpoints:: +* `POST /api/rest/2.0/schedules/create` — Creates a new Liveboard schedule. +* `POST /api/rest/2.0/schedules/search` — Returns a list of Liveboard schedules. +* `PUT /api/rest/2.0/schedules/{schedule_identifier}/update` — Updates an existing Liveboard schedule. +* `DELETE /api/rest/2.0/schedules/{schedule_identifier}/delete` — Deletes a Liveboard schedule. -=== Custom token generation API -Note the following changes to request parameters for the `/api/rest/2.0/auth/token/custom` API endpoint: +For more information, see xref:liveboard-schedule-api.adoc[Liveboard schedule API]. -* The `filter_rules` parameter on the custom token authentication (`/api/rest/2.0/auth/token/custom`) page in the REST API Playground is no longer available for new configurations. Existing implementations that use `filter_rules` continue to work. However, we strongly recommend migrating to `variable_values` and ABAC via RLS for data security. +=== Webhooks API -* The `parameter_values` property is supported in the current release but will be deprecated in an upcoming version. Using `parameter_values` for row-level security will be phased out with this deprecation. Therefore, we recommend generating JWTs that pass data security attributes through formula variable attributes instead of `filter_rules` or `parameter_values` for ABAC. +New API endpoints:: +* `POST /api/rest/2.0/webhooks/create` — Creates a new webhook. +* `POST /api/rest/2.0/webhooks/search` — Searches for webhooks. +* `PUT /api/rest/2.0/webhooks/{webhook_identifier}/update` — Updates a webhook. +* `DELETE /api/rest/2.0/webhooks/{webhook_identifier}/delete` — Deletes a webhook. -For more information, see xref:abac-migration-guide.adoc[ABAC JWT migration guide] and xref:abac_rls-variables.adoc[ABAC via RLS]. +For more information, see xref:webhooks-api.adoc[Webhooks API]. == Version 26.2.0.cl, February 2026 -=== Security settings APIs -This release introduces the following Security settings APIs: - -* `POST /api/rest/2.0/system/security-settings/configure` + -Allows configuring security settings at the Org level or for all Orgs on a ThoughtSpot instance. -* `POST /api/rest/2.0/system/security-settings/search` + -Gets a list of security settings configured on a specific Org or for all Orgs on a ThoughtSpot instance. - -For more information, see xref:security-settings.adoc[Security Settings]. - -=== Connection API -ThoughtSpot administrators can now revoke OAuth refresh tokens for users who no longer require access to a data warehouse connection via the `/api/rest/2.0/connections/{connection_identifier}/revoke-refresh-tokens` API endpoint. When a token is revoked, the affected user's session for that connection is terminated, and they must re-authenticate to regain access. - -=== Connection configuration API enhancements -You can now include `same_as_parent` and `policy_process_options` attributes in your API request to `/api/rest/2.0/connection-configurations/create` and `/api/rest/2.0/connection-configurations/{configuration_identifier}/update` endpoints. - -The `same_as_parent` parameter specifies if the configuration should inherit settings from its parent. The `policy_process_options` attribute can be used to define additional policy or processing options for the connection, to allow granular control over connection behavior. - -=== Liveboard Report API enhancements -You can now download Liveboard reports in the CSV and XLSX formats through the `POST /api/rest/2.0/report/liveboard` API endpoint. Both these options are Early Access features. - -For more information, see xref:data-report-v2-api.adoc[Data and Report APIs]. +=== Spotter AI APIs -=== Email customization API enhancements +Spotter 3 capabilities:: +The Spotter Agent API endpoints introduced for Spotter 2 now support Spotter 3 capabilities as of version 26.2.0.cl. The following conversation settings are enabled by default: -The `template_properties` parameter now has two additional elements for email template customization: +* `enable_contextual_change_analysis` — Spotter analyzes how context changes between queries. +* `enable_natural_language_answer_generation` — Allows sending natural language queries. +* `enable_reasoning` — Allows Spotter to use reasoning for deep analysis. -* `contact_support_url` to add a customized link for contacting customer support. -* `hide_contact_support_url` to hide the option of adding a link for customer support. +== Version 26.1.0.cl, January 2026 -=== System configuration API enhancements -The API response from the `/api/rest/2.0/system/config` endpoint indicates whether SAML or Okta authentication is enabled on the system. +=== REST API Python SDK -=== User API enhancements +ThoughtSpot provides the REST API Python SDK (`thoughtspot-rest-api-sdk`) to help Python developers interact programmatically with ThoughtSpot REST API v2 endpoints. The SDK is available on link:https://pypi.org/project/thoughtspot-rest-api-sdk[PyPI, window=_blank]. -* `POST /api/rest/2.0/users/import` + -The `preferred_locale` parameter allows configuring the preferred locale for users being imported via API request. -* `POST /api/rest/2.0/users/search` + -The `include_variable_values` parameter in the API request allows including variable values in the search response. The variable values can be assigned for a user via xref:abac_rls-variables.adoc[ABAC tokens] or xref:variables.adoc#_define_values_and_scope_for_variables[variable API documentation]. +For information about how to install and use the SDK, see xref:rest-api-sdk-python.adoc[Python SDK for REST APIs]. == Version 10.15.0.cl, December 2025 -=== Spotter APIs - -This release introduces the following Spotter APIs: - -* `POST /api/rest/2.0/ai/instructions/set` + -Allows configuring natural language (NL) instructions on a data model to define how Spotter interprets queries, handles data nuances, and improves responses. -* `POST /api/rest/2.0/ai/instructions/get` + -Gets NL instructions that are currently assigned to a model. -* `POST /api/rest/2.0/ai/data-source-suggestions` + -Retrieves a list of recommended data sources based on the specified query string. - -For more information, see xref:spotter-apis.adoc[Spotter AI APIs]. - -=== Variable APIs +=== Spotter AI APIs -You can now create formula variables using the `/api/rest/2.0/template/variables/create` API endpoint, and assign values and scope to these variables using the `/api/rest/2.0/template/variables/update-values` API endpoint. +Spotter memory APIs [earlyAccess eaBackground]#Early Access#:: +ThoughtSpot introduces two new REST API v2.0 endpoints for managing Spotter memory: -For more information, see xref:variables.adoc[Configure variables]. +* `POST /api/rest/2.0/ai/memory/import` — Imports Spotter memory entries. +* `POST /api/rest/2.0/ai/memory/export` — Exports Spotter memory entries. -=== ABAC tokens with formula variable attributes -The `/api/rest/2.0/auth/token/custom` API endpoint allows creating a token request with formula variables for ABAC via RLS implementation. +=== Metadata API -For more information, see xref:abac-user-parameters.adoc[ABAC via tokens]. +`POST /api/rest/2.0/metadata/search` enhancements:: +The `metadata/search` API response now includes `tags`, `author_name`, and `modified_by` fields for all metadata object types. == Version 10.14.0.cl, November 2025 -=== New API endpoints - - - -System:: -This release introduces the following endpoints for configuring communication channel preferences. - -* `POST /api/rest/2.0/system/preferences/communication-channels/configure` [beta betaBackground]^Beta^ + -Sets a communication channel preference for all Orgs at the cluster level or at the individual Org level. -* `POST /api/rest/2.0/system/preferences/communication-channels/search` [beta betaBackground]^Beta^ + -Gets details of the communication channel preferences configured on ThoughtSpot. -+ -For more information, see xref:webhooks-comm-channel.adoc[Configure and monitor communication channels]. - -Webhook:: -The following APIs are introduced for webhook CRUD operations: -* `POST /api/rest/2.0/webhooks/create` -Creates a webhook. -* `POST /api/rest/2.0/webhooks/{webhook_identifier}/update` -Updates the properties of a webhook. -* `POST /api/rest/2.0/webhooks/search` -Gets a list of webhooks configured in ThoughtSpot or in a specific Org. -* `POST /api/rest/2.0/webhooks/delete` -Deletes the webhook. -+ -For more information, see xref:webhooks-lb-schedule.adoc[Webhooks for Liveboard schedule events]. - -Column security rules:: - -* `POST /api/rest/2.0/security/column/rules/update` + -Updates column security rules for a given Table. - -* `POST /api/rest/2.0/security/column/rules/fetch` + -Gets details of column security rules for the tables specified in the API request. - -//// - -Spotter:: -POST /api/rest/2.0/ai/agent/{conversation_identifier}/converse -//// -=== Variable API enhancements - -The variable API enhancements are listed in the following sections. For additional details, see xref:variables.adoc[Define variables]. - -==== Variable creation API - -* The variable creation endpoint `/api/rest/2.0/template/variables/create` does not support assigning values to a variable. To assign values to a variable, use the `/api/rest/2.0/template/variables/update-values` endpoint. -* The `sensitive` parameter is renamed as `is_sensitive`. - -==== Variables update APIs [tag redBackground]#BREAKING CHANGE# - -The `/api/rest/2.0/template/variables/update` endpoint is deprecated and replaced with `/api/rest/2.0/template/variables/update-values`. + -To update the properties of a specific variable, use the `/api/rest/2.0/template/variables/{identifier}/update` endpoint and to assign values to one or several variables in a single API call, use the `POST /api/rest/2.0/template/variables/update-values` endpoint. - -==== Variables search API - -* The variables search API endpoint `/api/rest/2.0/template/variables/search` now includes the `value_scope` parameter that allows you to filter the API response by the objects to which the variable is mapped. -* Filtering API response by `EDITABLE_METADATA_AND_VALUES` is no longer supported. - - -=== User API enhancements -The following APIs now support the `variable_values` parameter. The `variable_values` property can be used for user-specific customization. - -* `POST /api/rest/2.0/users/create` -* `POST /api/rest/2.0/users/search` -* `POST /api/rest/2.0/users/activate` +=== Authentication -=== DBT API enhancements -The `/api/rest/2.0/dbt/generate-tml` endpoint supports the `model_tables` attribute to list models and their tables. +Token API enhancements:: +The `POST /api/rest/2.0/auth/token/full` and `POST /api/rest/2.0/auth/token/object` endpoints now support the `org_identifier` parameter, allowing token generation scoped to a specific org. -//// - -=== Authentication API -Support for `variable_values` property in `/api/rest/2.0/auth/session/user` API calls. +=== Roles API -//// +New privilege types:: +The `POST /api/rest/2.0/roles/create` and `POST /api/rest/2.0/roles/update` endpoints now support `SHAREWITHALL` (*Can share with all users*) and `EXPERIMENTALFEATUREPRIVILEGE` (*Has access to experimental features*) privilege types. == Version 10.13.0.cl, October 2025 -=== New API endpoints - -Spotter:: - -* `POST /api/rest/2.0/ai/agent/conversation/create` + -Creates a new AI-driven conversation session based on a specified data source. The resulting session sets the context for subsequent queries and responses. + - +=== Spotter Agent APIs -* `POST /api/rest/2.0/ai/relevant-questions/` + -Breaks down a user-submitted query into a series of analytical sub-questions using relevant contextual metadata. +Conversation create API:: +ThoughtSpot introduces the `POST /api/rest/2.0/ai/agent/conversation/create` API endpoint to create a conversation session with Spotter Agent. -* `POST /api/rest/2.0/ai/agent/converse/sse` + -Allows sending a follow-up message or question to an ongoing conversation session and returns the AI agent's response, including answers, tokens, and visualization details. + +Data source suggestions API [beta betaBackground]^Beta^:: +ThoughtSpot introduces the `POST /api/rest/2.0/ai/data-source-suggestions` API endpoint to return a list of relevant data sources based on a query. -For more information, see xref:spotter-apis.adoc[Spotter AI APIs]. - -Email customization:: -`POST /api/rest/2.0/customization/email/update` + -Updates an existing email customization. For more information, see xref:customize-email-apis.adoc[Customize email template]. - -=== API enhancements -The following APIs were modified to include new parameters: - -TML export:: -The TML export API now supports the `export_with_column_aliases` parameter in `export_options` to indicate whether to export column aliases of the model. - -Email customization:: -The `/api/rest/2.0/customization/email/update` and `/api/rest/2.0/customization/email` APIs now include `company_privacy_policy_url` and `company_website_url` properties in template variables, and a new `org_identifier` parameter in the API request. - -For more information, see xref:customize-email-apis.adoc[Customize email template]. - -=== Deprecated endpoints - -Spotter:: -The `POST /api/rest/2.0/ai/analytical-questions` Spotter AI API [beta betaBackground]^Beta^ is deprecated and replaced with the new API endpoint, `POST /api/rest/2.0/ai/relevant-questions/`. - -Email customization:: -The `POST /api/rest/2.0/customization/email/{template_identifier}/delete` email customization API is deprecated and replaced with the new API endpoint, `POST /api/rest/2.0/customization/email/delete`. - - -//// -=== Deprecated endpoints -The following Spotter AI APIs [beta betaBackground]^Beta^ are deprecated and replaced with the new xref:spotter-apis.adoc[AI APIs]. - -* `POST /api/rest/2.0/ai/conversation/create` -* `POST /api/rest/2.0/ai/analytical-questions` -* `POST /api/rest/2.0/ai/conversation/{conversation_identifier}/converse` -//// +Relevant questions API [beta betaBackground]^Beta^:: +ThoughtSpot introduces the `POST /api/rest/2.0/ai/relevant-questions/` API endpoint to decompose a user query into relevant sub-questions. == Version 10.12.0.cl, September 2025 -=== New API endpoints - -The following API endpoints are now available: - -Custom calendar:: -* `POST /api/rest/2.0/calendars/create` + -Creates a custom calendar. -* `POST /api/rest/2.0/calendars/generate-csv` + -Exports a custom calendar in the CSV format. -* `POST /api/rest/2.0/calendars/search` + -Gets custom calendars for the connection ID specified in the API request. -* `POST /api/rest/2.0/calendars/{calendar_identifier}/delete` + -Deletes a custom calendar. -* `POST /api/rest/2.0/calendars/{calendar_identifier}/update` + -Updates a custom calendar. +=== Connections API -Connection configuration:: -* `POST /api/rest/2.0/connection-configurations/create` + -Creates an additional configuration to an existing connection to a data warehouse. -* `POST /api/rest/2.0/connection-configurations/search` + -Gets the required connection configuration objects. -* `POST /api/rest/2.0/connection-configurations/{configuration_identifier}/update` + -Updates an existing connection configuration object. -* `POST /api/rest/2.0/connection-configurations/delete` + -Deletes the connection configuration object. - -=== Enhancements to APIs - -Export API endpoint:: - -* Answer TML: + -The `POST /api/rest/2.0/metadata/tml/export` API endpoint now allows fetching TML for Answer objects that do not have an ID or name assigned. The `session_identifier` and `generation_number` parameters allow you to define the session ID and the Answer generation number in the API request. These optional attributes can be used for unsaved Answers generated from Spotter queries. - -* Table TML: + -The `POST /api/rest/2.0/metadata/tml/export` API request allows exporting column security rules for Table TML objects. This attribute will export column security rules only if the object specified in the API request has column security applied and when `export_associated` is set to `true`. - -== Version 10.11.0.cl, July 2025 - -=== Search metadata API enhancements -The search metadata (`/api/rest/2.0/metadata/search`) API includes the following enhancements: - -* The `liveboard_reponse_version` parameter. It allows you to specify the xref:rest-api-v2-metadata-search.adoc#_response_format_for_liveboards[response format for Liveboard objects]. -* The `subtypes` attribute to specify the sub-type for the `LOGICAL_TABLE` metadata type. The `LOGICAL_TABLE` type allows you to fetch objects such as Tables, Models, and Views. The `subtypes` parameter allows you to filter API response by specifying subcategories of the object type. -* The `include_only_published_objects` attribute to specify whether the search should include xref:publish-api.adoc[published objects]. - - -=== System API -The API response generated from the `GET /api/rest/2.0/system/config-overrides` requests now returns the overrides in the `config_override_info` object. +`POST /api/rest/2.0/connections/search` enhancements:: +The API response now includes `connection_type`, `data_warehouse_type`, and `scheduled_sync_config` fields. === TML API -The API response for the `POST /api/rest/2.0/metadata/tml/async/import` and `POST /api/rest/2.0/metadata/tml/async/status` now includes the `author_display_name` property. This property shows the display name of user that initiated the asynchronous TML import request. - -=== REST API Java SDK - -The REST API Java SDK library artifacts are now available in the `com.thoughtspot` Maven namespace. If you are using Maven Central to import the REST API SDK artifacts, update the group ID in your `pom.xml` file to `com.thoughtspot` and the artifact ID to `rest-api-sdk`. - -For more information, see xref:rest-api-java-sdk.adoc#_import_the_sdk_to_your_application_environment[REST API Java SDK]. -== Version 10.10.0.cl, July 2025 - -=== Email template customization APIs -This release introduces the following new endpoints for email template customization: +Bulk import:: +The `POST /api/rest/2.0/metadata/tml/import` endpoint now supports importing up to 50 TML objects in a single request. -* `POST /api/rest/2.0/customization/email` + -Allows you to personalize the ThoughtSpot notification emails content. -* `POST /api/rest/2.0/customization/email/{template_identifier}/delete` + -Removes the customizations done for the ThoughtSpot notification emails. -* `POST /api/rest/2.0/customization/email/search` + -Allows searching the email customization configuration if configured for ThoughtSpot. -* `POST /api/rest/2.0/customization/email/validate` + -Validates the email customization configuration if configured for ThoughtSpot. +== Version 10.11.0.cl, August 2025 -=== Group API +=== Orgs API -The `/api/rest/2.0/groups/search` endpoint now supports the following new options in group search API requests: +Multi-org user management:: +`POST /api/rest/2.0/orgs/{org_identifier}/users/add` and `POST /api/rest/2.0/orgs/{org_identifier}/users/remove` endpoints are introduced to add and remove users from orgs programmatically. -* `include_users` + -When set to `true`, it includes user details in the group search API response. -* `include_sub_groups` + -When set to `true`, it includes sub-groups in the group search response. +== Version 10.10.0.cl, July 2025 -=== Schedule API -You can now specify the `personalised_view_id` of a Liveboard in API requests to the following schedule APIs: +=== Authentication -* `POST /api/rest/2.0/schedules/create` -To schedule a job for a personalized view of the Liveboard, specify the `personalised_view_id`. -* `POST /api/rest/2.0/schedules/{schedule_identifier}/update` -To update schedule details for a specific view of the Liveboard, specify the `personalised_view_id`. +Token revocation:: +`POST /api/rest/2.0/auth/token/revoke` endpoint is introduced to revoke an active bearer token before its expiry. == Version 10.9.0.cl, June 2025 -=== Metadata parameterization and content publishing across Orgs - -This release introduces the following new endpoints for metadata parameterization [beta betaBackground]^Beta^ and content publishing [beta betaBackground]^Beta^ across Orgs. To enable the content publishing feature and the related API operations on your instance, contact ThoughtSpot Support. - -* `POST /api/rest/2.0/metadata/parameterize` [beta betaBackground]^Beta^ + -Allows you to parameterize fields in metadata objects. -* `POST /api/rest/2.0/metadata/unparameterize` [beta betaBackground]^Beta^ + -Allows removing parameterization from fields in metadata objects -* `POST /api/rest/2.0/security/metadata/publish` [beta betaBackground]^Beta^ + -Publish metadata objects to one or several Orgs on an instance. -* `POST /api/rest/2.0/security/metadata/unpublish` [beta betaBackground]^Beta^ + -Removes published metadata objects from the Orgs specified in the API request. -* `POST /api/rest/2.0/template/variables/create` [beta betaBackground]^Beta^ + -Allows creating a template variable which can be used to parameterize fields in a metadata object. -* `POST /api/rest/2.0/template/variables/search` [beta betaBackground]^Beta^ + -Allows searching template variables -* `POST /api/rest/2.0/template/variables/{identifier}/update` [beta betaBackground]^Beta^ + -Allows updating properties of a template variable. -* `POST /api/rest/2.0/template/variables/update` [beta betaBackground]^Beta^ + -Allows you to add, remove, or replace properties of one or several template variables. -* `POST /api/rest/2.0/template/variables/{identifier}/delete` [beta betaBackground]^Beta^ + -Deletes a template variable. - -If your metadata objects are parameterized, you can use the `show_resolved_parameters` to filter the API response from `/api/rest/2.0/connection/search` and `/api/rest/2.0/metadata/search` endpoints to get only the objects with resolved parameterized values. - -=== Liveboard Report API -The Liveboard Report API now allows you to define the following properties: - -* `tab_identifiers` + -Optional parameter to specify the name or GUID of a Liveboard tab to export only the visualizations in that tab. -* `personalised_view_identifier` + -Optional parameter to specify the GUID of the Liveboard personalized view that you want to download. - -In addition to these parameters, you can also define the following properties for PNG downloads: - -* `image_resolution` -* `image_scale` -* `include_header` - -For more information, see xref:data-report-v2-api.adoc#_liveboard_report_api[Liveboard Report API]. - -=== REST API Java SDK - -The REST API Java SDK enables developers to interact programmatically with ThoughtSpot REST APIs from Java applications. It provides a client library with Java methods and classes that map to API endpoints, handle authentication, send API requests, and allow creating and modifying ThoughtSpot resources and objects. - -For information about how to install and use the SDK, see xref:rest-api-java-sdk.adoc[Java SDK for REST APIs]. - - -== Version 10.8.0.cl, April 2025 - -=== New API endpoints - -This version introduces the following endpoints: - -* `POST /api/rest/2.0/metadata/update-obj-id` + -Update object IDs for given metadata objects. + - -[NOTE] -==== -An object ID is a user-defined ID assigned to a ThoughtSpot object in addition to the system-generated GUID. -Note that the object ID generation for metadata objects is disabled by default. If this feature is enabled on your instance, you can use the `POST /api/rest/2.0/metadata/update-obj-id` to assign or update the object ID. -==== - -=== Metadata API - -* The `POST /api/rest/2.0/metadata/search` endpoint now supports the following parameters: +=== System API -** `include_discoverable_objects` + -Allows including Answers and Liveboards that are marked as discoverable by the object owner. -** `metadata_obj_id` + -Filters metadata objects by the user-defined object ID. This parameter returns data only if the user-defined object ID feature is enabled on your instance. +`GET /api/rest/2.0/system` enhancements:: +The API response now includes `orgs_enabled` (boolean) indicating whether multi-org is enabled on the instance. -=== TML APIs +== Version 10.8.0.cl, May 2025 -* The `all_orgs_context` parameter in TML import APIs (`/api/rest/2.0/metadata/tml/import` and `/api/rest/2.0/metadata/tml/async/import`) is deprecated and removed from the Playground. Use `all_orgs_override` to define the Org context in your API requests. +=== RBAC -* The TML export API now allows exporting TML content with user feedback received for objects such as AI-generated Answers. The `export_with_associated_feedbacks` attribute is set to `false` by default. +Role-based access control APIs:: +ThoughtSpot introduces the following REST API v2.0 endpoints to manage roles and privileges for RBAC: -=== Report APIs -The Liveboard export API (`/api/rest/2.0/report/liveboard`) now allows overriding filters applied to a Liveboard. The `override_filters` array allows specifying several types of filters and updates the Liveboard data during export. +* `POST /api/rest/2.0/roles/create` — Creates a new role. +* `POST /api/rest/2.0/roles/search` — Returns a list of roles. +* `PUT /api/rest/2.0/roles/{role_identifier}/update` — Updates an existing role. +* `DELETE /api/rest/2.0/roles/{role_identifier}/delete` — Deletes a role. -For more information, see xref:data-report-v2-api.adoc#_override_filters[Override filters]. +For more information, see xref:roles-api.adoc[Roles API]. == Version 10.6.0.cl, March 2025 -=== New metadata API endpoints - -* `POST /api/rest/2.0/metadata/headers/update` + -Updates metadata header for a given list of objects. -* `POST /api/rest/2.0/metadata/worksheets/convert` + -Converts a Worksheet object to a Model. - -=== Report APIs -[tag redBackground]#BREAKING CHANGE# - -Downloading Liveboard reports in the CSV and XLSX file format via `POST /api/rest/2.0/report/liveboard` API endpoint is not supported. The CSV and XLSX `file_format` options have been removed because they were not functioning in the expected manner. - -==== Parameters for regional settings - -The `/api/rest/2.0/report/answer` and `/api/rest/2.0/report/liveboard` now allow users to define the following `regional_settings` attributes: - -* `currency_format` -* `user_locale` -* `number_format_locale` -* `date_format_locale` - -=== Custom object ID in TML and Metadata APIs - -The following API endpoints allow you to specify a custom object ID (`obj_identifier`) in the metadata object properties: - -* `POST /api/rest/2.0/metadata/search` -* `POST /api/rest/2.0/metadata/headers/update` -* `POST /api/rest/2.0/metadata/tml/export` + - -=== TML import API - -The `/api/rest/2.0/metadata/tml/async/import` and `POST /api/rest/2.0/metadata/tml/import` endpoints allow skipping diff check when processing TMLs for imports. The `skip_diff_check` attribute is disabled by default and can be enabled to avoid importing objects that do not have any changes. - -=== API response changes - -The 200 and 201 response body from `POST /api/rest/2.0/ai/answer/create` and `POST /api/rest/2.0/ai/conversation/{conversation_identifier}/converse` API calls now includes the `display_tokens` property. - - -== Version 10.5.0.cl, December 2024 - -=== Custom access token API -The `/api/rest/2.0/auth/token/custom` API endpoint allows setting the following attributes in API requests: - -* `auto_create` + -Creates a user if username specified in the API request is not available in ThoughtSpot. By default, the `auto_create` is set to `true`. -* `REPLACE` enum for `persist_option` + -Allows replacing persisted values with new attributes defined in the token generation API request. For more information, see xref:abac-user-parameters.adoc[ABAC via tokens]. - -=== TML import APIs - -TML async import:: - -The `/api/rest/2.0/metadata/tml/async/import` supports setting the following properties via API requests: -+ -* `import_policy` + -Allows you to specify if all objects should be imported during the TML import operation. Valid values are: - -** `PARTIAL_OBJECT` (default) -** `PARTIAL` -** `VALIDATE_ONLY` -** `ALL_OR_NONE` - -* `enable_large_metadata_validation` + -Indicates if the TMLs with large and complex metadata should be validated before the import. -+ -For more information about these attributes, see xref:tml.adoc#_import_tml_objects_asynchronously[Import TML objects asynchronously]. - -TML import API:: - -The `/api/rest/2.0/metadata/tml/import` API also supports setting the `enable_large_metadata_validation` attribute for large and complex metadata objects during TML import. - -TML export API:: - -The `/api/rest/2.0/metadata/tml/export` endpoint now allows you to include additional attributes when exporting TML for an object from ThoughtSpot. The `export_options` allows you to include the following optional attributes: - -* `include_obj_id_ref` + -Specifies whether to export `user_defined_id` of the referenced object. This setting is valid only if the `UserDefinedId` property in TML is enabled. -* `include_guid` + -Specifies whether to export the GUID of the object. This setting is valid only if the `UserDefinedId` property in TML is enabled. -* `include_obj_id` + -Specifies whether to export the `user_defined_id` of the object. This setting is valid only if the `UserDefinedId` property in TML is enabled. - - -Share metadata:: - -The `email` attribute is now optional in the `POST` request body sent to the `/api/rest/2.0/security/metadata/share` API endpoint. - -Role API:: - -The `/api/rest/2.0/roles/create` API endpoint now allows setting `read_only` attribute to specify if the role is read only. A read-only role cannot be updated or deleted. - -== Version 10.4.0.cl, November 2024 - -=== New API endpoints - -Spotter AI APIs [beta betaBackground]^Beta^ :: - -* `POST /api/rest/2.0/ai/conversation/create` + -Creates a conversation session. -* `POST /api/rest/2.0/ai/conversation/{conversation_identifier}/converse` + -Generates responses for user queries and follow-up questions. -* `POST /api/rest/2.0/ai/answer/create` + -Generates an Answer from a Natural Language Search query. - -Authentication:: -The `/api/rest/2.0/auth/token/custom` API endpoint is now available to generate an authentication token with custom rules and filter conditions for a user. - -+ -ThoughtSpot recommends using the custom token API endpoint to generate tokens for the Attribute-Based Access Control (ABAC) implementation. For more information, see xref:abac_rls-variables.adoc[ABAC via RLS with variables]. - -Connections:: -The following new API endpoints are available for updating and deleting a connection object: - -* `POST /api/rest/2.0/connections/{connection_identifier}/update` -* `POST /api/rest/2.0/connections/{connection_identifier}/delete` - -+ -ThoughtSpot recommends using these APIs instead of `POST /api/rest/2.0/connection/update` and `POST /api/rest/2.0/connection/delete`. - -TML:: -The following API endpoints are available for asynchronous TML import: - -* `POST /api/rest/2.0/metadata/tml/async/import` + -Validates and imports TML objects asynchronously. Use this API endpoint when importing large metadata objects. -* `POST /api/rest/2.0/metadata/tml/async/status` + -Fetches task status for the async TML import operations. - -For more information, see xref:tml.adoc#_import_tml_objects_asynchronously[Import TML objects asynchronously]. - -=== API enhancements - -User session:: - -* The 200 API response for the `/api/rest/2.0/auth/session/user` and `/api/rest/2.0/users/search` is modified to show `access_control_properties`. - -* You can now manage account activation status for IAMv2 users using the following API endpoints: - -** `POST /api/rest/2.0/users/create` + -** `POST /api/rest/2.0/users/{user_identifier}/update` - -Report API:: - -The `POST /api/rest/2.0/report/answer` API endpoint supports downloading an Answer generated by the Spotter AI APIs: - -* `session_identifier` + -Session ID returned in API response by the `/api/rest/2.0/ai/answer/create` or `/api/rest/2.0/ai/conversation/create` endpoint. -* `generation_number` + -Number assigned to the Answer session with Spotter. -+ -If you are downloading an Answer generated by Spotter, you must specify the session ID. The `metadata_identifier` property is not required. - -=== Deprecated features - -Connection APIs:: - -The following connection API endpoints are deprecated: - -* `POST /api/rest/2.0/connection/delete` -* `POST /api/rest/2.0/connection/update` - -+ -Use `POST /api/rest/2.0/connections/{connection_identifier}/update` and `POST /api/rest/2.0/connections/{connection_identifier}/delete` APIs to update and delete a connection object respectively. - -Authentication:: - -The `user_parameters` property in `/api/rest/2.0/auth/token/full` and `/api/rest/2.0/auth/token/object` APIs is deprecated. -+ -ThoughtSpot recommends using `/api/rest/2.0/auth/token/custom` API endpoint with `filter_rules` and `parameter_values` to configure user properties for ABAC via tokens. - -== Version 10.3.0.cl, October 2024 - -=== New API endpoint - -You can now create a copy of a Liveboard or Answer object using `/api/rest/2.0/metadata/copyobject` API endpoint. - -== Version 10.1.0.cl, August 2024 - -=== New API endpoints - -* `POST /api/rest/2.0/metadata/tml/export/batch` + -Exports a batch of TML for user, user group, or Role objects. - -=== Security APIs -The `/api/rest/2.0/security/metadata/fetch-permissions` API endpoint supports the following parameters: - -* `record_offset` + -Specifies the starting record number from which the records for each metadata type will be included in the API response. -* `record_size` + -Specifies the number of records that should be included for each metadata type in the API response. -* `permission_type` + -Specifies the type of permission. Valid values are: -** `EFFECTIVE` - If user permission to the metadata objects is granted by the privileges assigned to the groups to which they belong. -** `DEFINED` - If a user or user group received access to metadata objects via object sharing by another user. - -== Version 10.0.0.cl, July 2024 - -=== Roles - -You can now assign the `CAN_MANAGE_VERSION_CONTROL` role using any of the following API endpoints: - -* `POST /api/rest/2.0/roles/create` -* `POST /api/rest/2.0/roles/{role_identifier}/update` - -The `CAN_MANAGE_VERSION_CONTROL` Role privilege is required for Git integration with ThoughtSpot. - -== Version 9.12.0.cl, May 2024 - -==== New features - -Authentication API:: - -* `/api/rest/2.0/auth/token/validate` + -Validates the authentication token of the logged-in user. - -TML API:: -The export TML API requests now support the following parameters: -+ -* `export_schema_version` + -Specifies the schema version for datasets during TML export. By default, the API request uses v1 schema for Worksheet TML export. For Models, set `export_schema_version` to `v2`. + -* `export_dependent` + -Allows exporting dependent Tables while exporting a Connection. -* `export_connection_as_dependent` + -Specifies if a Connection can be exported as a dependent object when exporting a Table, Worksheet, Answer, or Liveboard. This parameter works only when `export_associated` is set to `true` in the API request. - -==== Deprecated features - -Token authentication APIs:: - -The `jwt_user_options` object property in `/api/rest/2.0/auth/token/full` and `/api/rest/2.0/auth/token/object` is deprecated. Use the `user_parameters` property to define security entitlements to a user session. For more information, see xref:abac-user-parameters.adoc[ABAC via token][beta betaBackground]^Beta^. - -== Version 9.10.5.cl, April 2024 - -=== New features - -Authentication:: - -The `/api/rest/2.0/auth/token/full` and `/api/rest/2.0/auth/token/object` API endpoints support generating JWT token for Attribute-Based Access Control. The `user_parameters` object allows you to define security entitlements for a given user. - -For more information, see xref:abac-user-parameters.adoc[ABAC via tokens]. +=== Custom actions API -Roles:: +New API endpoints:: +* `POST /api/rest/2.0/customization/custom-actions/create` — Creates a custom action. +* `POST /api/rest/2.0/customization/custom-actions/search` — Searches for custom actions. +* `PUT /api/rest/2.0/customization/custom-actions/{custom_action_identifier}/update` — Updates a custom action. +* `DELETE /api/rest/2.0/customization/custom-actions/{custom_action_identifier}/delete` — Deletes a custom action. -The `/api/rest/2.0/roles/create` and `/api/rest/2.0/roles/{role_identifier}/update` API endpoints support assigning the following privileges to a Role for granular data access control and management: +For more information, see xref:custom-actions-rest-api.adoc[Custom actions API]. -* `CAN_MANAGE_CUSTOM_CALENDAR` -* `CAN_CREATE_OR_EDIT_CONNECTIONS` -* `CAN_MANAGE_WORKSHEET_VIEWS_TABLES` +== Version 10.5.0.cl, February 2025 -DBT:: - -You can now use `file_content` to upload DBT Manifest and Catalog artifact files as a ZIP file in your API requests to the `/api/rest/2.0/dbt/dbt-connection`, `/api/rest/2.0/dbt/generate-tml`, `/api/rest/2.0/dbt/generate-sync-tml`, and `/api/rest/2.0/dbt/update-dbt-connection` endpoints. This field is required if the `import_type` parameter is set to `'ZIP_FILE'`. - -Connections:: - -* `/api/rest/2.0/connections/fetch-connection-diff-status/{connection_identifier}` + -Validates the differences in Connection metadata between Cloud Data Warehouse and ThoughtSpot. -* `/api/rest/2.0/connections/download-connection-metadata-changes/{connection_identifier}` + -Downloads the connection metadata differences identified between Cloud Data Warehouse and ThoughtSpot. - -Logs:: -The `/api/rest/2.0/logs/fetch` API endpoint allows fetching all logs in a single API request. To get all logs, set `get_all_logs` to `true`. - -Share metadata:: - -The `/api/rest/2.0/security/metadata/share` API supports the following new properties: - -* `notify_on_share` + -Sends a share notification to the email addresses specified in the API request. -* `has_lenient_discoverability` + -Sets the shared metadata object as a discoverable object. Applies to Saved Answers and Liveboards only. - -Users:: -The `trigger_activation_email` property allows you to specify if an activation email must be sent to the user's email address in the user creation request to the `/api/rest/2.0/users/create` endpoint. - -=== Deprecated features - -Version Control APIs:: - -The following parameters in `/api/rest/2.0/vcs/git/config/create` and `/api/rest/2.0/vcs/git/config/update` are deprecated from 9.10.5.cl onward: - -* `default_branch_name` + -Replaced by `commit_branch_name` -* `guid_mapping_branch_name` + -Replaced by `configuration_branch_name` - -For more information, see xref:version_control.adoc[Git integration and version control]. - -== Version 9.10.0.cl, March 2024 - -=== New API endpoints - -DBT:: - -* `POST /api/rest/2.0/dbt/dbt-connection` + -Creates a DBT connection. -* `POST /api/rest/2.0/dbt/generate-tml` + -Generates Worksheets and Tables for a given DBT connection. -* `POST /api/rest/2.0/dbt/generate-sync-tml` + -Synchronizes the existing TML of data models and Worksheets and imports them to ThoughtSpot. -* `POST /api/rest/2.0/dbt/search` + -Gets a list of DBT connection objects for a given user or Org. -* `POST /api/rest/2.0/dbt/{dbt_connection_identifier}` + -Updates a DBT connection. - -System:: - -`GET api/rest/2.0/system/banner` + -Gets cluster maintenance status and banner text. - -+ -For more information, see xref:tse-eco-mode.adoc#_cluster_status_during_upgrade[Cluster maintenance and upgrade]. - -== Version 9.8.0.cl, January 2024 - -The `deploy_policy` property in the `/api/rest/2.0/vcs/git/commits/deploy` endpoint now supports the `VALIDATE_ONLY` option, which allows you to compare and validate TML content on the destination environment against the content in the main branch before deploying commits. - -== Version 9.7.0.cl, November 2023 - -=== Version Control APIs - -This release introduces the following enhancements to the Version Control API endpoints: - -==== Git connection creation and update APIs - -The `POST /api/rest/2.0/vcs/git/config/create` and `POST /api/rest/2.0/vcs/git/config/update` API endpoints include the following enhancements: - -New parameters:: - -* `commit_branch_name` + -Allows configuring a commit branch for Git connections on your ThoughtSpot instance. ThoughtSpot recommends using `commit_branch_name` instead of `default_branch_name` in the API calls to prevent users from committing changes to the default deployment branch. -* `configuration_branch_name` + -Allows configuring a separate Git branch for storing and maintaining configuration files, such as GUID mapping and commit tracking files. If the `configuration_branch_name` property is defined, the `guid_mapping_branch_name` parameter is not required. - -Modified parameters:: -The `enable_guid_mapping` parameter is enabled by default. - -Separate branches for Orgs:: -If you are using Orgs and want to move content between these Orgs using version control APIs, ensure that you set a separate Git branch for each Org. If two Orgs are connected to the same Git `repository_url`, the `POST /api/rest/2.0/vcs/git/config/create` and `POST /api/rest/2.0/vcs/git/config/update` API endpoints do not support configuring the same branch name for these Orgs. - -Deprecation notice:: - -The `default_branch_name` and `guid_mapping_branch_name` parameters will be deprecated from version 10.0.0.cl and later releases. - -For more information, see xref:git-configuration.adoc#connectTS[Connect your ThoughtSpot environment to the Git repository]. - -==== Commit API - -The `POST /api/rest/2.0/vcs/git/branches/commit` API endpoint allows the following new attribute in the request body: - -* `delete_aware` -+ -When set to true, the system runs a check between the objects and files in the Git branch and destination environment or Org. If an object exists in the Git branch, but not the destination environment or Org, it will be deleted from the Git branch during the commit operation. - -For more information, see xref:version_control.adoc#_commit_files_and_changes[Commit files]. - -==== Deploy API - -Note the following changes: - -* The `branch_name` attribute is now mandatory in the `POST /api/rest/2.0/vcs/git/commits/deploy` API requests. Ensure that you specify the name of the Git branch from which the commits can be picked and deployed on the destination environment or Org. - -* After a successful deployment, a tracking file is generated with the `commit_id` and saved in the Git branch that is used for storing configuration files. The `commit_id` recorded in the tracking file is used for comparing changes when new commits are pushed in the subsequent API calls. - -For more information, see xref:version_control.adoc#_deploy_commits[Deploy commits]. - -=== User API - -The following new API endpoints are introduced for user account management: - -* `POST /api/rest/2.0/users/activate` + -Activates an inactive user account. - -* `POST /api/rest/2.0/users/deactivate` + -Deactivates a user account. - -=== Support for sorting of columns at runtime -The following data API endpoints now support runtime sorting of columns: - -* `POST /api/rest/2.0/searchdata` + -* `POST /api/rest/2.0/metadata/liveboard/data` + -* `POST /api/rest/2.0/metadata/answer/data` + - -For more information, see xref:runtime-sort.adoc[Runtime sorting of columns]. - -== Version 9.6.0.cl, October 2023 - -=== New API endpoints - -* `POST /api/rest/2.0/customization/custom-actions/search` + -Gets custom action objects -* `POST /api/rest/2.0/customization/custom-actions` + -Creates a custom action -* `POST /api/rest/2.0/customization/custom-actions/{custom_action_identifier}/update` + -Updates the properties of a custom action object. -* `POST /api/rest/2.0/customization/custom-actions/{custom_action_identifier}/delete` + -Deletes a custom action - -=== SDK for TypeScript - -ThoughtSpot provides TypeScript SDK to help client applications call REST APIs using TypeScript. You can download the SDK from the link:https://www.npmjs.com/package/@thoughtspot/rest-api-sdk?activeTab=readme[NPM site, window=_blank]. - -== Version 9.5.0.cl, September 2023 - -=== New API endpoints for Role-Based Access Control [beta betaBackground]^Beta^ - -* `POST /api/rest/2.0/roles/search` + -Gets details of role objects available in the ThoughtSpot system. -* `POST /api/rest/2.0/roles/create` + -Creates a role and assigns privileges -* `POST /api/rest/2.0/roles/{role_identifier}/update` + -Updates the properties of a given role -* `POST /api/rest/2.0/roles/{role_identifier}/delete` + -Removes a role object from the ThoughtSpot system - -For more information, see xref:roles.adoc[Role-based access control]. - -[NOTE] -==== -The roles APIs work only if the Role-Based Access Control (RBAC) [beta betaBackground]^Beta^ feature is enabled on your instance. The RBAC feature is turned off by default. To enable this feature, contact ThoughtSpot Support. -==== - -=== Enhancements and API modifications - -Support for runtime parameter overrides:: -The following data and report API endpoints support applying runtime parameter overrides: -* `POST /api/rest/2.0/searchdata` + -* `POST /api/rest/2.0/metadata/liveboard/data` + -* `POST /api/rest/2.0/metadata/answer/data` + -* `POST /api/rest/2.0/report/liveboard` + -* `POST /api/rest/2.0/report/answer` - -Git integration support for Orgs:: - -The Version Control API endpoints support using Orgs as disparate deployment environments. You can create separate Orgs for `dev`, `staging`, and `prod` and integrate these environments with a GitHub repo. - -+ -For more information, see xref:version_control.adoc[Git integration and version control]. - -=== Response code change [tag redBackground]#BREAKING CHANGE# - -The following endpoints now return the 204 response code instead of 200. The 204 code does not return a response body. This change may affect your current implementation, so we recommend that you update your code to avoid issues. - -* `POST /api/rest/2.0/connection/delete` -* `POST /api/rest/2.0/connection/update` -* `POST /api/rest/2.0/users/{user_identifier}/update` -* `POST /api/rest/2.0/users/{user_identifier}/delete` -* `POST /api/rest/2.0/users/change-password` -* `POST /api/rest/2.0/users/reset-password` -* `POST /api/rest/2.0/users/force-logout` -* `POST /api/rest/2.0/groups/{group_identifier}/update` -* `POST /api/rest/2.0/groups/{group_identifier}/delete` -* `POST /api/rest/2.0/metadata/delete` -* `POST /api/rest/2.0/orgs/{org_identifier}/update` -* `POST /api/rest/2.0/orgs/{org_identifier}/delete` -* `POST /api/rest/2.0/schedules/{schedule_identifier}/delete` -* `POST /api/rest/2.0/schedules/{schedule_identifier}/update` -* `POST /api/rest/2.0/security/metadata/assign` -* `POST /api/rest/2.0/security/metadata/share` -* `POST /api/rest/2.0/system/config-update` -* `POST /api/rest/2.0/tags/{tag_identifier}/update` -* `POST /api/rest/2.0/tags/{tag_identifier}/delete` -* `POST /api/rest/2.0/tags/assign` -* `POST /api/rest/2.0/tags/unassign` -* `POST /api/rest/2.0/vcs/git/config/delete` -* `POST /api/rest/2.0/auth/session/login` -* `POST /api/rest/2.0/auth/session/logout` -* `POST /api/rest/2.0/auth/token/revoke` - - -== Version 9.4.0.cl, August 2023 - -=== API endpoints to schedule and manage Liveboard jobs - -* `*POST* /api/rest/2.0/schedules/create` + -Creates a scheduled job for a Liveboard -* `*POST* /api/rest/2.0/schedules/{schedule_identifier}/update` + -Updates a scheduled job -* `*POST* /api/rest/2.0/schedules/search` + -Gets a list of Liveboard jobs configured on a ThoughtSpot instance -* `*POST* /api/rest/2.0/schedules/{schedule_identifier}/delete` + -Deletes a scheduled job. - -For more information, see link:{{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fschedules%2Fsearch-schedule[REST API v2.0 Reference]. - -=== API to fetch authentication token - -The `GET /api/rest/2.0/auth/session/token` API endpoint fetches the current authentication token used by the currently logged-in user. - -=== Version Control API enhancements - -* The following Version Control API endpoints support generating and maintaining a GUID mapping file on a Git branch connected to a ThoughtSpot instance: - -** `*POST* /api/rest/2.0/vcs/git/config/create` -** `*POST* /api/rest/2.0/vcs/git/config/update` - -=== User and group API enhancements - -* The `**POST** /api/rest/2.0/users/{user_identifier}/update` and `**POST** /api/rest/2.0/groups/{group_identifier}/update` support specifying the type of operation API request. For example, if you are removing a property of a user or group object, you can specify the `operation` type as `REMOVE` in the API request. -* The `**POST** /api/rest/2.0/users/{user_identifier}/update` allows you to define locale settings, preferences, and other properties for a user object. - -== Version 9.3.0.cl, June 2023 - -The following Version Control [beta betaBackground]^Beta^ API endpoints are now available for the lifecycle management of content on your deployment environments: - -* `*POST* /api/rest/2.0/vcs/git/config/search` -* `*POST* /api/rest/2.0/vcs/git/commits/search` -* `*POST* /api/rest/2.0/vcs/git/config/create` -* `*POST* /api/rest/2.0/vcs/git/config/update` -* `*POST* /api/rest/2.0/vcs/git/config/delete` -* `*POST* /api/rest/2.0/vcs/git/branches/commit` -* `*POST* /api/rest/2.0/vcs/git/commits/{commit_id}/revert` -* `*POST* /api/rest/2.0/vcs/git/branches/validate` -* `*POST* /api/rest/2.0/vcs/git/commits/deploy` - -For more information, see xref:version_control.adoc[Version control and Git integration]. - -== Version 9.2.0.cl, May 2023 - -New endpoints:: - -* System -+ -** `POST /api/rest/2.0/system/config-update` + -Updates system configuration -+ -** `GET /api/rest/2.0/system/config-overrides` + -Gets system configuration overrides - -* Connections -+ -** POST /api/rest/2.0/connection/create + -Creates a data connection - -** `POST /api/rest/2.0/connection/search` + -Gets a list of data connections - -** `POST /api/rest/2.0/connection/update` + -Updates a data connection - -** `POST /api/rest/2.0/connection/delete` + -Deletes a data connection - -Enhancements:: - -* Support for runtime filters and runtime sorting of columns + -The following REST API v2.0 endpoints support applying xref:runtime-filters.adoc#_rest_api_v2_0_endpoints[runtime filters] and xref:runtime-sort.adoc[sorting column data]: -+ -** `POST /api/rest/2.0/report/liveboard` + -** `POST /api/rest/2.0/report/answer` - -* Search users by their favorites -+ -The `/api/rest/2.0/users/search` API endpoint allows searching users by their favorite objects and home Liveboard setting. - -* Ability to log in to a specific Org -+ -The `/api/rest/2.0/auth/session/login` API endpoint now allows ThoughtSpot users to log in to a specific Org context. +=== Version control API -== Version 9.0.0.cl, February 2023 +Git integration:: +ThoughtSpot introduces REST API v2.0 endpoints for version control (Git) integration: -The ThoughtSpot Cloud 9.0.0.cl release introduces the REST API v2.0 endpoints and Playground. For information about REST API v2.0 endpoints and Playground, see the following articles: +* `POST /api/rest/2.0/vcs/git/config/create` — Creates a Git configuration. +* `GET /api/rest/2.0/vcs/git/config/get` — Returns the current Git configuration. +* `PUT /api/rest/2.0/vcs/git/config/update` — Updates the Git configuration. +* `DELETE /api/rest/2.0/vcs/git/config/delete` — Deletes the Git configuration. +* `POST /api/rest/2.0/vcs/git/branches/commit` — Commits TML changes to a Git branch. +* `POST /api/rest/2.0/vcs/git/branches/validate` — Validates TML objects on a Git branch. +* `POST /api/rest/2.0/vcs/git/branches/pull` — Pulls changes from a Git branch into ThoughtSpot. -* xref:rest-api-v2.adoc[REST API v2.0] -* xref:rest-api-v2-getstarted.adoc[Get started with REST API v2.0] -* xref:rest-api-v2-reference.adoc[REST API v2.0 reference] -* xref:rest-api-v1v2-comparison.adoc[REST API v1 and v2.0 comparison] +For more information, see xref:version-control.adoc[Version control and Git integration]. From 0a5ae843d180b43b1356ebd6cdd043911b1d3a82 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 17 Aug 2026 09:41:30 +0530 Subject: [PATCH 022/154] docs: add Visual Embed SDK 1.52.x changelog entries (SCAL-317516, SCAL-314461) --- modules/ROOT/pages/api-changelog.adoc | 1843 ++----------------------- 1 file changed, 81 insertions(+), 1762 deletions(-) diff --git a/modules/ROOT/pages/api-changelog.adoc b/modules/ROOT/pages/api-changelog.adoc index 0619c8767..28c0b59df 100644 --- a/modules/ROOT/pages/api-changelog.adoc +++ b/modules/ROOT/pages/api-changelog.adoc @@ -8,6 +8,85 @@ This page documents the changes introduced in each release of the Visual Embed SDK. For information about the REST API v2.0 changes, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. +== Version 1.52.x, September 2026 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| + +[discrete] +===== Browser history management in full application embedding + +// SOURCE: SCAL-317516 +// SOURCE: thoughtspot/visual-embed-sdk/src/types.ts (master) + +ThoughtSpot 26.9.0.cl introduces the `overrideHistoryState` configuration parameter for `AppEmbed`. When embedding ThoughtSpot in a host application, every internal ThoughtSpot navigation event (for example, switching between Liveboards or Answers) pushes a new entry onto the browser's history stack. This causes the browser *Back* button to step through ThoughtSpot's internal navigation before returning to the host application's prior page. + +Setting `overrideHistoryState: true` converts all ThoughtSpot internal `pushState` calls to `replaceState`, preventing ThoughtSpot navigation from polluting the host application's browser history stack. + +[source,JavaScript] +---- +import { AppEmbed, init, AuthType } from '@thoughtspot/visual-embed-sdk'; + +init({ + thoughtSpotHost: 'https://.thoughtspot.cloud', + authType: AuthType.TrustedAuthToken, + getAuthToken: () => fetch('/ts-token').then(r => r.json()).then(d => d.token), +}); + +const embed = new AppEmbed('#embed-container', { + frameParams: { width: '100%', height: '100%' }, + overrideHistoryState: true, // <1> +}); + +embed.render(); +---- +<1> When set to `true`, ThoughtSpot replaces rather than pushes browser history entries during internal navigation. + +[NOTE] +==== +`overrideHistoryState` is available on `AppEmbed` only. It is not supported on `LiveboardEmbed`, `SearchEmbed`, or `SpotterEmbed`. Validate behavior across Chrome, Firefox, and Safari before enabling in production. +==== + +For more information, see xref:full-app-embed.adoc[Full application embedding]. + +|[tag greenBackground]#NEW FEATURE# a| + +[discrete] +===== Collections in left navigation panel + +// SOURCE: SCAL-314461 + +The `HomeLeftNavItem.Collections` enum value is now available in the Visual Embed SDK. Embed developers can include *Collections* as a selectable navigation option in the embedded left navigation panel for full application embeds. When enabled, end users of the embedded application can navigate to *Collections* from the left navigation panel. + +[source,JavaScript] +---- +import { AppEmbed, HomeLeftNavItem, init, AuthType } from '@thoughtspot/visual-embed-sdk'; + +init({ + thoughtSpotHost: 'https://.thoughtspot.cloud', + authType: AuthType.TrustedAuthToken, + getAuthToken: () => fetch('/ts-token').then(r => r.json()).then(d => d.token), +}); + +const embed = new AppEmbed('#embed-container', { + frameParams: { width: '100%', height: '100%' }, + leftNavOrder: [ + HomeLeftNavItem.Home, + HomeLeftNavItem.Liveboards, + HomeLeftNavItem.Answers, + HomeLeftNavItem.Collections, // <1> + ], +}); + +embed.render(); +---- +<1> Include `HomeLeftNavItem.Collections` in the `leftNavOrder` array to show Collections in the embedded left navigation panel. + +For more information, see xref:full-app-customize.adoc[Customize full application embedding]. + +|==== + == Version 1.51.x, August 2026 [width="100%" cols="1,4"] @@ -156,1767 +235,7 @@ New events and action IDs;; * `EmbedEvent.DownloadLiveboardAsContinuousPDF` + Emits when the download action is triggered. * `HostEvent.DownloadLiveboardAsContinuousPDF` + -Programmatically triggers the download action to export the PDF with a continuous Liveboard layout. +Triggers a PDF download of the Liveboard. * `Action.DownloadLiveboardAsContinuousPDF` + -Action ID to control the visibility of download action that exports continuous PDFs. - -Liveboard download actions:: - -The following action IDs are introduced in the SDK for the download buttons at the Liveboard level: - -* `Action.DownloadLiveboard` + -* `Action.DownloadLiveboardAsXlsx` + -* `Action.DownloadLiveboardAsCsv` - -Test email for Liveboard scheduled jobs:: - -The SDK introduces the `isSendNowLiveboardSchedulingEnabled` to enable the **Send now** option for the Liveboard scheduled jobs. This option allows Liveboard users to send a test email notification to either themselves or the intended recipients of the Liveboard scheduled alerts. - -New events and action IDs;; - -* `EmbedEvent.SendTestScheduleEmail` + -Emits when *Send now* button is clicked. -* `HostEvent.SendTestScheduleEmail` + -Programmatically triggers the Send now action to send a test email notification for a Liveboard scheduled job. -* `Action.SendTestScheduleEmail` + -Action ID to disable, show, or hide the **Send now** button on the Liveboard schedule page. - -|[tag greenBackground]#NEW FEATURE# a| - -[discrete] -===== Spotter embedding - -The SDK introduces the following action IDs to control the visibility of specific UI components in chat panel of the embedded Spotter interface: - -* `Action.SpotterChatConnectorResources` + -For the connector resources section in the Spotter chat interface. -* `Action.SpotterChatConnectors` + -For the connectors panel section in the Spotter chat interface. -* `Action.SpotterChatModeSwitcher` + -For the mode switcher in the Spotter chat interface. - -|[tag greenBackground]#NEW FEATURE# a| - -[discrete] -===== Event handling -Note the following changes: - -EmbedEvent:: - -* `EmbedEvent.Subscribed` + -The SDK introduces the `EmbedEvent.Subscribed` to emit an event when a HostEvent listener is registered. You can use this event to dispatch host events during the initial load without race conditions. This is particularly useful for Spotter, where host events such as `HostEvent.ResetSpotterConversation` may be triggered immediately after load. -* `EmbedEvent.Error` + -The `EmbedEvent.Error` now fires on HostEvent payload validation failures. - -HostEvent:: -* `HostEvent.GetExportRequestForCurrentPinboard` [.version-badge.breaking]#Breaking# + -The response payload of the `GetExportRequestForCurrentPinboard` passthrough -host event has been updated to include a `type` discriminator field, making it -consistent with the shape of other host event responses. It now returns `{ data: { v2Content }, type }` instead of `{ v2Content }` directly. This enhancement introduces a breaking change for any code that reads `result.v2Content` directly. Update your integration workflows to use `result.data.v2Content`. - - -|[tag greenBackground]#NEW FEATURE# a| - -[discrete] -===== Personalized View selection via host event - -* `EmbedEvent.ChangePersonalizedView` + -Emits when a user selects a different Personalized View on an embedded Liveboard, or resets to the default view. For more information, see xref:EmbedEvent.adoc#_changepersonalizedview[EmbedEvent reference documentation]. - -* `HostEvent.SelectPersonalizedView` + -The SDK introduces `HostEvent.SelectPersonalizedView` to programmatically switch the active Personalized View on an embedded Liveboard from the host application. For more information, see xref:HostEvent.SelectPersonalizedView[HostEvent reference documentation]. - -⚠️Deprecated events and action IDs️:: -The following events are deprecated and replaced with new event IDs. - -* `EmbedEvent.UpdatePersonalisedView`. Use `EmbedEvent.UpdatePersonalizedView`. -* `EmbedEvent.SavePersonalisedView`. Use `EmbedEvent.SavePersonalizedView`. -* `EmbedEvent.DeletePersonalisedView`. Use `EmbedEvent.DeletePersonalizedView`. -* `HostEvent.ResetLiveboardPersonalisedView`. Use `HostEvent.ResetLiveboardPersonalizedView`. -* `Action.PersonalisedViewsDropdown`. Use `Action.PersonalizedViewsDropdown`. -* `Action.OrganiseFavourites`. Use `Action.OrganizeFavorites`. - -|==== - - -== Version 1.47.x, April 2026 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| **Spotter chat history sidebar customization** - -The SDK introduces the `SpotterSidebarViewConfig` interface and the `spotterSidebarConfig` object with configuration controls to customize the appearance and contents of the chat history panel. Developers can use the following properties in the `spotterSidebarConfig` object to enable or disable chat history panel and customize the contents of the sidebar when enabled: - -* `enablePastConversationsSidebar` + -Controls the visibility of the past conversations sidebar panel. The chat history panel is disabled by default in embed view. When this property in `spotterSidebarConfig` is specified, it takes precedence over the standalone `enablePastConversationsSidebar` setting, which is deprecated from v1.47.0. - -* `spotterSidebarTitle` + -Allows adding custom title text for the sidebar header. - -* `spotterSidebarDefaultExpanded` + -Sets the default state of the sidebar to expanded or collapsed view. - -* `spotterChatRenameLabel` + -Allows setting a custom label for the **Rename** action in the conversation edit menu. - -* `spotterChatDeleteLabel` + -Allows setting a custom label for the **Delete** action in the conversation edit menu. - -* `spotterDeleteConversationModalTitle` + -Allows editing the title text of the chat delete confirmation modal. - -* `spotterPastConversationAlertMessage` + -Sets a custom message text for the past conversation banner alert. Defaults to the translated alert message. - -* `spotterBestPracticesLabel` + -Allows customizing the label for the best practices button in the sidebar footer. - -* `spotterDocumentationUrl` + -The best practices documentation link shown in the sidebar footer. You can customize the link by specifying the full URL. - -* `spotterConversationsBatchSize` + -Sets the number of conversations to fetch per batch when loading conversation history. Default is `30`. - -* `spotterNewChatButtonTitle` + -Allows customizing the title text for the **New chat** button in the sidebar. - -|[tag redBackground]#DEPRECATED# a| **Standalone `enablePastConversationsSidebar` attribute in Spotter embed** - -The standalone `enablePastConversationsSidebar` property on `SpotterEmbedViewConfig` and `AppViewConfig` is deprecated from SDK 1.47.0 and ThoughtSpot 26.4.0.cl. - -Use `enablePastConversationsSidebar` in the `spotterSidebarConfig` instead. When both are defined, the property in the `spotterSidebarConfig` object takes precedence. - -[source,javascript] ----- -// Deprecated -enablePastConversationsSidebar: false, - -// Recommended -spotterSidebarConfig: { - enablePastConversationsSidebar: true, - //... other config properties -} ----- - -|[tag greenBackground]#NEW FEATURE# a| **Spotter chat UI branding** - -The SDK introduces the `SpotterChatViewConfig` interface for customizing branding in Spotter tool response cards. You can pass these parameters as the `spotterChatConfig` object properties in `SpotterEmbed`, `AppEmbed`, or `LiveboardEmbed` where Spotter interface is used. - -* `hideToolResponseCardBranding` + -When set to `true`, hides the ThoughtSpot logo and icon in tool response cards. The branding label prefix is controlled separately via `toolResponseCardBrandingLabel`. Default value is `false`. - -* `toolResponseCardBrandingLabel` + -Custom label to replace the `ThoughtSpot` prefix in tool response cards. Set to an empty string (`''`) to hide the prefix entirely. - -[NOTE] -==== -These settings do not affect the external MCP tool branding. -==== - -|[tag greenBackground]#NEW FEATURE# a|**Liveboard embed enhancements** - -Personalized Liveboard view:: - -The `personalizedViewId` property allows embedding a saved personalized view of a Liveboard. A personalized view is a saved configuration that includes specific filter selections and changes applied by a user. To embed a personalized view of Liveboard, specify the GUID of the saved personalized view to load along with `liveboardId`. - -Centralized Liveboard filter setting:: - -When set to `true`, the `isCentralizedLiveboardFilterUXEnabled` enables displaying a unified modal to manage and update multiple filters at once, replacing the older individual filter interactions. This feature is disabled by default on ThoughtSpot Embedded instances. - -|[tag greenBackground]#NEW FEATURE# a|**Option to include current period in rolling date filters** - -If the current period inclusion in rolling date filters feature is enabled on your instance, the rolling date filters options such as **Last ** and **Next ** for the Liveboards and Answers in the embed view will allow you to include current period. For example, when you define a date range such as "Last 2 months", the date filter interface displays the **Include this month** checkbox. -To disable this feature, use the `isThisPeriodInDateFiltersEnabled` setting. To hide, show, or disable this option in the embed view, use the action ID, `Action.IncludeCurrentPeriod`. -|==== - - -== Version 1.46.x, March 2026 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| **Host events with page context framework** - -The Visual Embed SDK introduces the HostEvent V2 framework for improved handling and execution of host events in embedded ThoughtSpot experiences with multi-layer UI interactions. The v2 framework supports the page context feature, which tracks the top-most active layer in the user's current context. Developers can use this feature to route events based on the user's current context or set a specific target context for precise and predictable handling of host events. - -* To enable this feature, set `useHostEventsV2` to `true`. -* To retrieve the current context, use `getCurrentContext()`. -* To set a target context for a host event, use xref:ContextType.adoc[ContextType]. - -For more information, refer to the xref:events-context-aware-routing.adoc[Host events documentation]. - -|[tag redBackground]#DEPRECATED# a| **dataPanelV2** - -The `dataPanelV2` parameter is deprecated and can no longer be used to switch between the classic and new data panel experience. By default, the new data panel v2 experience is enabled on all ThoughtSpot embedded instances. - -|[tag greenBackground]#NEW FEATURE# a| **Spotter experience** -The SDK includes the following parameters, action IDs, and events to customize the Spotter embed experience. - -Chat history sidebar customization:: - -//* `SpotterSidebarViewConfig` interface with configuration parameters for customizing the visibility and appearance of the chat history sidebar. -//* `spotterSidebarConfig` properties for customizing the appearance and available options in the chat history sidebar. -* Action IDs for customizing the visibility and status of actions in the embedded Spotter interface: -** `Action.DataModelInstructions` for the data model instructions icon. -** `Action.SpotterSidebarHeader` for the chat history sidebar header -** `Action.SpotterSidebarFooter` for the chat history sidebar footer -** `Action.SpotterSidebarToggle` for the chat history toggle that expands or collapses the sidebar. -** `Action.SpotterNewChat` for the new chat icon in the chat history sidebar. -** `Action.SpotterPastChatBanner` for the banner in the chat history sidebar. -** `Action.SpotterChatMenu` for the chat menu component in the chat history sidebar. -** `Action.SpotterChatRename` for **Rename** action in the chat menu of a saved chat. -** `Action.SpotterChatDelete` for **Delete** action in the chat menu of a saved chat. -//** `Action.SpotterDocs` for best practices documentation icon in the chat history sidebar. - -Events:: -* `HostEvent.DataModelInstructions` + -Opens the Data Model instructions modal. -* `EmbedEvent.DataModelInstructions` + -Is emitted when a user clicks the Data Model instructions icon in the Spotter interface. -* `EmbedEvent.SpotterConversationRenamed` + -Is emitted when a user renames a saved chat. -* `EmbedEvent.SpotterConversationDeleted` + -Is emitted when a saved chat is deleted. -* `EmbedEvent.SpotterConversationSelected` + -Is emitted when a saved chat is selected in the chat history sidebar. - -|[tag greenBackground]#NEW FEATURE# | `enableLinkOverridesV2` + - -Use this configuration setting to override ThoughtSpot URLs on hover or when opening in a new tab. This is recommended over the earlier `linkOverride` flag for a better user experience. - -|[tag greenBackground]#NEW FEATURE# a| **Liveboard experience enhancements** - -* The `isLiveboardXLSXCSVDownloadEnabled` attribute adds XLSX and CSV to the available Liveboard download formats. -* The `isGranularXLSXCSVSchedulesEnabled` attribute allows you to include the entire Liveboard, specific visualizations, or only tables and pivot tables in the XLSX and CSV schedules. +Action ID to show or hide the continuous PDF download button. |==== - -== Version 1.45.0, February 2026 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| **Spotter enhancements** - -You can now embed the Spotter 3 experience in your application and use features such as Auto mode for automatic data model selection, chat history, and a new chat prompt interface. - -* To enable the new chat prompt interface, set `updatedSpotterChatPrompt` to `true`. -* To use Auto mode, set the `worksheetId` to `auto_mode`. -* To enable Chat history, set `enablePastConversationsSidebar` to `true`. - -For more information, see xref:embed-spotter.adoc[Embedding Spotter] and xref:embed-ai-analytics.adoc#_feature_status_and_availability_in_embed_mode[Features available with Spotter 3 experience]. - -Events:: - -* `EmbedEvent.AddToCoaching` for the *Add to Coaching* workflow in a Spotter conversation session -* `HostEvent.AddToCoaching` to trigger the *Add to Coaching* action in a Spotter conversation session. -* `HostEvent.StartNewSpotterConversation` to trigger the action to start a new chat session with Spotter. - -[NOTE] -==== -On Spotter embed deployments running version 26.2.0.cl or later, the *Add to Coaching* feature is enabled by default. To disable or hide the *Add to Coaching* button, use the xref:Action.adoc#_inconversationtraining[InConversationTraining] action ID. -==== - -|[tag greenBackground]#NEW FEATURE# a| **Liveboard experience enhancements** + - -Styling and grouping:: - -* The `isLiveboardStylingAndGrouping` attribute, used to enable the Liveboard styling and grouping feature, is now replaced with `isLiveboardMasterpiecesEnabled`. While your existing configuration with the deprecated `isLiveboardStylingAndGrouping` attribute continues to work, we recommend switching to the new configuration setting. -* The following action IDs are now available to show, disable, or hide the grouping menu actions on a Liveboard: -** `Action.MoveToGroup` for the **Move to Group** menu action. -** `Action.MoveOutOfGroup` for the **Move out of Group** menu action. -** `Action.CreateGroup` for the *Create Group* menu action. -** `Action.UngroupLiveboardGroup` for the **Ungroup Liveboard Group** menu action. - -Filter chip masking:: -The `showMaskedFilterChip` boolean parameter is now available to control the visibility of masked filter chips on a Liveboard. When set to `true`, if a Liveboard is shared with a user who has restricted access due to column-level security, the filter chip corresponding to those inaccessible columns will be displayed as masked to that user. When set to `false`, the filter chip for inaccessible columns will not be visible to the user. -+ -For more information, see link:https://docs.thoughtspot.com/cloud/latest/security-data-object#csr-liveboard[Column security rules on Liveboards]. -+ -The `showMaskedFilterChip` setting is also available in full application embedding. - -|[tag greenBackground]#NEW FEATURE# a| **Publishing objects** - -The following action IDs are available for the data publishing menu actions in the *Data workspace* page: - -* `Action.Publish` for *Publish* -* `Action.ManagePublishing` for *Manage publishing* -* `Action.Unpublish` for *Unpublish* -* `Action.Parameterize` for *Parameterize* -|[tag greenBackground]#NEW FEATURE# a| **Error handling improvements** - -To handle errors in the embedding workflows, the SDK includes the following features: - -* `ErrorDetailsTypes` enum for categorizing error types, such as `API`, `VALIDATION_ERROR`, and `NETWORK`. -* `EmbedErrorCodes` enum with specific error codes for programmatic error handling. -* `EmbedErrorDetailsEvent` interface for structured error event handling. - -For more information, see link:https://developers.thoughtspot.com/docs/Enumeration_EmbedErrorCodes[EmbedErrorCodes] and link:https://developers.thoughtspot.com/docs/Enumeration_ErrorDetailsTypes[ErrorDetailsTypes]. -|==== - -== Version 1.44.x, January 2026 - -[width="100%" cols="1,4"] -|==== - -|[tag redBackground]#DEPRECATED# | **Use `minimumHeight` instead of `defaultHeight`** + - -The `defaultHeight` parameter is deprecated in Visual Embed SDK v1.44.2 and later. -To set the minimum height of the embed container for ThoughtSpot components such as a Liveboard, use the `minimumHeight` attribute instead. - -|[tag greenBackground]#NEW FEATURE# a| *Intercepting API calls* + -The SDK provides the following attributes to intercept API calls and handle interception via events and custom workflows: - -//* `enableApiIntercept` + -//When set to true, enables the feature on your ThoughtSpot embed. -* `interceptUrls` + -Allows configuring which API calls to intercept. -* `interceptTimeout` + -Sets the timeout duration for handling interception. -* `isOnBeforeGetVizDataInterceptEnabled` + -When set to true, it enables use of `EmbedEvent.OnBeforeGetVizDataIntercept` to emit and intercept search execution calls initiated by users and implement custom logic or workflows to allow or restrict search execution. -* `EmbedEvent.ApiIntercept` + -Emits when an API call matching the conditions defined in `interceptUrls` is detected. - -For more information, see xref:api-intercept.adoc[Intercept API calls and search requests]. -|==== - - -== Version 1.43.0, November 2025 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| *Code-based custom actions* - -The following enumerations are available for code-based custom actions: - -* `CustomActionTarget` + -To define the target object for the custom action, such as on a Liveboard, visualization, Answer, or in Spotter. -* `CustomActionsPosition` + -To define the position of the custom action in the target object, such as primary menu, **More** options menu image:./images/icon-more-10px.png[the more options menu], or the contextual menu. -|[tag greenBackground]#NEW FEATURE# | *Attribute to set Parameter chip visibility during overrides* + -The `HostEvent.UpdateParameters` event now supports configuring the `isVisibleToUser` attribute to show or hide the Parameter chips after an override. For more information, see xref:runtime-parameters.adoc#_show_or_hide_parameter_chips_in_embedded_sessions[Show or hide Parameter chips in embedded sessions]. -|==== - -== Version 1.42.0, October 2025 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a|*Runtime overrides in Spotter embed* - -The Visual Embed SDK now supports runtime overrides in Spotter embed. - -* To apply runtime filters, use the `runtimeFilters` object -* To apply runtime Parameters, use the `runtimeParameters` object. - -|[tag greenBackground]#NEW FEATURE# a|*PNG images in Liveboard schedule notifications* + -To enable embedding PNG images of Liveboards in scheduled job notifications sent to subscribers, the SDK provides the `isPNGInScheduledEmailsEnabled` boolean parameter. When set to true, scheduled emails will include a PNG image of the Liveboard. - -The SDK also provides the following action IDs: - -* `Action.PngScreenshotInEmail` + -Adds the option to include a PNG screenshot in the notification email body when scheduling emails in ThoughtSpot. -* `Action.RemoveAttachment` + -Allows the user to remove an attachment from the email configuration in the schedule email dialog. -|[tag greenBackground]#NEW FEATURE# a|*Spotter embed* - -Action IDs:: -The following action IDs are available for Spotter embedding and are currently supported only in the `hiddenActions` array: - -* `Action.SpotterWarningsBanner` + -Action ID to control the visibility of the Spotter warnings banner in the UI. This banner displays general warnings or informational messages related to Spotter results or queries. -* `Action.SpotterWarningsOnTokens` + -Action ID to control the visibility of warning indicators on individual Spotter tokens parsed from a Spotter query. -* `Action.SpotterTokenQuickEdit` + -Action ID to enable or disable the link:https://docs.thoughtspot.com/cloud/latest/spotter-getting-started#quick-edits[quick edit functionality^] for Spotter tokens. -|==== - -== Version 1.41.0, September 2025 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a|*React component for Spotter Agent embed* - -The Visual Embed SDK now supports embedding Spotter Agent feature without a body or Spotter interface in a React app. For ease of implementation, the SDK also provides a custom React hook, `useSpotterAgent`. - -For more information, see xref:embed-ts-react-app.adoc#_embed_spotter_agent_in_your_own_app[Spotter Agent embedding in a React app]. - -|[tag greenBackground]#NEW FEATURE# a|*Event handlers for Spotter embed* - -The following event handlers are now available for Spotter embed: - -* `EmbedEvent.SpotterInit` + -Fires when Spotter embed component rendering is initialized. -* `EmbedEvent.QueryChanged` + -Fires when the Spotter query is updated by the user. -* `HostEvent.AskSpotter` + -Triggers *Ask Spotter* action for visualizations. -* `HostEvent.GetParameters` + -Triggers the action to fetch runtime Parameters applied on a visualization. -* `HostEvent.UpdateParameters` + -Triggers the action to update runtime Parameters for a Spotter-generated Answer. -* `HostEvent.GetTML` + -Triggers the action to get TML representation of a Spotter-generated Answer. - -For more information, see xref:EmbedEvent.adoc[EmbedEvent] and xref:HostEvent.adoc[HostEvent]. - -|[tag greenBackground]#NEW FEATURE# a|*Event handlers for Spotter Agent embed* - -You can now use the following host events in Spotter Agent embedding: - -- `HostEvent.DownloadAsCsv` + -Triggers the action to download a Spotter-generated Answer in CSV format. -- `HostEvent.DownloadAsPng` + -Triggers the action to download a Spotter-generated Answer in PNG format. -- `HostEvent.DownloadAsXlsx` + -Triggers the action to download a Spotter-generated Answer in XLSX format. -- `HostEvent.DownloadAsPdf` + -Triggers the action to download the PDF version of a Spotter-generated Answer. -- `HostEvent.Pin` + -Triggers the action to add a Spotter-generated Answer to a Liveboard. -- `HostEvent.Save` + -Triggers the *Save* action for a Spotter-generated Answer. - -For more information, see xref:HostEvent.adoc[HostEvent]. - -|[tag greenBackground]#NEW FEATURE# a| *Lazy loading of visualizations on an embedded Liveboard* - -You can now use the `lazyLoadingForFullHeight` parameter with the `fullHeight` to progressively load visualizations on an embedded Liveboard. When both these attributes are enabled, only the visualizations in the current viewport are loaded initially, while the other visualizations load as the user scrolls the Liveboard page. - -You can also set the margin property for lazy loading to define when the visualization should load. - -For more information, see xref:lazy-loading-fullheight.adoc[Lazy loading of visualizations in an embedded Liveboard]. - -|[tag greenBackground]#NEW FEATURE# a| *Full application embed* + - -You can now enable the persona-based left navigation panel and home page experience on your ThoughtSpot instance. This feature is disabled by default on ThoughtSpot instances and is available for Early Access. When it's enabled on your ThoughtSpot instance, you can roll out the new experience on embedding applications by configuring the xref:AppViewConfig.adoc#_discoveryexperience[`discoveryExperience`] attribute. - -When enabled, the left navigation panel organizes the application menu into persona-based contextual sections. For example, the *Insights* icon for business users, the *Data Workspace* icon for Analysts and Data engineers, and the *Develop* icon for developers. Your application users can navigate to each option using the tabs in the left navigation panel. The new interface also provides a slider to allow users to view or hide the left navigation panel. -|==== - -== Version 1.40.0, July 2025 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| *Fullscreen presentation mode controls for embedded Liveboards and visualizations* + -Developers can now control whether a visualization or Liveboard can be presented in full screen mode using the `disableFullscreenPresentation` attribute. By default, the full screen mode is disabled on embedded Liveboards and visualizations. -|[tag greenBackground]#NEW FEATURE# a| *PDF download settings* + -Developers can now control the display of *Include cover page* and *Include filter page(s)* options on the Download PDF dialog for Liveboards. The *Include cover page* and *Include filter page(s)* options are disabled by default on ThoughtSpot instances. When this feature is enabled, developers can use the `coverAndFilterOptionInPDF` attribute to show or hide these options for the Liveboard users in their embedding app. - -|[tag greenBackground]#NEW FEATURE# a| *Parameter for overriding a default primary action* + - -If Spotter is enabled on your instance, the *Spotter* button appears by default as the primary action on embedded Liveboard charts; if Spotter is not enabled, the *Explore* button is set as the primary action. If you want to replace the primary action with a different action, you can now use the `primaryAction` attribute. - -For more information, see xref:embed-actions.adoc#_override_default_primary_actions[Override default primary action]. - -|[tag greenBackground]#NEW FEATURE# a| *Full application embed experience enhancements* + - -The SDK now includes the `hideObjectSearch` property, which allows developers to hide the object search button in the navigation bar when embedding the full application. - -|[tag greenBackground]#NEW FEATURE# a| *Host events* + - -In this version, the SDK introduces the following host event handlers: - -- `HostEvent.ExitPresentMode` + -Triggers the exit action that allows users to exit the Liveboard or visualization present mode. -- `HostEvent.SpotterSearch` + -Triggers a search operation for the specified query string in Spotter embed. -- `HostEvent.PreviewSpotterData` + -Triggers the *Preview data* action that shows the data used for Spotter conversations. -- `HostEvent.ResetSpotterConversation` + -Triggers the *Reset* action to reset a Spotter conversation. -- `HostEvent.EditLastPrompt` + -Triggers the edit prompt action. -- `HostEvent.DeleteLastPrompt` + -Triggers the delete prompt action. - -For more information, see xref:HostEvent.adoc[HostEvent]. - -|[tag greenBackground]#NEW FEATURE# a|*Events support for Spotter embed* - -You can now use the following host events in Spotter embed: - -- `HostEvent.DownloadAsCsv` -- `HostEvent.DownloadAsPng` -- `HostEvent.DownloadAsXlsx` -- `HostEvent.Edit` -//- `HostEvent.GetParameters` -//- `HostEvent.GetTML` -- `HostEvent.MakeACopy` -- `HostEvent.Pin` -- `HostEvent.Save` - -For more information, see xref:HostEvent.adoc[HostEvent]. - -|[tag greenBackground]#NEW FEATURE# a| *Lazy loading with full height* - -The SDK introduces `lazyLoadingForFullHeight` parameter, which enables progressive loading of visualizations on an embedded Liveboard. -This parameter works in conjunction with the `fullHeight` attribute. When both these attributes are enabled, only the visualizations in the current viewport are loaded initially, while the other visualizations load as the user scrolls the Liveboard page. - -[NOTE] -==== -To use these attributes effectively in embedded applications, your ThoughtSpot instance must be upgraded to version 10.12.0.cl or later. -==== -|==== - - -== Version 1.39.0, July 2025 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| *Spotter embed components with new names* + -The following Spotter embed components are now deprecated and replaced with new components in the SDK and Visual Embed Playground: - -* `ConversationEmbed` + -Replaced with `SpotterEmbed` -* `ConversationViewConfig` + -Replaced with `SpotterEmbedViewConfig` -* `BodylessConversation` + -Replaced with `SpotterAgentEmbed` -* `BodylessConversationViewConfig` + -Replaced with `SpotterAgentEmbedViewConfig` - -The deprecated components with old names in the existing Spotter embed implementations will continue to function until further notice. For code samples with new component names, see xref:embed-spotter.adoc[Spotter embed documentation]. - -|[tag greenBackground]#NEW FEATURE# a| *Action ID for Spotter in-conversation training* + -For ThoughtSpot instances that have the new Spotter in-conversation training workflow enabled, the SDK provides the action ID `Action.InConversationTraining` to manage the visibility of the *Add to Coaching* button on Answers generated from Spotter prompts. - -[NOTE] -The *Add to Coaching* feature is currently in beta and is turned off by default on embed deployments. To enable this feature on your instance, contact ThoughtSpot Support. - -|[tag greenBackground]#NEW FEATURE# a|*Events support for Spotter embed* - -New embed events:: - -- `EmbedEvent.ExitPresentMode` + -Emits when a user exits the Liveboard or visualization presentation mode. -- `EmbedEvent.LastPromptDeleted` + -Emits when a query prompt in Spotter embed is deleted. -- `EmbedEvent.LastPromptEdited` + -Emits when a query prompt in Spotter embed is edited. -- `EmbedEvent.ResetSpotterConversation` + -Emits when a Spotter query is reset. -- `EmbedEvent.PreviewSpotterData` + -Emits when a user clicks the Preview data button in the Spotter conversation panel. -- `EmbedEvent.SpotterQueryTriggered` -Emits when a Spotter query is triggered. - -The following embed events are also supported in Spotter embed: - -- `EmbedEvent.AddRemoveColumns` -- `EmbedEvent.AnswerChartSwitcher` -- `EmbedEvent.AuthExpire` -- `EmbedEvent.AuthInit` -- `EmbedEvent.CopyToClipboard` -- `EmbedEvent.CustomAction` -- `EmbedEvent.Data` -- `EmbedEvent.DataSourceSelected` -- `EmbedEvent.DialogClose` -- `EmbedEvent.DialogOpen` -- `EmbedEvent.Download` -- `EmbedEvent.DownloadAsCsv` -- `EmbedEvent.DownloadAsPng` -- `EmbedEvent.DownloadAsXlsx` -- `EmbedEvent.DrillDown` -- `EmbedEvent.DrillExclude` -- `EmbedEvent.DrillInclude` -- `EmbedEvent.Edit` -- `EmbedEvent.Error` -- `EmbedEvent.Load` -- `EmbedEvent.Pin` -- `EmbedEvent.Save` -- `EmbedEvent.TableVizRendered` -- `EmbedEvent.VizPointClick` -- `EmbedEvent.VizPointDoubleClick` -- `EmbedEvent.VizPointRightClick` - -For more information, see xref:EmbedEvent.adoc[EmbedEvent]. - -|==== - -== Version 1.38.0, June 2025 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| *String IDs for text customization* + -Developers can now customize a specific occurrence of a visible text string in the ThoughtSpot UI using the `stringIDs` object in the customization interface. - -To locate the string IDs, SDK provides the `exposeTranslationIds` attribute. By setting `exposeTranslationIds` to `true` in the Playground, you can find the string ID of the UI text and use it in your customization code. - -Additionally, the SDK provides the `StringIDsUrl` attribute to allow using a JSON file with string IDs and custom strings to override the visible text in the UI. - -For more information, see xref:customize-text-strings.adoc[Customize text strings]. - -|[tag greenBackground]#NEW FEATURE# a| *Hide columns on list pages* + - -In full app embedding, you can now hide the following columns on the *Liveboards* and *Answers* listing pages using the `hiddenListColumns` array: - -* *Author* + -`hiddenListColumns: [ListPageColumns.Author]` -* *Favorite* + -`hiddenListColumns: [ListPageColumns.Favourite]` -* *Last modified* + -`hiddenListColumns: [ListPageColumns.DateSort]` -* *Tags* + -`hiddenListColumns: [ListPageColumns.Tags]` -* *Share* + -`hiddenListColumns: [ListPageColumns.Share]` + - -For more information, see xref:full-app-customize.adoc#_hide_columns_on_list_pages_new_experience[Customize full application embed]. -|==== - -== Version 1.37.0, April 2025 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| -The SDK now provides the `customVariablesForThirdPartyTools` setting to pass custom variables when integrating third-party tools and running custom scripts in your embed. Developers can define this object in the **init()** function and add variables as key-value pairs. -This feature is available only if third-party integration is enabled on your instance and the script hosting domain URL is added to the CSP allowlist. - -For more information, see xref:3rd-party-script.adoc[Integrate third-party tools and allow custom scripts]. - -|[tag greenBackground]#NEW FEATURE# a| -You can now exclude search token string from the application URL by setting `excludeSearchTokenStringFromURL` to `true` in your embed with ThoughtSpot token-based Search or Search bar. - -|[tag greenBackground]#NEW FEATURE# a| This version of the SDK supports the following embed and host events: - -Embed Events:: - -* `EmbedEvent.TableVizRendered` + -Emits when a table visualization is rendered in the ThoughtSpot embedded app. You can also use this event as a hook to trigger host events such as `HostEvent.TransformTableVizData` on the table visualization. For more information, see the link:https://developers.thoughtspot.com/docs/Enumeration_EmbedEvent#_tablevizrendered[SDK reference documentation]. - -* `EmbedEvent.CreateLiveboard` + -Emits when a Liveboard is created. - -Host Events:: - -* `HostEvent.TransformTableVizData` + -Triggers the table visualization re-render with the updated data. You can use this event in conjunction with `EmbedEvent.TableVizRendered` to apply the modifications to table visualization payload. - -* `HostEvent.Remove` + -Triggers the *Delete* action on a Liveboard. -|==== - -== Version 1.36.0, February 2025 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| -The following HostEvents now allow custom parameters to set object properties programmatically: - -* `HostEvent.SaveAnswer` + -Allows adding `name` and `description` text strings. When these parameters are defined, the event triggers the Save action to save the Answer with the predefined properties without opening the *Describe your Answer* modal. -* `HostEvent.Pin` + -Allows adding custom properties for visualization ID, name, and description, Liveboard ID, and Tab ID. When these parameters are defined, the event triggers an action to pin the Answer to the Liveboard specified in the code, without opening the *Pin* modal. - -For more information, see xref:events-hostEvents.adoc#hostEventParameterization[Host Events] documentation. - -|[tag greenBackground]#NEW FEATURE# a| - -New configuration attributes:: - -* `disableSourceSelection` + -Disables data source selection panel for embed users when set to `true`. -* `hideSourceSelection` + -Hides data source selection panel when set to `true` -* `locale` + -Sets the xref:locale-setting.adoc[locale and regional settings] for the Spotter interface. -* `showSpotterLimitations` + -Shows functional limitations of Spotter when set to `true` -* `hideSampleQuestions` + -Hides sample questions that appear on the default Spotter page. - -Action IDs for menu customization:: -Use the following action IDs in the `disabledActions`, `visibleActions`, or `hiddenActions` array to disable, show, or hide menu actions and elements in the embedded Spotter interface: - -* `Action.PreviewDataSpotter` + -The *Preview data* button on the Spotter conversation panel. -* `Action.ResetSpotterChat` + -The *Reset* button on the Spotter conversation panel. -* `Action.SpotterFeedback` + -The feedback widget on Spotter-generated charts. -* `Action.EditPreviousPrompt` + -The edit icon on the prompt panel. -The Prompt panel appears after Spotter generates a response to a user query. -* `Action.DeletePreviousPrompt` + -The delete icon on the prompt panel. - -//// -* `Action.EditTokens` + -The option to edit tokens on a Spotter-generated chart or table. -//// -CSS variables:: - -The following new CSS variables are available for Spotter interface customization: - -* `--ts-var-spotter-input-background` -* `--ts-var-spotter-prompt-background` - -For more information about Spotter customization, see xref:embed-spotter.adoc#SpotterCSS[Customize styles]. -|[tag greenBackground]#NEW FEATURE# a| - - -Configuration attributes:: - -* `hideIrrelevantChipsInLiveboardTabs` + -Hides filter chips on a Liveboard when set to `true`. - -* `isLiveboardCompactHeaderEnabled` + -Enables the compact Liveboard header feature when set to `true`. - -Action IDs:: -Use the following action IDs in the `disabledActions`, `visibleActions`, or `hiddenActions` array to disable, show, or hide menu actions on an embedded Liveboard: - -* `Action.DisableChipReorder` + -ID for the action that disables filter chip reordering. -* `Action.ChangeFilterVisibilityInTab` - -|==== - -== Version 1.35.0, December 2024 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| -The SDK now provides the `isUnifiedSearchExperienceEnabled` setting to customize the Search experience on ThoughtSpot Home page for embedding application users: - -* When set to `true`, the split search experience is disabled and the Search bar on the Home page functions as Natural Language Search interface -* When set to `false`, the split search experience is enabled and object Search is set as the default Home page search experience. - -For more information, see xref:full-app-customize.adoc#_search_components[Search interface on the Home page in full application embedding]. - -|[tag greenBackground]#NEW FEATURE# a| The `overrideOrgId` parameter in the SDK provides the ability to override Org context for embedding application users. This parameter allows users authenticated to an Org to temporarily view content from another Org. Before specifying the Org ID for override, make sure the Per Org URL feature is enabled on your ThoughtSpot instance. To enable Per Org URL on your instance, contact ThoughtSpot Support. -|==== - -== Version 1.34.0, November 2024 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| You can now embed the following ThoughtSpot Spotter components in your app: - -* `SpotterEmbed` + -Embeds Spotter conversation interface in your app -* `SpotterAgentEmbed` + -Creates a conversation component without the body, which can be integrated into chatbots or other conversational apps. - -For more information, see xref:embed-spotter.adoc[Embed Spotter] and xref:spotter-in-custom-chatbot.adoc[Integrate Spotter into your chatbot]. - -|[tag greenBackground]#NEW FEATURE# a|The following parameters and enumerations are available for customizing Liveboard experience: - -* `showLiveboardVerifiedBadge` + -Shows or hides the Liveboard verified badge. Available if the Liveboard compact header feature is enabled. -* `showLiveboardReverifyBanner` + -Shows or hides the re-verify banner. Available if the Liveboard compact header feature is enabled. -* `Action.KPIAnalysisCTA` + -Action ID to show, hide, or disable the **Analyze CTA** action on a KPI chart. - -|[tag greenBackground]#NEW FEATURE# |You can now use the `HostEvent.GetIframeUrl` to get the iframe src URL from the Visual Embed Playground. If you are embedding ThoughtSpot in apps like Salesforce and Sharepoint without the SDK, use this event to generate the iframe URL. - -|[tag greenBackground]#NEW FEATURE# a|The following parameters are available for customizing Search experience: - -* `collapseDataPanel` -Minimizes the data panel view. Users can click the data panel header any time to expand the panel. -* `collapseSearchBar` -Sets the initial state of the search bar when embedding a saved Answer. - -|[tag greenBackground]#NEW FEATURE# a| The following settings are available for customizing the new home page and navigation experience in full app embedding: - -* `HomeLeftNavItem.LiveboardSchedules` + -The Liveboard schedules menu on the left navigation panel. - -Action enumerations:: - -* `Action.EditScheduleHomepage` + -To show, disable, or hide the *Edit* action on the *Liveboard schedules* page -* `Action.PauseScheduleHomepage` + -To show, disable, or hide the *Pause* action on the *Liveboard schedules* page -* `Action.ViewScheduleRunHomepage` + -To show, disable, or hide the *View run history* action on the *Liveboard schedules* page -* `Action.DeleteScheduleHomepage` + -To show, disable, or hide the *Delete* action on the *Liveboard schedules* page -* `Action.UnsubscribeScheduleHomepage` + -To show, disable, or hide the *Unsubscribe* action on the *Liveboard schedules* page -|==== - -== Version 1.33.x, October 2024 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| You can now customize the search experience for the embedded ThoughtSpot **Home** page using `homePageSearchBarMode`. By default, the **Home** page includes the Object Search bar, which allows finding popular Liveboards and Answers. - -You can set the `homePageSearchBarMode` property to one of the following options: - -** `aiAnswer` + -Displays the search bar for Natural Language Search. -** `none` -Hides the Search bar on the **Home** page. Note that it only hides the Search bar on the **Home** page and doesn't affect the Object Search bar visibility on the top navigation bar. -** `objectSearch` (default) + -Displays Object Search bar on the **Home** page. -|[tag greenBackground]#NEW FEATURE# a|The SDK now allows you to set the focus on the Search bar or outside the Search bar when rendering the embedded Search page. Use the `focusSearchBarOnRender` property to set the position of the cursor focus. -|[tag greenBackground]#NEW FEATURE# a| The SDK includes the following Event and Action enumeration members: - -Events:: - -* `EmbedEvent.OnBeforeGetVizDataIntercept` + -Developers can emit this event to intercept search execution, allow or restrict certain queries, and show an error message with custom text for restricted queries. To allow the embedded page to emit this event, you must set the `isOnBeforeGetVizDataInterceptEnabled` attribute to `true`. - -* `EmbedEvent.ParameterChanged` + -Emitted when a Parameter is changed on a saved Answer or Liveboard. - -Actions:: - -* `Action.ManageTags` + -Use this action enumeration to disable, show, or hide the **Manage tags** button on the Liveboards and Answers pages. -|==== - -== Version 1.32.x, August 2024 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| The following new action enumerations are available in this version: + - -* `Action.CreateLiveboard` for the *Create Liveboard* menu action on the Liveboards lists page. + -* `Action.SyncToTeams` for the **Sync to Teams** menu action on Liveboard visualizations. -* `Action.SyncToSlack` for the **Sync to Slack** action on Liveboard visualizations. -* `Action.AddQuerySet` for the **Add Query Set** action on the data panel (new experience) of the Search page. -* `Action.AddColumnSet` for the **Add Column Set** action on the data panel (new experience) of the Search page. -* `Action.AddDataPanelObjects` for the **Add** menu that includes sub-menu options such as Formulas, Parameters, Query set, and Column set actions. -* `Action.OrganiseFavourites` for the **Organize** action above the Favorites panel on the modular Homepage (New experience) -For more information, see xref:Action.adoc[Actions]. -|[tag greenBackground]#NEW FEATURE#| Developers can now use the `disableRedirectionLinksInNewTab` parameter to disable links and redirection of links in the embedded view. -|[tag greenBackground]#NEW FEATURE# a|You can now enable `enable2ColumnLayout` on a Liveboard to adjust the page view according to the width and resolution of users' devices. -|| -|==== - -== Version 1.31.x, July 2024 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| Runtime filters + - -* `NOT_IN` operator for Runtime filters. -For more information, see xref:runtime-filters.adoc#runtimeFilterOp[Runtime filters]. -* `excludeRuntimeParametersfromURL` parameter to exclude or remove runtimeParameters from the URL. -|[tag greenBackground]#NEW FEATURE# |For performance optimization, developers can choose to load embedded views in a lightweight V2 shell by setting `enableV2Shell_experimental` to `true`. -|==== - -== Version 1.30.0, June 2024 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| **CSS variables for new homepage experience** - -* `--ts-var-home-watchlist-selected-text-color` + -* `--ts-var-home-card-color` + -* `--ts-var-home-favorite-suggestion-card-text-color` + -* `--ts-var-home-favorite-suggestion-card-background` + -* `--ts-var-home-favorite-suggestion-card-icon-color` - -For more information, see xref:css-customization.adoc#_homepage_modules_new_experience_mode[CSS variables and overrides]. -|==== - -== Version 1.29.0, May 2024 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| **Ask Sage** - -With Ask Sage [beta betaBackground]^Beta^ embedded application users can ask follow-up questions on a visualization generated from a Natural Language Search query, converse with AI analyst, and refine results. To enable this feature, set `enableAskSage` to `true`. - -Action enumeration:: -To show, hide, or disable Ask Sage on a visualization, add `Action.AskAi`. For example, -+ -[source,JavaScript] ----- -hiddenActions: [Action.AskAi] ----- - -Events:: -* `HostEvent.AskSage` + -Triggers the **Ask Sage** action on a Liveboard visualization. -* `EmbedEvent.AskSageInit` + -Emits when the **Ask Sage** action is initialized. -* `HostEvent.GetParameters` + -Triggers a fetch action to get runtime Parameters. -* `HostEvent.UpdateParameters` + -Updates runtime Parameters -* `HostEvent.ResetLiveboardPersonalisedView` + -Resets a personalized Liveboard view. -* `HostEvent.UpdateCrossFilter` + -Updates cross filters applied on a Liveboard. -|==== - -== Version 1.28.x, April 2024 - -[width="100%" cols="1,4"] -|===== -|[tag greenBackground]#NEW FEATURE# a| The SDK includes the following new enumeration members in v1.28.0: - -** `Action.VerifiedLiveboard` + -Can be used to show or hide the *Verified Liveboard* banner. -|[tag greenBackground]#NEW FEATURE# a| To access the new Home page and global navigation experience in the full application embedding, you can use the `modularHomeExperience` property in the SDK. The modular homepage experience is turned off by default and is available as an Early Access feature in 9.12.5.cl release. When `modularHomeExperience` is set to `true`, you can use the following parameters in the SDK to control the application experience: - -* `hiddenhomeleftnavitems` -* `hiddenhomepagemodules` -* `hideapplicationswitcher` -* `hidehomepageleftnav` -* `hideorgswitcher` -* `reorderedhomepagemodules` -* `HomeLeftNavItem` - -For more information, see xref:full-app-customize.adoc[Customize full application embedding] and xref:AppViewConfig.adoc[AppViewConfig]. -|[tag greenBackground]#NEW FEATURE# a| The following embed event is available from the v1.28.0 onwards: - -`EmbedEvent.Rename` + -Emits when an embedded Liveboard or visualization is renamed. -|[tag greenBackground]#NEW FEATURE# a| TML actions - -The following TML menu actions are now grouped under the **TML** sub-menu of the **More** image:./images/icon-more-10px.png[the more options menu] menu on Answer page. - -* Export TML -* Edit TML -* Update TML - -To show, hide, or disable these actions in the embedded mode, use the following format: - -[source,JavaScript] ----- - // to show the TML menu and its sub-menu options -visibleActions: [Action.TML, Action.ExportTML, Action.EditTML] ----- - -[source,JavaScript] ----- - // to hide all TML actions -hiddenActions: [Action.TML] ----- - -[source,JavaScript] ----- - // to disable all TML actions -disabledActions: [Action.TML] ----- -|[tag greenBackground]#NEW FEATURE# | You can now reset authentication token and fetch a new token for new authentication requests. -For more information, see link:https://developers.thoughtspot.com/docs/Function_resetCachedAuthToken[resetCachedAuthToken]. - -|[tag greenBackground]#NEW FEATURE#| You can now override the default number, date, and currency format defined by your locale settings. To override the default settings, use the following parameters: - -* `numberFormatLocale` + -* `dateFormatLocale` + -* `currencyFormat` - -For more information, see xref:locale-setting.adoc#_set_locale_in_the_sdk[Customize locale]. - -|[tag greenBackground]#NEW FEATURE# |Tokenized fetch + -The SDK now provides a fetch wrapper that adds the authentication token to the API requests. -For more information, see link:https://developers.thoughtspot.com/docs/Function_tokenizedFetch#_tokenizedfetch[tokenizedFetch]. -|===== - -== Version 1.27.x, March 2024 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| The following action enumeration members are available from v1.27.9 and v1.27.10: - -* `Action.AIHighlights` -* `Action.AddToWatchlist` -* `Action.RemoveFromWatchlist` -* `Action.CopyKpiLink` - -For more information, see xref:Action.adoc[Action]. -| [tag greenBackground]#NEW FEATURE# a| You can now use `HostEvent.GetAnswerSession` to get Answer session data for a Search Answer or Liveboard Visualization in the embedded view. -|==== - -== Version 1.27.0, January 2024 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a|The `SageEmbed` package is now available on all clusters. You can use this SDK package to embed Natural Language Search capabilities and assist users with AI-suggested queries and AI-generated answers. This SDK package also allows you to customize the Natural Language Search experience in the embedded view. - -For a complete list of methods, functions, interface objects, and properties, see the following pages: + - -* xref:SageEmbed.adoc[SageEmbed] -* xref:SageViewConfig.adoc[SageViewConfig] - -|[tag orangeBackground]#MODIFIED# a| The `HostEvent.DrillDown` now supports the `vizId` parameter to trigger a drill-down action on a specific visualization of a Liveboard. -For more information, see xref:HostEvent.adoc#_drilldown[DrillDown]. -|[tag greenBackground]#NEW FEATURE# a| The new version of the SDK introduces the following new enumeration members: - -* Host Events -** `HostEvent.UpdateSageQuery` + -Updates the search query string for Natural Language Search operations. -* Embed Events -** `EmbedEvent.CreateConnection` + -Emitted when a user creates a new data connection on the **Data** page. -** `EmbedEvent.CreateWorksheet` + -Emitted when a user creates a new Worksheet. -|==== - -== Version 1.26.0, November 2023 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| The SDK provides `AnswerService` class to trigger the answer service with a custom action payload. -You can use this service to run GraphQL queries in the context of the Answer with a custom action trigger. For more information, see link:https://developers.thoughtspot.com/docs/Class_AnswerService[AnswerService]. Recommended ThoughtSpot application version is 9.10.0.cl. - -|[tag greenBackground]#NEW FEATURE# a|The following object properties and feature flags are introduced in the `LiveboardEmbed` and `AppEmbed` SDK packages: - -* `showLiveboardDescription` + -Shows the Liveboard description text when set to `true` -* `showLiveboardTitle` + -Shows the Liveboard title when set to `true` -* `isLiveboardHeaderSticky` + -Sets Liveboard header bar as a fixed element when set to `true` -* `hideLiveboardHeader` + -Hides the Liveboard header when set to `true` -* `hiddenTabs` + -Hides the specified tabs from the Liveboard page -* `visibleTabs` + -Displays the specified tabs on the Liveboard page - -|[tag greenBackground]#NEW FEATURE# |You can now enable the new data panel experience by setting `dataPanelV2` to `true` in the SDK when embedding ThoughtSpot Search. The new data panel experience is turned off by default on embedded ThoughtSpot instances. - -|[tag greenBackground]#NEW FEATURE# a|The new version of the SDK supports the following events: - -Embed events:: -* `EmbedEvent.hiddenTabs` -* `EmbedEvent.visibleTabs` -* `EmbedEvent.UpdatePersonalisedView` -* `EmbedEvent.SavePersonalisedView` -* `EmbedEvent.ResetLiveboard` -* `EmbedEvent.DeletePersonalisedView` -* `EmbedEvent.SageWorksheetUpdated` -* `EmbedEvent.SageEmbedQuery` -+ -For more information, see xref:EmbedEvent.adoc[EmbedEvent]. - -Host events:: - -* `HostEvent.GetTabs` -* `HostEvent.SetVisibleTabs` -* `HostEvent.SetHiddenTabs` -* `HostEvent.GetAnswerSession` -* `HostEvent.UpdateSageQuery` -+ -For more information, see xref:HostEvent.adoc[HostEvent]. - -|[tag greenBackground]#NEW FEATURE# a| The SDK introduces the following action enumeration members: - -* `Action.AddTab` + -Show, disable, or hide the **Add Tab** action on a Liveboard. -* `Action.PersonalisedViewsDropdown` + -Show, disable, or hide the Liveboard views saved by a user. -* `Action.LiveboardUsers` + -Show, disable, or hide Liveboard users. -* `Action.SageAnswerFeedback` -Show, disable, or hide the feedback widget on AI-generated Answer page. -* `Action.EditSageAnswer` -Show, disable, or hide the **Edit** action on the AI-generated Answer page. - -For more information, see xref:Action.adoc[Actions]. -|==== - -== Version 1.25.0, October 2023 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# | The SDK now supports runtime Parameter overrides on Liveboards and Answers. -For more information, see xref:runtime-parameters.adoc#_apply_parameter_overrides_using_visual_embed_sdk[Runtime Parameter overrides]. - -|[tag greenBackground]#NEW FEATURE# a| The SDK introduces the following action enumeration members: - -* `Action.RenameModalTitleDescription` -* `Action.EnableContextualChangeAnalysis` -* `Action.RequestVerification` -* `Action.AddTab` - -For more information, see xref:Action.adoc[Actions]. -|==== - -== Version 1.24.0, September 2023 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| ThoughtSpot now provides the `SageEmbed` package to embed the ThoughtSpot Search page with Sage features such as natural language search and AI-suggested search examples. This feature is in beta and not available in the Visual Embed Playground. -|[tag greenBackground]#NEW FEATURE# a| The `HostEvent.SetActiveTab` event in the upcoming version of the SDK allows you to set a tab as an active tab on a Liveboard. -|==== - -== Version 1.23.0, August 2023 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| The SDK supports the following performance optimization enhancements: + - -* Ability to pre-render a generic instance of the ThoughtSpot component using the `prerenderGeneric` attribute. The generic instance uses the default host and flags and can be rendered in the background to improve application response. -* Ability to use an iFrame from a pre-rendered iFrame pool using the `usePrerenderedIfAvailable` attribute. -|==== - -//// -|[tag greenBackground]#NEW FEATURE# a| New events for Liveboard filters + - -* `EmbedEvent.FilterChanged` + -* `HostEvent.GetFilters` + -* `HostEvent.UpdateFilters` -//// - -== Version 1.22.0, June 2023 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| The new version of the SDK introduces the `TrustedAuthTokenCookieless` `authType` property to allow Cookieless embedding. The Cookieless authentication method allows using a bearer token to identify the signed-in user instead of session cookies. - -For more information, see xref:embed-authentication.adoc#_cookieless_authentication[Cookieless authentication]. - -|[tag greenBackground]#NEW FEATURE# a|The new version of the SDK allows you to block user access to the non-embedded instance of the ThoughtSpot application. In full app embed deployments, you can use the `blockNonEmbedFullAppAccess` property in the SDK to restrict or allow your application users from accessing ThoughtSpot pages in the non-embed mode. - -For more information, see xref:security-settings.adoc#_block_access_to_non_embedded_thoughtspot_pages[Block access to non-embedded ThoughtSpot pages]. - -|==== - -//// -|[tag greenBackground]#NEW FEATURE# a| The SDK supports the following performance optimization enhancements: + - -* Ability to pre-render a generic instance of the ThoughtSpot component using the `prerenderGeneric` attribute. The generic instance uses the default host and flags and can be rendered in the background to improve application response. -* Ability to use an iFrame from a pre-rendered iFrame pool using the `usePrerenderedIfAvailable` attribute. -//// - -== Version 1.21.0, May 2023 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a|The new version of the SDK introduces the following action enumeration members: - -* `Action.AxisMenuAggregate` -* `Action.AxisMenuConditionalFormat` -* `Action.AxisMenuEdit` -* `Action.AxisMenuFilter` -* `Action.AxisMenuGroup` -* `Action.AxisMenuNumberFormat` -* `Action.AxisMenuPosition` -* `Action.AxisMenuRemove` -* `Action.AxisMenuRename` -* `Action.AxisMenuSort` -* `Action.AxisMenuTextWrapping` -* `Action.AxisMenuTimeBucket` -* `Action.CrossFilter` -* `Action.RemoveCrossFilter` - -For more information, see xref:embed-action-ref.adoc[Action reference]. - -|[tag greenBackground]#NEW FEATURE# a| The SDK introduces the following events: - -* `HostEvent.AddColumns` -* `HostEvent.OpenFilter` -* `HostEvent.RemoveColumn` -* `HostEvent.ResetSearch` -* `EmbedEvent.CrossFilterChanged` -* `EmbedEvent.DownloadAsPng` -* `EmbedEvent.VizPointRightClick` - -For more information, see xref:embed-events.adoc[Events]. - -|[tag redBackground]#DEPRECATED# a| - -The following events are deprecated from version 1.21.0 onwards. - -* `HostEvent.Download` + -* `EmbedEvent.Download` - -You can use the `DownloadAsPng`, `DownloadAsXlsx`, `DownloadAsCsv` and `DownloadAsPdf` events for download actions. - -For more information, see xref:embed-events.adoc[Events reference]. -|[tag orangeBackground]#MODIFIED# a| - -Events:: -The SDK supports omitting or executing a search query in xref:HostEvent.adoc#_search[`HostEvent.Search`]. -Actions:: -Use the following action enumeration members instead of `Action.Download` to show, hide, or disable the *Download* menu action on an embedded Liveboard, visualization, or Answer: -+ -* `Action.DownloadAsCsv` -* `Action.DownloadAsPdf` -* `Action.DownloadAsXlsx` -* `Action.DownloadAsPng` - -To disable or hide download actions, you can use `Action.Download` in the `disabledActions` and `hiddenActions` arrays respectively. However, if you are using the `visibleActions` array to show or hide actions on a visualization or Answer, include the following download action enumerations along with `Action.Download` in the array: + - -** `Action.DownloadAsCsv` + -** `Action.DownloadAsPdf` + -** `Action.DownloadAsXlsx` + -** `Action.DownloadAsPng` - -|[tag greenBackground]#NEW FEATURE# a| The SDK includes new attributes to customize the experience for embedded app users: - -* `linkOverride` -+ -Allows overriding the *Open in new tab* link on embedded pages. - -* `contextMenuTrigger` -+ -Allows triggering contextual menu on the Liveboard visualizations and Answers from left-click to right-click. - -* `hideSearchBar` -+ -Allows hiding the Search bar on the embedded Search page. -|[tag greenBackground]#NEW FEATURE# | The SDK now allows setting the loading preference for embedded iFrames. -For performance optimization, you can set the `loading` attribute to `lazy` in the `FrameParams` property. -|==== - -== Version 1.20.0, April 2023 - -[width="100%" cols="1,4"] -|==== -|[tag redBackground]#DEPRECATED# a|The `dataSources` property in `SearchEmbed` and `SearchBarEmbed` is deprecated and replaced with the `dataSource` attribute. The SDK supports searching from a single data source only. -|[tag greenBackground]#NEW FEATURE# a|The embed SDK packages now include the `insertAsSibling` property. This attribute can be used to insert the embedded object as a sibling to the element inside the target container. -|==== - -== Version 1.19.0, February 2023 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a|The `customCSS` property in the `customizations` object supports new variables to customize the styles for dialogs, search bar, search navigation and search suggestions panels. -For more information, see xref:css-customization.adoc[Customize CSS]. -|[tag redBackground]#BREAKING CHANGE# a|The new Liveboard experience mode introduces changes to the data format of the JSON response payload triggered by callback custom actions. For example, the `reportBookData`, and `vizData` attributes are modified, and the custom action `id` now is part of the data attribute. These changes may break your current custom action event handlers. For interoperability, we recommend adding the data attribute to `payload` in your code as shown in the example here: - -[source,JavaScript] ----- -liveboardEmbed.on(EmbedEvent.CustomAction, payload => { - if (payload.id === "callback-action-id" \|\| payload.data.id === "callback-action-id") { - console.log('Custom Action event:', payload.data); - } -}) ----- - -You may also want to update the data classes in your scripts to process the JSON response payload and handle complex data. For more information, see xref:custom-actions-callback.adoc#_define_functions_and_classes_to_handle_liveboard_data[Callback custom actions]. - -|[tag greenBackground]#NEW FEATURE# a|The new version of the SDK introduces the following Host events: - -* `HostEvent.Delete` -* `HostEvent.Download` -* `HostEvent.DownloadAsCsv` -* `HostEvent.DownloadAsXlsx` -* `HostEvent.ManagePipelines` -* `HostEvent.Save` -* `HostEvent.Share` -* `HostEvent.ShowUnderlyingData` -* `HostEvent.SpotIQAnalyze` -* `HostEvent.SyncToOtherApps` -* `HostEvent.SyncToSheets` - -For more information, see xref:events-hostEvents.adoc[Host events]. - -|[tag redBackground]#DEPRECATED# a|The `noRedirect` property in the SDK is deprecated and replaced with the `inPopup` attribute. When set to `true`, the `inPopup` attribute allows the SAML SSO authentication flow in a pop-up window. - -For more information, see xref:embed-authentication.adoc#_saml_redirection[SAML Redirection]. -|==== - -== Version 1.18.0, January 2023 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a|The new version of the SDK provides the `SearchBarEmbed` JavaScript package to embed only the ThoughtSpot Search bar in your app. + - -For more information, see xref:embed-searchbar.adoc[Embed ThoughtSpot search bar]. - -|[tag greenBackground]#NEW FEATURE# a|The `customCSS` property in the `customizations` object supports new variables to customize the UI elements on Liveboard, visualization, and Answer pages. You can also use these variables to define custom styles in the CSS file. + -For more information, see xref:css-customization.adoc[Customize CSS]. -|[tag greenBackground]#NEW FEATURE# |The new version of the SDK allows fetching TML objects via `GetTML` host event. This event is triggered when a user clicks on the *Show underlying data* action on a Liveboard visualization or Answer page. + - -For more information, see xref:HostEvent.adoc#_gettml[GetTML]. - -|[tag greenBackground]#NEW FEATURE# a| The new version of the SDK introduces the following enums in the `Action` object: - -* `Action.SyncToOtherApps` + -* `Action.SyncToSheets` + -* `Action.ManagePipelines` + - -You can use these enums to show, hide, or disable *Sync to sheets*, *Sync to other apps*, and *Manage pipelines* menu actions on a Liveboard visualization or Answer. - -For more information, see xref:embed-action-ref.adoc[Actions]. -|==== - -== Version 1.17.1, December 2022 - -Bug fixes to the trusted authentication feature. - -== Version 1.17.0, November 2022 - -The new version of the SDK introduces several new features and enhancements. -[width="100%" cols="1,4"] -|==== -|[tag orangeBackground]#MODIFIED# a|The `AuthType` property is modified and supports new enums. + - -* `AuthType.SAML` is renamed as `AuthType.SAMLRedirect` + -* `AuthType.OIDC` is renamed as `AuthType.OIDCRedirect` + -* `AuthType.AuthServer` is renamed to `AuthType.TrustedAuthToken` + -This enhancement does not introduce any breaking changes to your current implementation. -|[tag greenBackground]#NEW FEATURE# a|To use your current SAML or OIDC authentication setup and redirect users to the IdP for authentication within the embedded iFrame, you can now use `AuthType.EmbeddedSSO`. + -For more information, see xref:embed-authentication.adoc[Authentication]. -|[tag greenBackground]#NEW FEATURE#| -The `customizations` object in the SDK allows you to specify a custom CSS URL. You can also use this object to define CSS variables directly in the `init` code. + -For more information, see xref:css-customization.adoc[Customize CSS]. -|==== - -== Version 1.16.0, October 2022 - -The new version of the SDK includes bug fixes and improvements to the new Liveboard experience. - -== Version 1.15.1, September 2022 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE#| -The `prefetch` method now supports the `url` and `prefetchFeatures` parameters. You can use these parameters to call the prefetch method before `init` and prefetch static resources on application load. + -For more information, see xref:prefetch-and-cache.adoc[Prefetch static resources]. -|==== - -== Version 1.15.0, September 2022 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE#| -For embedded instances with the new Liveboard experience, the Visual Embed SDK provides the `activeTabId` attribute, using which you can set a Liveboard tab as an active tab. - -For more information, see xref:embed-pinboard.adoc#_liveboard_tabs[Customize Liveboard tabs]. - -|[tag greenBackground]#NEW FEATURE# a|The new version of the SDK supports firing events for Liveboard menu actions from the host application. The SDK introduces the following host event enumeration members for Liveboard objects: - -* CopyLink -* CreateMonitor -* DownloadAsPdf -* Edit -* EditTML -* Explore -* ExportTML -* LiveboardInfo -* MakeACopy -* ManageMonitor -* Pin -* Present -* Remove -* Schedule -* SchedulesList -* UpdateTML - -For more information, see xref:events-hostEvents.adoc[Events reference]. -|==== - -== Version 1.14.0, August 2022 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE#| -The Visual Embed SDK now includes the `liveboardV2` attribute in the `LiveboardEmbed` package to allow developers to enable the new Liveboard experience on their embedded ThoughtSpot instance. + -For more information, see xref:embed-pinboard.adoc[Embed a Liveboard]. -|[tag orangeBackground]#MODIFIED#|If trusted authentication is enabled, the SDK makes a `POST` API call to get a login token and log the user into ThoughtSpot. -The earlier versions of the SDK supported only `GET` API requests. For more information, see xref:embed-authentication.adoc#_configure_token_based_authentication_method_in_visual_embed_sdk[Configure token-based authentication method in Visual Embed SDK]. -|==== - -== Version 1.13.0, July 2022 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE#| -This version of Visual Embed SDK includes the `enableSearchAssist` attribute, using which you can turn on the Search Assist feature on an embedded instance. -|[tag greenBackground]#NEW FEATURE#| The new version of SDK introduces the `AuthType.SAML` enum for SAML-based SSO authentication. Note that `AuthType.SAML` replaces the `AuthType.SSO` enum, which is deprecated in the v1.13.0 version of the SDK. + -For more information, see xref:embed-authentication.adoc#saml-sso-embed[Authentication]. -|[tag redBackground]#DEPRECATED#| The `AuthType.SSO` enum is deprecated in v1.13.0. ThoughtSpot recommends using `AuthType.SAML` for the SAML SSO authentication method. + -This change does not impact your current embed implementation with `AuthType.SSO`. -|[tag greenBackground]#NEW FEATURE#| The SDK includes the `getExportRequestForCurrentPinboard` event, which is triggered when a user tries to export a Liveboard in its current state. + -For more information, see xref:events-hostEvents.adoc[Events reference]. -|==== - -== Version 1.12.0, June 2022 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE#| -This version of Visual Embed SDK introduces the `navigate` host event, which is triggered when a user navigates to an application page without a page reload. - -For more information, see xref:events-hostEvents.adoc[Events reference]. -|[tag greenBackground]#NEW FEATURE# | The new `getThoughtSpotPostUrlParams` method fetches ThoughtSpot URL query parameters prefixed with `ts-`. -|==== - -== Version 1.11.2, June 2022 - -Bug fix for Typescript builds that affect Angular project configurations. - -== Version 1.11.1, May 2022 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE#| The SDK includes the action enum `ReportError`, using which you can turn off ThoughtSpot-specific error reporting. -|==== - -== Version 1.11.0, May 2022 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| The new version of SDK includes the following new events: - -* `ALL` -* `AnswerChartSwitcher` -* `AnswerDelete` -* `CopyAEdit` -* `CopyToClipboard` -* `Download` -* `DownloadAsPdf` -* `DownloadAsCsv` -* `DownloadAsXlsx` -* `DrillExclude` -* `DrillInclude` -* `EditTML` -* `ExportTML` -* `Monitor` -* `Pin` -* `Save` -* `SaveAsView` -* `Share` -* `ShowUnderlyingData` -* `SpotIQAnalyze` -* `UpdateTML` -* `VizPointClick` - -For more information about how to register and handle these events, see xref:embed-events.adoc[Events and app integration]. -|[tag greenBackground]#NEW FEATURE# a| The new version of SDK supports the `showAlerts` attribute, using which you can show or hide alerts and error messages in the embedded view. - -|[tag greenBackground]#NEW FEATURE# a| The `Action.CreateMonitor` enumeration is available in the SDK for embedded ThoughtSpot environments on which the *Monitor* feature is enabled. -For more information, see xref:embed-actions.adoc[Show or hide UI actions]. -|==== - -== Version 1.10.4, May 2022 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE#|The `detectCookieAccessSlow` parameter in the SDK allows your app to check if third-party cookies are enabled on the browser. This parameter is available only for trusted and `Basic` authentication types. -|==== -== Version 1.10.3, May 2022 - -Bug fix and improvements to the `logout` method. - -== Version 1.10.2, May 2022 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE#|Ability to configure `redirectPath` on the origin when using the SAMLRedirect `authType`. -|==== - -== Version 1.10.1, May 2022 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE#|You can now use the `logout` method to log out embed users. -|[tag orangeBackground]#MODIFIED# a| Note the following changes: + - -* You can now use the `loginFailedMessage` property on init to display the `Not logged in` message when a user login fails. You can customize this message by defining a custom text string in the `loginFailedMessage` attribute. -* The `init` method now returns an event emitter which can be used to listen to `AuthStatus` such as login failure, success, or user logout. -|==== - -== Version 1.10.0, April 2022 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| The `AddRemoveColumns` event is now available in the SDK. For more information, see xref:event-embedEvents.adoc[Events reference]. -|==== - -== Version 1.9.8, April 2022 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE#|The `pageId` attribute now allows you to set the **SpotIQ** page as the home tab of your embedded ThoughtSpot app. - -For more information, see xref:full-embed.adoc[Embed full application]. -|==== - -== Version 1.9.6 and 1.9.7, April 2022 - -Bug fixes and improvements - -== Version 1.9.5, April 2022 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE#|The `locale` attribute is now available in embed packages. You can use this attribute to set the locale or language of your embedded application view. -For more information, see xref:locale-setting.adoc[Set locale and display language]. -|==== - -== Version 1.9.4, April 2022 - -Bug fixes and improvements to React components. - -== Version 1.9.3, March 2022 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE#| The SDK now supports the `disableLoginRedirect` attribute to improve the login experience for your application users. When enabled, this attribute prevents your app from redirecting users to the login page when their session expires. + -You can use this attribute along with `autoLogin` to automatically authenticate and re-login a user. + -This feature is applicable to token-based authentication, that is, when the `AuthType` is set as `TrustedAuthToken` in the SDK. - -For more information, see xref:embed-authentication.adoc#trusted-auth-embed[Authentication]. -|==== - -== Version 1.9.2, March 2022 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE#| You can now trigger events on React components using the `useEmbedRef` hook. - -For more information, see xref:embed-ts-react-app.adoc[Embed ThoughtSpot in a React app]. -|==== - -== Version 1.9.1, March 2022 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE#| The SDK now includes the `visibleVizs` attribute in the `LiveboardEmbed` package. This attribute allows you to add visualization GUIDs that you want to display when a Liveboard renders for the first time. - -For more information, see xref:embed-pinboard.adoc[Embed a Liveboard]. - -|[tag greenBackground]#NEW FEATURE# a| The following events are now available in the SDK: + - -* `LiveboardRendered` (EmbedEvent) - -For more information, see xref:event-embedEvents.adoc[Events reference]. -|==== - -== Version 1.9.0, March 2022 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| The SDK now includes the following new enumerations for UI actions: - -* `Action.AnswerDelete` + -* `Action.AnswerChartSwitcher` + -* `Action.AddToFavorites` + -* `Action.EditDetails` + - -For more information, see xref:embed-actions.adoc#standard-actions[Show or hide UI actions]. - -|[tag greenBackground]#NEW FEATURE# a| The SDK now supports the `UpdateRuntimeFilters` host event. For more information, see xref:events-hostEvents.adoc[Events reference]. -|==== - -== Version 1.8.x, February 2022 - -[width="100%" cols="1,4"] -|==== -|[tag redBackground]#BREAKING CHANGE# | The `autoLogin` attribute is now set as `false` by default. This attribute is used in the `init` method to automatically re-login a user when a session expires. -|[tag greenBackground]#NEW FEATURE# | The `init` method now returns the `authPromise` which resolves when a user authentication is completed. -|==== - - -== Version 1.7.0, January 2022 - -[width="100%" cols="1,4"] -|==== -| -[tag greenBackground]#NEW FEATURE# |+++
OIDC AuthType
+++ - -The SDK supports the `OIDC` `authType` in `init` calls. If you want your application users to authenticate to an OpenID provider and use their SSO credentials to access the embedded ThoughtSpot content, you can enable the `OIDC` authentication type in the SDK. - -For more information, see xref:embed-authentication.adoc#oidc-auth[Authentication and security attributes]. -|[tag greenBackground]#NEW FEATURE# a|+++
Embed events
+++ - -The SDK includes the following new event: - -* `RouteChange` - -For more information, see xref:event-embedEvents.adoc[Events reference]. - -|==== - -== Version 1.6.x, November 2021 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a|+++
Visible actions
+++ - -You can now configure a set of ThoughtSpot UI actions as visible actions and display these actions in the embedded UI. If your embedded instance requires only a few actions, you can use the `visibleActions` API to show only these actions in the embedded ThoughtSpot UI. - -For more information, see xref:embed-actions.adoc[Show or hide UI actions]. - -|[tag orangeBackground]#MODIFIED# | +++
Terminology changes
+++ - -The SDK library and object parameter names are modified to rebrand pinboards as Liveboards. For a complete list of changes, see xref:terminology-update.adoc#sdk-changes[Terminology changes]. - -|[tag greenBackground]#NEW FEATURE# a|+++
Embed events
+++ - -The SDK supports the following new events: - -* `DialogOpen` -* `DialogClose` - -For more information, see xref:event-embedEvents.adoc[Events reference]. -|==== - -== Version 1.5.0, October 2021 - -[width="100%" cols="1,4"] -|==== -|| -|[tag greenBackground]#NEW FEATURE# | +++
Render embedded objects in queue
+++ - -The SDK now supports rendering embedded objects in a queue. If you have multiple embedded objects, you can enable the `queueMultiRenders` parameter to queue your embedded objects and render them one after another. This feature helps in decreasing the load on the web browsers and improving your application loading experience. By default, this attribute is set to `false`. - -|[tag greenBackground]#NEW FEATURE# a|+++
Liveboard embed
+++ - -The `pinboardEmbed` package includes the `defaultHeight` attribute that sets a minimum height for embedded objects on a pinboard page, and the corresponding visualization pages that a user can navigate to. - -For more information, see xref:embed-search.adoc[Embed a pinboard]. - -|[tag greenBackground]#NEW FEATURE# a|+++
Embed events
+++ - -The SDK EmbedEvent library includes the following new events: - -* `VizPointDoubleClick` -* `Drilldown` -* `SetVisibleVizs` - -For more information, see xref:event-embedEvents.adoc[Events reference]. - -|==== - -== Version 1.4.0, September 2021 - -[width="100%" cols="1,4"] -|==== -|| -|[tag greenBackground]#NEW FEATURE# a|+++
+++Prefetch API+++
+++ - -The `prefetch` API fetches static resources from a given URL before your application loads. Web browsers can then cache the prefetched resources locally and serve them from a user's local disk. You can use this API to load the embedded objects faster and improve your application response time. - -For more information, see xref:prefetch-and-cache.adoc[Prefetch static resources]. - -|[tag greenBackground]#NEW FEATURE# a|+++
+++In-app page navigation+++
+++ - -The `navigateToPage` method in the SDK lets you provide quick and direct access to a specific pinboard, saved Answer, or an application page. You can add a custom menu action or button in your application UI that calls the `navigateToPage` method and leads your users to the page specified in the `path` parameter. - -For more information, see xref:page-navigation.adoc[Add a custom action for in-app navigation]. - -|[tag greenBackground]#NEW FEATURE# a|+++
+++Full application embedding+++
+++ - -The `appEmbed` SDK package includes the following new attributes: - -* The `disableProfileAndHelp` attribute to show or hide the `Help (?)` and the user profile menu in the navigation bar of your embedded app. - -* The `hideObjects` attribute to hide specific objects from a user's page view. - -For more information, see xref:full-embed.adoc[Embed full application]. - -|[tag greenBackground]#NEW FEATURE# |+++
+++Search embed +++
+++ - -The `searchEmbed` package includes the `forceTable` attribute that sets tabular view as the default format for presenting search data. You can set this attribute to `true` to force search results to appear in the table view. - -For more information, see xref:embed-search.adoc[Embed ThoughtSpot search]. - -|[tag redBackground]#REMOVED# | - -The `searchQuery` parameter is no longer supported and is removed from the `searchEmbed` SDK package. -|[tag greenBackground]#NEW FEATURE# a|+++
+++Embed events +++
+++ -The SDK EmbedEvent library includes the following events: - -* `QueryChanged` -* `AuthExpire` - -For more information, see xref:embed-events.adoc[Events and app integration]. -|==== - -== Version 1.3.0, August 2021 - -[width="100%" cols="1,4"] -|==== -|| -|[tag greenBackground]#NEW FEATURE# a| +++
searchOptions
+++ - -The `searchEmbed` SDK package introduces the `searchOptions` parameter for setting search tokens. The `searchOptions` parameter includes the following attributes: - -* `searchTokenString` -+ -A TML query string to define search tokens. - -* `executeSearch` -+ -When set to `true`, it executes search and shows the search results. - -For more information, see xref:embed-search.adoc#search-query[Embed ThoughtSpot search]. - -|[tag redBackground]#DEPRECATED# a| +++
searchQuery
+++ - -The `searchQuery` parameter in the `searchEmbed` SDK package is deprecated in the Visual Embed SDK version 1.3.1. Instead, you can use the `searchOptions` parameter to define the search token string. - -For more information about `searchOptions`, see xref:embed-search.adoc#search-query[Embed ThoughtSpot search]. - -|[tag greenBackground]#NEW FEATURE# a| +++
autoLogin
+++ - -The SDK now supports logging in users automatically after a user session has expired. - -For more information, see xref:embed-authentication.adoc#embed-session-sec[Embed user authentication]. - -|[tag greenBackground]#NEW FEATURE# a| +++
shouldEncodeUrlQueryParams
+++ - -You can now convert query parameters in the ThoughtSpot generated URLs to base64-encoded format. You can enable this attribute to secure your cluster from cross-site scripting attacks. -|[tag redBackground]#BREAKING CHANGE# a| +++
Data structure changes in custom action response payloads
+++ - -* The data structure passed in the custom action response for search now shows as `payload.data.embedAnswerData` instead of `payload.data.columnsAndData`. - -* The Answer payload for custom actions includes the following metadata: - -** `reportBookmetadata` -+ -Includes visualization metadata attributes such as description, object header metadata, author details, timestamp of the Answer creation, and modification. - -** user data -+ -Includes user information such as username, GUID of the user, and email address. - -To view a sample response payload, see xref:callback-response-payload.adoc#search-data-payload[Custom action response payload]. - -|[tag greenBackground]#NEW FEATURE# a| +++
preventPinboardFilterRemoval
+++ - -The `pinboardEmbed` SDK package now includes the `preventPinboardFilterRemoval` attribute. You can use this attribute to disable the filter removal action and thus prevent users from removing the filter chips added on a pinboard page. - -For more information, see xref:embed-pinboard.adoc[Embed a pinboard] and xref:embed-a-viz.adoc[Embed a visualization]. -|[tag greenBackground]#NEW FEATURE# a| +++
suppressNoCookieAccessAlert
+++ - -You can now set custom alerts for `noCookieAccess` events. By default, the SDK triggers a `noCookieAccess` event and generates an alert when a user's browser blocks third-party cookies. The `suppressNoCookieAccessAlert` allows you to disable this alert. - -|[tag greenBackground]#NEW FEATURE# a| +++
Support for fetching callback custom action payload in batches
+++ - -The Visual Embed SDK now supports processing data in batches for callback custom action responses. -The callback custom action event in the SDK package supports defining `batchSize` and `offset` values to paginate the Answer payload and send the records in batches. - -For more information, see xref:push-data-to-external-app.adoc#large-dataset[Callback custom action workflow]. -|==== - -== Version 1.2.0, June 2021 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a|+++
SAML authentication
+++ - -The Visual Embed SDK packages now include the `noRedirect` attribute as an optional parameter for the SAMLRedirect SSO `AuthType`. If you want to display the SAML authentication workflow in a pop-up window, instead of refreshing the application web page to direct users to the SAML login page, you can set the `noRedirect` attribute to `true`. - -For more information, see the instructions for embedding xref:full-embed.adoc[ThoughtSpot pages], xref:embed-search.adoc[search], xref:embed-pinboard.adoc[pinboard], and xref:embed-a-viz.adoc[visualizations]. - -|[tag greenBackground]#NEW FEATURE# a|+++
Pinboard actions
+++ -The *More* menu image:./images/icon-more-10px.png[the more options menu] in the embedded Pinboard page now shows the following actions for pinboard and visualizations. - -Pinboard:: -* Save -* Make a copy -* Add filters -* Configure filters -* Present -* Download as PDF -* Pinboard info -* Manage schedules - - -[NOTE] -Users with edit permissions can view and access the *Save*, *Add filters*, *Configure filters*, and *Manage schedules* actions. -|[tag greenBackground]#NEW FEATURE# a|+++
Visualization actions
+++ - -Visualizations on a pinboard: - -* Pin -* Download -* Edit -* Present -* Download as CSV -* Download as XLSX -* Download as PDF - -[NOTE] -Users with edit permissions can view and access the *Edit* action. The *Download as CSV*, *Download as XLSX*, and *Download as PDF* actions are available for table visualizations. The *Download* action is available for chart visualizations. - -|==== - -== Version 1.1.0, May 2021 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a|+++
NoCookieAccess event
+++ - -When a user accesses the embedded application from a web browser that has third-party cookies disabled, the Visual Embed SDK emits the `NoCookieAccess` event to notify the developer. Cookies are disabled by default in Safari. Users can enable third-party cookies in Safari’s Preferences setting page or use another web browser. -To know how to enable this setting by default on Safari for a ThoughtSpot embedded instance, contact ThoughtSpot Support. -|==== \ No newline at end of file From 3a06bdb2e5ee9805037547f19e5ce748cfecbfd2 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 17 Aug 2026 09:43:02 +0530 Subject: [PATCH 023/154] docs: add Spotter conversation sharing APIs section (aug.26.mt, SCAL-306173) --- modules/ROOT/pages/spotter-agent-apis.adoc | 1205 +++----------------- 1 file changed, 163 insertions(+), 1042 deletions(-) diff --git a/modules/ROOT/pages/spotter-agent-apis.adoc b/modules/ROOT/pages/spotter-agent-apis.adoc index 5ea2587af..58dcbf738 100644 --- a/modules/ROOT/pages/spotter-agent-apis.adoc +++ b/modules/ROOT/pages/spotter-agent-apis.adoc @@ -61,6 +61,18 @@ a| `POST /api/rest/2.0/ai/relevant-questions/` [beta betaBackground]^Beta^ + xref:spotter-agent-apis.adoc#_get_relevant_questions[Decomposes a user query] into relevant sub-questions. Guides users to explore data more deeply for a comprehensive analysis. + __Available on ThoughtSpot Cloud instances from 10.13.0.cl onwards__. +a| `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` [.version-badge.new]#New# + +xref:spotter-agent-apis.adoc#_sharing_spotter_conversations[Shares a saved Spotter conversation] with one or more users or groups. + +__Available on ThoughtSpot Cloud instances from 26.9.0.cl onwards.__ + +a| `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content` [.version-badge.new]#New# + +xref:spotter-agent-apis.adoc#_get_shared_content[Returns the shared content] of a Spotter conversation, including messages and associated answers. + +__Available on ThoughtSpot Cloud instances from 26.9.0.cl onwards.__ + +a| `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info` [.version-badge.new]#New# + +xref:spotter-agent-apis.adoc#_get_share_information[Returns sharing metadata] for a Spotter conversation — the list of principals it is shared with. + +__Available on ThoughtSpot Cloud instances from 26.9.0.cl onwards.__ + a| `POST /api/rest/2.0/ai/agent/converse/sse` [.version-badge.deprecated]#Deprecated# + Legacy API endpoint for streaming responses, including tokens and visualizations, for a specific conversation context. __Deprecated in 26.5.0.cl__. @@ -112,57 +124,31 @@ With AUTO_MODE for metadata context:: [source,cURL] ---- curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/create' \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/create' \ + -H 'Authorization: Bearer {access-token}' \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {AUTH_TOKEN}' \ --data-raw '{ "metadata_context": { "type": "AUTO_MODE" - }, - "conversation_settings": { - "enable_save_chat": true } }' ---- -For a single data source as the data context:: +With DATA_SOURCE for metadata context:: [source,cURL] ---- curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/create' \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/create' \ + -H 'Authorization: Bearer {access-token}' \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {AUTH_TOKEN}' \ --data-raw '{ "metadata_context": { "type": "DATA_SOURCE", "data_source_context": { - "data_source_identifier": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" - } - }, - "conversation_settings": {} -}' ----- - -For multi-data source context:: - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/create' \ - -H 'Accept: application/json' \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {AUTH_TOKEN}' \ - --data-raw '{ - "metadata_context": { - "type": "DATA_SOURCE", - "data_source_context": { - "data_source_identifiers": [ - "a1b2c3d4-e5f6-7890-abcd-ef1234567890", - "b2c3d4e5-f6a7-8901-bcde-f12345678901" - ] + "data_source_identifier": "" } }, "conversation_settings": { @@ -171,1122 +157,257 @@ curl -X POST \ }' ---- -=== API response - -If the API request is successful, the API returns the conversation ID and identifier in the response body. - -[source,JSON] ----- -{ - "conversation_id": "wwHQ5j8O8dQC", - "conversation_identifier": "wwHQ5j8O8dQC" -} ----- - -* `conversation_identifier` + -Use this for all subsequent message calls. -* `conversation_id` [.version-badge.deprecated]#Deprecated# + -Returns the same value as `conversation_identifier`. - == Send queries to a conversation session -To send queries to an ongoing conversation session with the Spotter agent and receive a response synchronously, use the `/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send` API endpoint. - -This API operation requires the conversation ID obtained from the conversation creation API endpoint (`/api/rest/2.0/ai/agent/conversation/create`). The user making the API request must have access to the conversation session. The API request body must include at least one message in natural language format. +The `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send` API endpoint sends a natural language query to an existing Spotter agent conversation and returns the complete response synchronously. === Request parameters -[width="100%" cols="2,2,4"] +[width="100%" cols="2,4"] [options='header'] |===== -|Parameter|Type| Description -|`conversation_identifier`|Path parameter|__String__. Required. Specify the conversation ID received from the xref:spotter-agent-apis.adoc#_create_a_conversation_session_with_spotter_agent[POST /api/rest/2.0/ai/agent/conversation/create] API call. -|`messages`|Form parameter|_Array of strings_. Required. Specify at least one query in natural language. For example, `total sales of jackets last month`. +|Form parameter| Description +|`message` | The natural language query to send to the Spotter agent. +|`conversation_identifier` | GUID of the existing conversation session. Pass this in the URL path. |===== - -//// -|`settings` |__Optional__. Defines additional parameters for the conversation context. You can set any of the following attributes as needed: - -* `enable_contextual_change_analysis` + -__Boolean__. When enabled, Spotter analyzes how the context changes over time, that is comparing results from different queries. -* `enable_natural_language_answer_generation` + -__Boolean__. Allows sending natural language queries to the conversation session. -* `enable_reasoning` + -__Boolean__. Allows Spotter to use reasoning for deep analysis and precise responses. -//// - -=== Request and response examples - -The following example sends a data comparison query to a conversation session. The conversation ID is specified in the request URL as a path parameter. +=== Example request [source,cURL] ---- curl -X POST \ --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {AUTH_TOKEN}' \ --data-raw '{ - "messages": [ - "Sales in 2025 vs 2024" - ] + "message": "What are the top 10 products by revenue?" }' ---- -If the request is successful, the API returns an array of objects in the response. The messages in the API response include the following parts: +== Send a query to agent and get streaming responses -[source,JSON] ----- -[ - { - "type": "text", - "text": "\n\nI'll compare sales between 2025 and 2024. First, let me get the dataset context.", - "metadata": {}, - "internal": {}, - "agent_context": "" - }, - { - "type": "text", - "text": "```json\n{\"dataset_name\":\"(Sample) Retail - Apparel\",\"columns\":[{\"name\":\"sales\",\"type\":\"MEASURE\"},{\"name\":\"date\",\"type\":\"ATTRIBUTE\"}]}\n```", - "metadata": {}, - "internal": {}, - "agent_context": "" - }, - { - "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", - "metadata": { - "output": "", - "worksheet_id": "cd252e5c-b552-49a8-821d-3eadaa049cca", - "chart_type": "KPI", - "interrupted": false, - "data_awareness_enabled": true - }, - "internal": {} - }, - { - "type": "text", - "text": "\n\nThe visualization shows year-over-year comparison. You can identify growth or decline trends.", - "metadata": {}, - "internal": {}, - "agent_context": "" - } -] ----- +The `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream` API endpoint sends a natural language query to an existing Spotter agent conversation and returns the response as a real-time Server-Sent Events (SSE) stream. -The following example sends a follow-up question to the same conversation session. +=== Example request [source,cURL] ---- curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send' \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: text/event-stream' \ -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {AUTH_TOKEN}' \ --data-raw '{ - "messages": [ - "Now break that down by product category" - ] + "message": "Show me monthly revenue trends" }' ---- -If the request is successful, the agent returns the response for the follow-up question: - -[source,JSON] ----- -[{ - "type": "text", - "text": "I'll add product category to the comparison.", - "metadata": {}, - "internal": {}, - "agent_context": "" - }, - { - "type": "answer", - "title": "Sales by Product Category: 2025 vs 2024", - "session_id": "9abc1234-0000-0000-0000-000000000005", - "gen_no": 3, - "sage_query": "[sales] [product category] [date] = '2025' vs [date] = '2024'", - "tml_tokens": ["[sales]", "[product category]", "[date] = '2025' vs [date] = '2024'"], - "formulas": [], - "parameters": [], - "subqueries": [], - "viz_suggestion": "", - "metadata": { - "chart_type": "BAR", - "worksheet_id": "cd252e5c-b552-49a8-821d-3eadaa049cca" - }, - "internal": {} - }] ----- - -In each response, the agent returns the following information: - -* `type` + -Type of the message, such as text, answer, or error. -* `text` + -Response message generated for the query. -* `metadata` + -Additional information based on the message type. For example, answer metadata, chart type, or the data source ID. -* `tml_tokens` + -Query string broken down as TML tokens. - -In case of errors, the response returns the error details: - -[source,JSON] ----- -[{ - "type": "error", - "message": "The conversation session has expired. Please create a new conversation.", - "code": "SESSION_EXPIRED" -}] ----- - +== Stop an in-progress agent response +The `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response` API endpoint stops an in-progress Spotter agent response. The conversation session remains active after the response stops. -//// -The following example shows the response text contents for the `answer` message type. +=== Example request -[source,JSON] +[source,cURL] ---- -[ - { - "id": "r24X7D99SROD", - "type": "answer", - "group_id": "o8dQ9SAWdtrL", - "metadata": { - "sage_query": "[sales] [item type] = [item type].'jackets'", - "session_id": "b321b404-cbf1-4905-9b0c-b93ad4eedf89", - "gen_no": 1, - "transaction_id": "6874259d-13b1-478c-83cb-b3ed52628850", - "generation_number": 1, - "warning_details": null, - "ambiguous_phrases": null, - "query_intent": null, - "assumptions": "You want to see the total sales amount for jackets item type.", - "tml_phrases": [ - "[sales]", - "[item type] = [item type].'jackets'" - ], - "cached": false, - "sub_queries": null, - "title": "Net sales of Jackets", - "worksheet_id": "cd252e5c-b552-49a8-821d-3eadaa049cca" - }, - "title": "Net sales of Jackets" - } -] +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + --data-raw '{}' ---- -The session ID and generation number serve as the data context for the Answer. You can use this information to create a new conversation session using `/api/rest/2.0/ai/agent/conversation/create`, or download the answer via the `/api/rest/2.0/report/answer` API endpoint. - - -* The tokens and TML phrases returned in the response can be used as inputs for the search data API call to get an Answer. -//// +== Get data source suggestions -== Send a query to agent and get streaming responses - -To send queries to an ongoing conversation session with Spotter agent and receive streaming responses, use the `/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream` API endpoint. This API endpoint uses the SSE protocol to deliver data incrementally in real time, rather than waiting for the entire response to be generated before sending it to the client. - -The `/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream` API can be used as an integrated tool for real-time streaming of conversational interactions between agents and the ThoughtSpot backend. - -=== Request parameters - -[width="100%" cols="2,4"] -[options='header'] -|===== -|Parameter| Description -|`conversation_identifier` |__String__. Specify the conversation ID received from the xref:spotter-agent-apis.adoc#_create_a_conversation_session_with_spotter_agent[POST /api/rest/2.0/ai/agent/conversation/create] API call. -|`messages`|_Array of strings_. Include at least one natural language query. For example, `Sales data for Jackets`, `Top performing products in the west coast`. -|===== +The `POST /api/rest/2.0/ai/data-source-suggestions` API endpoint returns a list of relevant data sources based on a query, helping users and agents choose the most appropriate data source for analytics. === Example request [source,cURL] ---- curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream' \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/data-source-suggestions' \ + -H 'Authorization: Bearer {access-token}' \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {AUTH_TOKEN}' \ --data-raw '{ - "conversation_identifier": "h2I_pTGaRQof", - "messages": [ - "Net sales of Jackets" - ] + "query": "revenue by region" }' ---- -=== API response - -If the API request is successful, the response includes a stream of events, each containing a partial or complete message from the AI agent, rather than a single JSON object. - -Each event is a simple text-based message in a specific format, `data: \n\n`; `\n\n` means that each message sent from the server to the client is prefixed with the `data:` keyword, followed by the actual payload (``), and ends with two newline characters (`\n\n`). +== Get relevant questions -The API uses this format so that the clients can reconstruct the AI-generated response as it streams in, chunk by chunk, and show the responses in real-time. In agentic workflows, the receiving client or agent listens to the SSE stream, parses each event, and assembles the full response for its users. +The `POST /api/rest/2.0/ai/relevant-questions/` API endpoint decomposes a user query into relevant sub-questions, helping users explore data more deeply for comprehensive analysis. -==== Example response -If the request is valid, the API returns SSE streams. Each line has the form `data: [{"type": "...", ...}]`, a JSON array of event objects. - -[source,JSON] ----- -data: [{"type":"ack","node_id":"aGxzcFVrtom8"}] - -data: [{"type":"conv_title","title":"Sales 2025 vs 2024","conv_id":"-XIi04l5rrof"}] - -data: [{"type":"notification","group_id":"cDEsAQbSnd3J","metadata":{"type":"thinking","tool_title":"Analyzing Sales Performance: 2025 vs 2024"},"code":"TOOL_CALL_NOTIFICATION"}] - -data: [{"id":"mNAdvy-NK2l6","type":"text-chunk","group_id":"cDEsAQbSnd3J","metadata":{"format":"markdown","type":"thinking"},"content":"\n\nI need to compare sales performance between 2025 and 2024."}] - -data: [{"type":"notification","group_id":"m1MTvttEUa7o","code":"nls_start"}] - -data: [{"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"}] +=== Example request -data: [{"type":"notification","code":"FINAL_RESPONSE_NOTIFICATION"}] +[source,cURL] ---- -For the complete response in one payload, use the xref:spotter-agent-apis.adoc#_send_queries_to_a_conversation_session[`/send` endpoint] instead. - -//// -[source,] +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/relevant-questions/' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "query": "What drives customer churn?", + "data_source_identifiers": [""] +}' ---- -data: [{"type": "ack", "node_id": "BRxCtJ-aGt8l"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": "I"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " understand"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " you're"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " interested"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " in"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " the"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " net"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " sales"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " of"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " Jackets"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": "."}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " I'll"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " retrieve"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " the"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " relevant"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " data"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " for"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " you"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": "."}] - -data: [{"type": "notification", "group_id": "o8dQ9SAWdtrL", "metadata": {"title": "Net sales of Jackets"}, "code": "nls_start"}] - -data: [{"type": "notification", "group_id": "o8dQ9SAWdtrL", "code": "QH", "message": "Fetching Worksheet Data"}] - -data: [{"type": "notification", "group_id": "o8dQ9SAWdtrL", "code": "TML_GEN", "message": "Translating your query with the Reasoning Engine"}] - -data: [{"type": "notification", "group_id": "o8dQ9SAWdtrL", "code": "ANSWER_GEN", "message": "Verifying results with the Trust Layer"}] - -data: [{"id": "r24X7D99SROD", "type": "answer", "group_id": "o8dQ9SAWdtrL", "metadata": {"sage_query": "[sales] [item type] = [item type].'jackets'", "session_id": "b321b404-cbf1-4905-9b0c-b93ad4eedf89", "gen_no": 1, "transaction_id": "6874259d-13b1-478c-83cb-b3ed52628850", "generation_number": 1, "warning_details": null, "ambiguous_phrases": null, "query_intent": null, "assumptions": "You want to see the total sales amount for jackets item type.", "tml_phrases": ["[sales]", "[item type] = [item type].'jackets'"], "cached": false, "sub_queries": null, "title": "Net sales of Jackets", "worksheet_id": "cd252e5c-b552-49a8-821d-3eadaa049cca"}, "title": "Net sales of Jackets"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "The"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " net"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " sales"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " for"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " Jackets"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " have"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " been"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " visual"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "ized"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " for"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " you"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "."}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " This"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " analysis"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " specifically"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " filtered"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " for"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " the"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " item"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " type"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "jackets"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "\""}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " and"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " calculated"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " the"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " total"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " sales"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " amount"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " associated"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " with"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " those"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " products"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ".\n\n"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "**"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "Summary"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " &"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " Insights"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ":"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "**\n"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "-"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " The"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " visualization"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " shows"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " the"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " total"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " net"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " sales"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " for"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " all"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " jacket"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " transactions"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " in"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " your"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " apparel"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " dataset"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ".\n"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "-"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " The"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " calculation"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " uses"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " only"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " sales"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " amounts"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " where"}] -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " the"}] +[#_sharing_spotter_conversations] +== Sharing Spotter conversations -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " item"}] +// SOURCE: SCAL-306173 (aug.26.mt) +// SOURCE: scaligent/prism/src/public-apis/nl-to-answer.graphql (master) +// SOURCE: scaligent/prism/src/public-apis/docs/descriptions/ai/share-conversation.md (master) +// SOURCE: scaligent/prism/src/public-apis/docs/descriptions/ai/get-shared-content.md (master) +// SOURCE: scaligent/prism/src/public-apis/docs/descriptions/ai/get-share-info.md (master) -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " type"}] +ThoughtSpot 26.9.0.cl introduces REST API v2.0 endpoints for sharing saved Spotter agent conversations with other users or groups. Shared conversations are always `READ_ONLY`. A conversation can be shared only if `enable_save_chat` was set to `true` when the conversation was created. -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " is"}] +=== Supported endpoints -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " \""}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "J"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "ackets"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ".\"\n"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "-"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " This"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " information"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " is"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " useful"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " for"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " understanding"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " the"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " revenue"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " contribution"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " of"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " jackets"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " within"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " your"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " product"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " mix"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ".\n\n"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "If"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " you'd"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " like"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " to"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " see"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " a"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " breakdown"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " by"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " region"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ","}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " state"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ","}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " time"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " period"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ","}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " or"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " compare"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " jacket"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " sales"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " to"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " other"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " product"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " types"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ","}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " please"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " let"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " me"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " know"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "!"}] ----- -//// - -==== SSE event types -The SSE event types streamed in the API response include: - -* `ack` + -Confirms receipt of the request. For example, the type in the first message `data: [{"type": "ack", "node_id": "BRxCtJ-aGt8l"}]`, which indicates that the server has received the client's request and is acknowledging it. -* `conv_title` + -A conversation title (`title`, `conv_id`). -* `notification` + -Progress or status update (`group_id`, `metadata`, `code`). For example, `TOOL_CALL_NOTIFICATION`, `nls_start`, `FINAL_RESPONSE_NOTIFICATION`. -* `type` + -Type can be `thinking`, `text`. -* `text` + -Complete text block in markdown format. -* `text-chunk` + -Text fragments in incremental streaming, often in markdown (`id`, `group_id`, `metadata` with `format`) -* `content` + -The actual text content sent incrementally. For example, `"I"`, `"understand"`, `"you're"`, `"interested"`, `"in"`, `"the"`, `"net"`, `"sales"`, and so on. -* `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` and more) -* `error` + -In case of failures. -* `*-interrupt` + -If the generation was stopped mid-stream. -* `group_id` + -Groups related chunks together. - -For more information and examples, see xref:spotter-agent-apis.adoc#_sse_event_payload_reference[SSE event payload reference]. - -=== Thinking versus output events -Spotter responses have two phases: - -* A *thinking phase*, where the AI reasons through the query and calls internal tools, followed by an *output phase* containing the final response delivered to the user. + - -Events in the thinking phase carry `"metadata": { "type": "thinking" }`. All other events are final output. - -Every event includes a `group_id`. Events sharing the same `group_id` belong together. During the thinking phase, each tool call gets its own `group_id`. A `FINAL_RESPONSE_NOTIFICATION` notification marks the boundary between the thinking and output phases. - -[listing] ----- -THINKING PHASE -─────────────────────────────────────────────────────────── -ack - -┌─ group_id: g1 ── Tool Call 1 ("Searching data") ─────────┐ -│ notification (thinking, TOOL_CALL_NOTIFICATION) │ -│ text-chunk (thinking) │ -│ answer (thinking) │ -└──────────────────────────────────────────────────────────┘ - -┌─ group_id: g2 ── Tool Call 2 ("Running code") ───────────┐ -│ notification (thinking, TOOL_CALL_NOTIFICATION) │ -│ text-chunk (thinking) │ -│ text-chunk (thinking) │ -└──────────────────────────────────────────────────────────┘ - -notification (FINAL_RESPONSE_NOTIFICATION) ←── boundary -──────────────────────────────────────────────────────────── - -OUTPUT PHASE -──────────────────────────────────────────────────────────── -┌─ group_id: g3 ────────────────────────────────────────────┐ -│ text "Here are the results:" │ -│ answer (final visualization) │ -└───────────────────────────────────────────────────────────┘ -[stream closes] ----- - -==== Notification codes reference - -[width="100%" cols="2,4"] -[options='header'] +[width="100%"] +[options="header"] |===== -|Code| When it appears -|`QH`|Query handling started -|`TML_GEN` / `TML_GEN_RETRY`|Generating or retrying TML -|`ANSWER_GEN`|Generating an answer -|`IDENTIFYING_ATTRIBUTES`|Identifying data attributes -|`PERFORMING_CHANGE_ANALYSIS`|Running change analysis -|`PERFORMING_FORECASTING_ANALYSIS`|Running forecasting -|`SUMMARIZING_RESULTS`|Summarizing results -|`TOOL_CALL_NOTIFICATION`|Tool invocation (during thinking phase) -|`FINAL_RESPONSE_NOTIFICATION`|Marks the transition from thinking to output -|`search_datasets_start` / `search_datasets_end`|Data source discovery in progress or complete -|`approval_required`|An external tool requires user permission before proceeding +| Method | Endpoint | Description +| `POST` | `/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` | Shares a saved Spotter conversation with specified principals. Use `grant` and `revoke` arrays to manage access. +| `GET` | `/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content` | Returns the content of a shared Spotter conversation — messages, data sources, and answer details. +| `GET` | `/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info` | Returns sharing metadata — the list of principals the conversation is shared with and their access levels. |===== -=== SSE event payload reference - -==== ack - -[source,JSON] ----- -data: { - "type": "ack", - "group_id": "a1b2c3", - "id": "evt-001", - "node_id": "resp-node-abc" -} ----- - -==== notification (thinking — tool call) - -[source,JSON] ----- -data: { - "type": "notification", - "group_id": "g1", - "id": "evt-002", - "code": "TOOL_CALL_NOTIFICATION", - "message": "Searching for relevant data", - "metadata": { - "type": "thinking", - "tool_title": "Searching sales data", - "tool_code": "RUNNING_CODE_EXECUTION", - "tool_name": "code_interpreter" - } -} ----- - -==== notification (thinking - external tool with MCP integration) - -[source,JSON] ----- -data: { - "type": "notification", - "group_id": "g2", - "id": "evt-003", - "code": "TOOL_CALL_NOTIFICATION", - "message": "Querying Salesforce", - "metadata": { - "type": "thinking", - "tool_title": "Salesforce: Get Opportunities", - "tool_name": "get_opportunities", - "integration_id": "int-sf-123", - "integration_name": "Salesforce" - } -} ----- - -==== notification (approval required) -Sent when an external MCP tool requires explicit user permission before proceeding. Your application should prompt the user to approve or deny the action before continuing. - -[source,JSON] ----- -data: { - "type": "notification", - "group_id": "g2", - "id": "evt-005", - "code": "approval_required", - "metadata": { - "request_id": "perm-req-789", - "integration_id": "int-sf-123", - "integration_name": "Salesforce", - "tool_name": "get_opportunities", - "annotated_title": "Access Salesforce Opportunities" - } -} ----- - -==== notification (FINAL_RESPONSE_NOTIFICATION) - -[source,JSON] ----- -data: { - "type": "notification", - "group_id": "g1", - "id": "evt-004", - "code": "FINAL_RESPONSE_NOTIFICATION", - "message": "" -} ----- - -==== text - -[source,JSON] ----- -data: { - "type": "text", - "group_id": "g3", - "id": "evt-007", - "content": "Here is the total revenue breakdown by region for Q4 2025:\n\n- **North America:** $4.2M\n- **EMEA:** $2.8M\n- **APAC:** $1.5M" -} ----- - -==== text-chunk -Multiple chunks sharing the same `id` should be appended together to reconstruct the full text item. - -[source,JSON] ----- -data: { "type": "text-chunk", "group_id": "g3", "id": "evt-009", "content": "Based on the analysis, " } -data: { "type": "text-chunk", "group_id": "g3", "id": "evt-009", "content": "revenue grew 12% quarter-over-quarter." } ----- - -==== answer -When an `answer` event is received, the `session_id` and `gen_no` fields are returned. You can export the visualization data using the Export Answer Report API to process the results. This allows users to download the answer as a PDF, PNG, CSV, or XLSX file. - -[source,JSON] ----- -data: { - "type": "answer", - "group_id": "g3", - "id": "evt-010", - "title": "Revenue by Region Q4 2025", - "metadata": { - "session_id": "sess-abc-123", - "gen_no": 1, - "transaction_id": "txn-456", - "worksheet_id": "ws-def-789", - "cached": false, - "is_hidden": false - } -} ----- - -==== search_datasets -Emitted as a start/end pair during Auto mode data source discovery. - - -[source,JSON] ----- -data: { "type": "search_datasets", "group_id": "g0", "id": "evt-012", "code": "search_datasets_start", "metadata": {} } - -data: { - "type": "search_datasets", - "group_id": "g0", - "id": "evt-013", - "code": "search_datasets_end", - "metadata": { - "data_sources": [ - { "worksheet_id": "ws-1", "worksheet_name": "Sales Data", "confidence": "high", "reasoning": "Contains revenue columns" }, - { "worksheet_id": "ws-2", "worksheet_name": "Marketing Data", "confidence": "low", "reasoning": "No revenue columns" } - ], - "auto_selected": { "worksheet_id": "ws-1", "worksheet_name": "Sales Data", "confidence": "high", "reasoning": "Best match" } - } -} ----- -==== file - -[source,JSON] ----- -data: { - "type": "file", - "group_id": "g3", - "id": "evt-014", - "files": [ - { "ts_file_id": "file-abc-001", "display_name": "quarterly_report.csv", "file_type": "csv", "created_at": "2025-11-15T10:30:00Z" }, - { "ts_file_id": "file-abc-002", "display_name": "chart.png", "file_type": "png", "created_at": "2025-11-15T10:30:01Z" } - ], - "metadata": { "conv_id": "conv-123" } -} ----- -==== conv_title - -[source,JSON] ----- -data: { - "type": "conv_title", - "group_id": "g0", - "id": "evt-015", - "title": "Revenue Analysis Q4 2025", - "conv_id": "conv-123" -} ----- - -==== error +[NOTE] +==== +Shared conversations are always `READ_ONLY`. Shared access cannot be elevated to edit or admin level. The `notify_on_share` parameter is available from 26.10.0.cl. +==== -[source,JSON] ----- -data: { - "type": "error", - "group_id": "g3", - "id": "evt-016", - "code": "RATE_LIMIT_EXCEEDED", - "message": "Too many requests", - "display_message": "You've exceeded the rate limit. Please try again in a few minutes." -} ----- -==== agent-interrupt +[#share-conversation] +=== Share a conversation -[source,JSON] ----- -Sent when generation is stopped mid-stream. -data: { - "type": "notification", - "group_id": "g3", - "id": "evt-017", - "code": "agent-interrupt", - "message": "Generation stopped" -} ----- +`POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` -[#_stop_an_in_progress_agent_response] -== Stop an in-progress agent response +Grants or revokes access to a saved Spotter conversation. -The `/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response` API endpoint stops a Spotter agent response that is currently in progress for a given conversation session. +==== Path parameters -Use this endpoint when you want to cancel a long-running Spotter response before it completes. The conversation session remains active after you stop a response, so you can send a new query to the same session immediately. +[width="100%"] +[options="header"] +|===== +| Parameter | Type | Required | Description +| `conversation_identifier` | String | Yes | GUID of the Spotter conversation to share. +|===== -=== Request parameters +==== Request parameters -[width="100%", cols="2,2,4"] -[options='header'] +[width="100%"] +[options="header"] |===== -|Parameter|Type| Description -|`conversation_identifier`|Path parameter|__String__. Required. The identifier of the active conversation session. Use the value returned by the xref:spotter-agent-apis.adoc#_create_a_conversation_session_with_spotter_agent[create conversation] API endpoint. +| Parameter | Type | Required | Description +| `grant` | Array | No | List of principal identifier objects to grant `READ_ONLY` access to. Each object must include `identifier` (GUID, username, or email of the user or group). +| `revoke` | Array | No | List of principal identifier objects to revoke access from. Each object must include `identifier`. +| `refresh_shared_content` | Boolean | No | When `true`, regenerates the shared content snapshot before sharing. Default: `false`. +| `notify_on_share` | Boolean | No | When `true`, sends an in-app notification to newly granted principals. Default: `true`. Available from 26.10.0.cl. |===== -This endpoint does not require a request body. - -=== Example request +==== Example request [source,cURL] ---- curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response' \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share' \ + -H 'Authorization: Bearer {access-token}' \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {AUTH_TOKEN}' ----- - -=== Example response - -If the API request is successful, ThoughtSpot stops the in-progress response and returns a 204 response code. - -If the conversation session is not found or has expired, the API returns an error: - -[source,JSON] ----- -{ - "error_code": "CONVERSATION_NOT_FOUND", - "message": "The specified conversation session does not exist or has expired." -} ----- - -[#process_results] -== Process results generated from a conversation session -To export or download the Answer data generated by the Spotter APIs, use the xref:data-report-v2-api.adoc#exportSpotterData[Answer report] API. - -The `session_id` and `gen_no` values from the `answer` event metadata are required to identify the answer to export. - -NOTE: Requires at least view access to the Answer. - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \ - -H 'Authorization: Bearer {Bearer_token}' \ - -H 'Accept: application/octet-stream' \ - -H 'Content-Type: application/json' \ --data-raw '{ - "session_identifier": "sess-abc-123", - "generation_number": 1, - "file_format": "CSV" + "grant": [ + { "identifier": "user@example.com" }, + { "identifier": "" } + ], + "revoke": [], + "refresh_shared_content": false }' ---- -The `file_format` parameter accepts `PDF`, `PNG`, `CSV`, or `XLSX`. -[NOTE] -==== -Using tokens generated by the Spotter API in a xref:data-report-v2-api.adoc#_search_data_api[Search Data API] request can return invalid column errors, because these tokens may reference formulas or columns not present in the data model. Instead, use the xref:data-report-v2-api.adoc#exportSpotterData[Answer report] API and include the session ID and generation number obtained from the Spotter API in your API request to retrieve the data. -==== +[#get-shared-content] +=== Get shared content +`GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content` -== Data literacy and query assistance -The query assistance APIs help users find the appropriate dataset for a given query string, suggest what questions can be asked, and return example questions. These APIs are specifically designed to improve data literacy for users who may not be familiar with the underlying data, making it easier for them to explore and analyze data effectively. +Returns the content of a shared Spotter conversation that was shared with the authenticated user. -=== Get data source suggestions +==== Path parameters -The `POST /api/rest/2.0/ai/data-source-suggestions` API provides relevant data source recommendations for a user-submitted natural language query. To use this API, you must have at least view access to the underlying metadata object referenced in the response. +[width="100%"] +[options="header"] +|===== +| Parameter | Type | Required | Description +| `conversation_identifier` | String | Yes | GUID of the shared Spotter conversation. +|===== -==== Request parameters +==== Response fields -[width="100%" cols="2,4"] -[options='header'] -|==== -|Parameter| Description -|`metadata_context` a| Required. Specify one of the following attributes to set the metadata context: - -* `data_source_identifiers` + -__Array of strings__. IDs of the data source object such as Models. -* `answer_identifiers` + -__Array of strings__. GUIDs of the Answer objects that you want to use as metadata. -* `conversation_identifier` + -__String__. ID of the conversation session. -* `liveboard_identifiers` + -__Array of strings__. GUIDs of the Liveboards that you want to use as metadata. - -| `query` |__String__. Required parameter. Specify the query string that needs to be decomposed into smaller, analytical sub-questions. -|`limit_relevant_questions` + -__Optional__ | __Integer__. Sets a limit on the number of sub-questions to return in the response. Default is 5. -|`bypass_cache` + -__Optional__| __Boolean__. When set to `true`, disables cache and forces fresh computation. -|`ai_context` + -__Optional__. a| Additional context to guide the response. Define the following attributes as needed: -|==== +[width="100%"] +[options="header"] +|===== +| Field | Type | Description +| `conversation_id` | String | GUID of the original conversation. +| `shared_conversation_id` | String | GUID of the shared conversation snapshot. +| `messages` | Array | List of conversation messages included in the shared snapshot. +| `data_sources` | Array | Data sources associated with the conversation. +| `code_execution_files` | Array | Files generated during code execution steps in the conversation, if any. +|===== ==== Example request [source,cURL] ---- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/data-source-suggestions' \ - -H 'Accept: application/json' \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {AUTH_TOKEN}' \ - --data-raw '{ - "metadata_context": { - "data_source_identifiers": [ - "cd252e5c-b552-49a8-821d-3eadaa049cca" - ] - }, - "query": "Net sales of Jackets in west coast", - "limit_relevant_questions": 3 -}' ----- - -==== API response -If the API request is successful, ThoughtSpot returns a ranked list of data sources, each annotated with relevant reasoning. - -[source,JSON] ----- -{ - "relevant_questions": [ - { - "query": "What is the trend of sales by type over time?", - "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", - "data_source_name": "(Sample) Retail - Apparel" - }, - { - "query": "Sales by item", - "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", - "data_source_name": "(Sample) Retail - Apparel" - }, - { - "query": "Sales across regions", - "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", - "data_source_name": "(Sample) Retail - Apparel" - } - ] -} +curl -X GET \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/json' ---- -The returned results include metadata such as: +[#get-share-information] +=== Get share information -* `confidence` + -A float indicating the Model's confidence in the relevance of each recommendation. -* `details` + -The data source ID, name, and description for each recommended data source. -* `reasoning` + -Reason provided by the LLM to explain why each data source was recommended. +`GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info` -=== Get relevant questions +Returns the sharing metadata for a Spotter conversation — the list of principals the conversation is shared with. -The `/api/rest/2.0/ai/relevant-questions/` API endpoint breaks down a user-submitted query into relevant sub-questions. It accepts the original query and optional additional context, then generates a set of related questions to help users explore their data comprehensively. - -During agentic interactions, this API can be used as an integrated tool to decompose user queries and suggest relevant questions for a specific data context. REST clients can also call this API directly to fetch relevant questions via a `POST` request. - -==== Request parameters +==== Path parameters -[width="100%" cols="2,4"] -[options='header'] +[width="100%"] +[options="header"] |===== -|Parameter| Description -|`metadata_context` a| Required. Specify one of the following attributes to set the metadata context: - -* `data_source_identifiers` + -__Array of strings__. IDs of the data source object such as Models. -* `answer_identifiers` + -__Array of strings__. GUIDs of the Answer objects that you want to use as metadata. -* `conversation_identifier` + -__String__. ID of the conversation session. -* `liveboard_identifiers` + -__Array of strings__. GUIDs of the Liveboards that you want to use as metadata. - -| `query` |__String__. Required parameter. Specify the query string that needs to be decomposed into smaller, analytical sub-questions. -|`limit_relevant_questions` + -__Optional__ | __Integer__. Sets a limit on the number of sub-questions to return in the response. Default is 5. -|`bypass_cache` + -__Optional__| __Boolean__. When set to `true`, disables cache and forces fresh computation. -|`ai_context` + -__Optional__. a| Additional context to guide the response. Define the following attributes as needed: - -* `instructions` + -__Array of strings__. Custom user instructions to influence how the AI interprets and processes the query. -* `content` + -__Array of strings__. Additional input such as raw text or CSV-formatted data to enhance context and answer quality. +| Parameter | Type | Required | Description +| `conversation_identifier` | String | Yes | GUID of the Spotter conversation. |===== -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/relevant-questions/' \ - -H 'Accept: application/json' \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {AUTH_TOKEN}' \ - --data-raw '{ - "metadata_context": { - "data_source_identifiers": [ - "cd252e5c-b552-49a8-821d-3eadaa049cca" - ] - }, - "query": "Net sales of Jackets in west coast", - "limit_relevant_questions": 3 -}' ----- +==== Response fields -==== Example response -If the request is successful, the API returns a set of questions related to the query and metadata context in the `relevant_questions` array. Each object in the `relevant_questions` array contains the following fields: +[width="100%"] +[options="header"] +|===== +| Field | Type | Description +| `is_shared_content_outdated` | Boolean | `true` if the shared content snapshot is out of date with the current conversation state and needs to be refreshed. +| `principals` | Array | List of principal objects the conversation is shared with. Each entry includes `identifier` and `permission` (always `READ_ONLY`). +|===== -* `query` + -A string containing the natural language (NL) sub-question. -* `data_source_identifier` + -GUID of the data source object. -* `data_source_name` + -Name of the associated data source object. +==== Example request -[source,JSON] +[source,cURL] ---- -{ - "relevant_questions": [ - { - "query": "What is the trend of sales by type over time?", - "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", - "data_source_name": "(Sample) Retail - Apparel" - }, - { - "query": "Sales by item", - "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", - "data_source_name": "(Sample) Retail - Apparel" - }, - { - "query": "Sales across regions", - "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", - "data_source_name": "(Sample) Retail - Apparel" - } - ] -} +curl -X GET \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/json' ---- -== Additional resources +== Related resources -* Visit the +++REST API v2.0 Playground+++ to view the API endpoints and verify the request and response workflows. -* For information about MCP tools, see xref:mcp-integration.adoc[MCP server integration]. +* xref:spotter-agent-conversation-mgmt-apis.adoc[Saving and managing Spotter AI chat] +* xref:spotter-ai-memory-api.adoc[Spotter memory APIs] +* xref:spotter-agent-instructions.adoc[Spotter AI Agent instructions APIs] +* xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog] From 40511ea84f9ac3b6f9a618b7d51490c72db72576 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 17 Aug 2026 09:44:16 +0530 Subject: [PATCH 024/154] docs: add Answer Export API GA documentation (SCAL-306069) --- modules/ROOT/pages/data-report-v2-api.adoc | 503 ++++----------------- 1 file changed, 87 insertions(+), 416 deletions(-) diff --git a/modules/ROOT/pages/data-report-v2-api.adoc b/modules/ROOT/pages/data-report-v2-api.adoc index a73d16087..dfe588454 100644 --- a/modules/ROOT/pages/data-report-v2-api.adoc +++ b/modules/ROOT/pages/data-report-v2-api.adoc @@ -204,487 +204,158 @@ curl -X POST \ -H 'Accept: application/json'\ -H 'Content-Type: application/json' \ --data-raw '{ - "metadata_identifier": "f605dbc7-db19-450b-8613-307118f74c3c", + "metadata_identifier": "e9a3b456-ba71-4d80-9678-38b25edf18dc", + "data_format": "COMPACT", + "record_offset": 0, + "record_size": 10 }' ---- - == Report APIs -ThoughtSpot provides the following REST API v2 endpoints to fetch data: +ThoughtSpot provides the following REST API v2 endpoints to export reports: -* xref:_liveboard_report_api[`POST /api/rest/2.0/report/liveboard`] + -Download a Liveboard and its visualizations in PDF, PNG, CSV, or XLSX file format. -* xref:#_answer_report_api[`POST /api/rest/2.0/report/answer`] + -Download data from a saved Answer in PDF, PNG, CSV, or XLSX file format. +* xref:#_liveboard_report_api[`POST /api/rest/2.0/report/liveboard`] to export a Liveboard as a PDF or PNG. +* xref:#answer-report[`POST /api/rest/2.0/report/answer`] to export an Answer as PDF, PNG, CSV, or XLSX. === Liveboard Report API -To download a Liveboard report via `/api/rest/2.0/report/liveboard` API, you need at least view access to the Liveboard specified in the API request. - -In the `POST` request body, specify the GUID or name of the Liveboard as `metadata_identifier`. To download reports with specific visualizations, add GUIDs or names of the visualizations in the `visualization_identifiers`. - -To download visualizations from a specific Liveboard tab, specify the name or GUID of the tab in the `tab_identifiers` parameter. - -To download a personalized view of the Liveboard, specify the view name in the `personalised_view_identifier` attribute. - -[IMPORTANT] -==== -* The downloadable file returned in API response file is extensionless. You need to rename the downloaded file by typing in the relevant extension. -* If the Liveboard includes Note tiles, ensure that you do not pass the GUID of Note tiles as `visualization_identifiers` in the API request. Attempting to do so will lead to an error, and the API will return 400 error code in response. -* Attempting to override existing filter values with runtime filters while exporting a Liveboard will result in an error. -* If Role-Based Access Control (RBAC) is enabled, `DATADOWNLOADING` (Can download Data) privilege is required for Liveboard exports. -* If the granular Role-Based Access Control (RBAC) is enabled, the `CAN_DOWNLOAD_DETAILED_DATA` (Can download detailed data) privilege is required to export in the XLSX or CSV formats, and the `CAN_DOWNLOAD_VISUALS` (Can download visuals) privilege is required for PDF or PNG exports. In this case the `DATADOWNLOADING` privilege ceases to exist. -==== - -==== File Formats - -The default `file_format` is *CSV*. - -[NOTE] -If you do not have .csv downloads enabled for your ThoughtSpot instance, select either `PDF` or `PNG` `file_format` to successfully download the report. Using any other format will cause the API to return an error. +The `POST /api/rest/2.0/report/liveboard` endpoint exports a Liveboard in PDF or PNG format. +==== Prerequisites -For *CSV* downloads, +To download a Liveboard report, the user must have at least *View* access to the Liveboard. -* Each visualization is exported as a separate .csv file. -* If multiple visualizations are selected, the downloaded report is a single compressed .zip file containing all .CSV files. -* It does not support any additional parameters to customize the page orientation and `include_cover_page`, `include_filter_page`, logo, footer text, and page numbers. -* Charts are exported as tabular data. Downloaded reports may include columns not seen in the visualization if they were used as tokens in the underlying search query. +If RBAC is enabled, the user must have the `DATADOWNLOADING` (*Can download Data*) privilege or the `CAN_DOWNLOAD_VISUALS` (*Can download visuals*) privilege. -===== Sample API payload for CSV downloads +==== Example [source,cURL] ---- curl -X POST \ --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/liveboard' \ - -H 'Authorization: Bearer {access-token}'\ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/octet-stream' \ -H 'Content-Type: application/json' \ ---data-raw '{ -"metadata_identifier": "416052fd-ad22-4d48-be0a-e43b53109957", -"file_format": "CSV", -"tab_identifiers": [ -"bc6d6fb8-1e06-4617-b02f-51745e6933a6" -] -}' + --data-raw '{ + "metadata_identifier": "", + "file_format": "PDF" +}' \ + --output liveboard.pdf ---- -For *XLSX* downloads, - -* Visualization is exported as an Excel workbook (.xlsx). -* If multiple visualizations are selected, the downloaded report is a single Excel workbook (.xlsx) containing each visualization in their individual tab. -* A maximum of 255 tabs per .xlsx workbook are allowed. -* It does not support any additional parameters to customize the page orientation and `include_cover_page`, `include_filter_page`, logo, footer text, and page numbers. -* Charts are exported as tabular data. Downloaded reports may include columns not seen in the visualization if they were used as tokens in the underlying search query. -* New pivot tables generated in .xlsx workbooks using this API endpoint retain their complete visual formatting and structural integrity. - -===== Sample API payload for XLSX downloads - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/liveboard' \ - -H 'Authorization: Bearer {access-token}'\ - -H 'Content-Type: application/json' \ ---data-raw '{ -"metadata_identifier": "416052fd-ad22-4d48-be0a-e43b53109957", -"file_format": "XLSX", -"visualization_identifiers": [ -"254c6e30-680c-41ea-aa4d-bb059f745462" -] -}' ----- +[#answer-report] +=== Answer Report API -For *PDF* downloads, you can specify additional parameters to customize the page orientation and include or exclude the cover page, logo, footer text, and page numbers. +// SOURCE: SCAL-306069 -You can now also download continuous pdfs which matches the full length of your Liveboard, without breaking them into multiple A4 pages. +`POST /api/rest/2.0/report/answer` -* `page_size = CONTINUOUS` Unlike the A4 format, which introduces forced page breaks between visualizations, this continuous flow maintains your exact design and intended layout. -+ -When `page_size = CONTINUOUS`, the `include_filter_page` option works to show/hide the filter section in the PDF page (in a continuous PDF, there is no separate filter page, but the filters are included on the same page at the top). -* `zoom_level` offers various download size options to suit the viewer's screen dimensions, thereby enhancing legibility. This can be set only when `page_size = CONTINUOUS`. Valid values are integers in the range of 45 and 175. +The Answer Report API is generally available from 26.9.0.cl. Use this endpoint to export Answer data in `CSV`, `XLSX`, `PDF`, or `PNG` format. The endpoint supports saved Answers, pinned Answers (visualizations on a Liveboard), and Spotter-generated (ad hoc) Answers. +==== Prerequisites -===== Sample API payload for PDF downloads +To download Answer data, the user must have at least *View* access to the Answer or Liveboard. -[source,cURL] ----- -curl -X POST 'https://{ThoughtSpot-Host}/api/rest/2.0/report/liveboard' \ ---header 'Authorization: Bearer {access-token}' \ ---header 'Content-Type: application/json' \ ---data-raw '{ - "metadata_identifier": "416052fd-ad22-4d48-be0a-e43b53109957", - "file_format": "PDF", - "visualization_identifiers": [ - "254c6e30-680c-41ea-aa4d-bb059f745462" - ], - "pdf_options": { - "page_size": "CONTINUOUS", - "zoom_level": 105, - "include_cover_page": true, - "include_custom_logo": true, - "include_filter_page": true, - "include_page_number": true, - "page_orientation": "PORTRAIT", - "truncate_table": false, - "page_footer_text": "Sample footer text" - } -}' ----- +If Role-Based Access Control (RBAC) is enabled, the user must have one of the following privileges: -For *PNG* downloads, you can now define +* `DATADOWNLOADING` (*Can download Data*) +* `CAN_DOWNLOAD_DETAILED_DATA` (*Can download detailed data*) — for CSV and XLSX formats +* `CAN_DOWNLOAD_VISUALS` (*Can download visuals*) — for PNG format -* `image_resolution` -* `image_scale` -* `include_header` +==== Request parameters -[IMPORTANT] -==== -* If the above settings are enabled on your instance or you are using a ThoughtSpot release 10.9.0.cl or later, -** You will no longer be able to use the `include_cover_page`, `include_filter_page` within the `png_options`. -** PNG download will support exporting only one tab at a time. If the `tab_identifier` is not specified, the first tab will be downloaded. -* Due to UI limitations in the REST API Playground, you'll notice that some parameters are automatically included in the PNG options JSON. This may cause your API request to fail. As a workaround, click *View JSON* next to the `png_options`, review the parameters, remove additional parameters, and then click *Try it out*. +[width="100%"] +[options="header"] +|===== +| Parameter | Type | Required | Description +| `metadata_identifier` | String | Yes | GUID or name of the saved Answer. For pinned Answers, use the parent Liveboard GUID or name and set `viz_guid`. +| `file_format` | String | Yes | Export format. Accepted values: `CSV`, `XLSX`, `PDF`, `PNG`. +| `viz_guid` | String | No | GUID of a pinned visualization on a Liveboard. Required for pinned Answer exports. Liveboard-level filters and runtime overrides are applied automatically. +| `personalised_view_identifier` | String | No | GUID or name of a Personalized View. When specified, the export uses data from that view. +| `runtime_filter` | Object | No | Runtime filter overrides to apply to the export. +| `runtime_sort` | Object | No | Runtime sort overrides to apply to the export. +| `runtime_param_override` | Object | No | Runtime parameter overrides to apply to the export. +| `x_resolution` | Integer | No | Width of the PNG export in pixels. Accepted range: 600–3840. Applies only when `file_format` is `PNG`. Default: 2254. +| `y_resolution` | Integer | No | Height of the PNG export in pixels. Accepted range: 600–3840. Applies only when `file_format` is `PNG`. Default: 1588. +| `scaling_factor` | Integer | No | Scaling percentage for chart elements in PNG exports. Accepted range: 80–400. Does not crop the image. Applies only when `file_format` is `PNG`. +|===== -==== - -===== Sample API payload for PNG downloads +==== Export a saved Answer [source,cURL] ---- curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/liveboard' \ - -H 'Authorization: Bearer {access-token}'\ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/octet-stream' \ -H 'Content-Type: application/json' \ --data-raw '{ - "metadata_identifier": "416052fd-ad22-4d48-be0a-e43b53109957", - "file_format": "PNG", - "tab_identifiers": [ - "bc6d6fb8-1e06-4617-b02f-51745e6933a6" - ], - "png_options": { - "include_cover_page": null, - "include_filter_page": null, - "personalised_view_id": null, - "image_resolution": 1920, - "image_scale": 100, - "include_header": true - } -}' + "metadata_identifier": "", + "file_format": "CSV" +}' \ + --output answer.csv ---- -==== Override filters - -If the Liveboard has filters applied, and you want to override the filters before downloading the Liveboard, you can specify the filters in the `override_filters` array. +==== Export a pinned Answer -[source,JSON] +[source,cURL] ---- curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/liveboard' \ - -H 'Content-Type: application/json' \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \ -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/octet-stream' \ + -H 'Content-Type: application/json' \ --data-raw '{ - "metadata_identifier": "9bd202f5-d431-44bf-9a07-b4f7be372125", - "file_format": "PNG", - "override_filters": [ - { - "column_name": "Color", - "generic_filter": { - "op": "IN", - "values": [ - "almond", - "turquoise" - ] - }, - "negate": false - }, - { - "column_name": "Commit Date", - "date_filter": { - "datePeriod": "HOUR", - "number": 3, - "type": "LAST_N_PERIOD", - "op": "EQ" - } - }, - { - "column_name": "Sales", - "generic_filter": { - "op": "BW_INC", - "values": [ - "100000", - "70000" - ] - }, - "negate": true - } - ], - "png_options": { - "include_cover_page": true, - "include_filter_page": true - } -}' + "metadata_identifier": "", + "viz_guid": "", + "file_format": "PDF" +}' \ + --output pinned-answer.pdf ---- -[#transient-lb-content] -==== Liveboard data with unsaved changes - -include::{path}/transient-lb-content.adoc[] - -===== Sample browser fetch request - -[source,JavaScript] ----- -< iframe src = "http://ts_host:port/" id = "ts-embed" > < /iframe> -< script src = "/path/to/liveboard.js" > < /script> -< script > - const embed = new LiveboardEmbed("#embed", { - frameParams: {}, - }); - async function liveboardData() { - const transientPinboardContent = await embed.trigger(HostEvent.getExportRequestForCurrentPinboard); - const liveboardDataResponse = await fetch("https://ts_host:port/api/rest/2.0/report/liveboard", { - method: "POST", - body: createFormDataObjectWith({ - "transient_content": transientPinboardContent, - }), - }); - } -< /script> ----- - -See also, link:https://developers.thoughtspot.com/docs/Enumeration_HostEvent#_getexportrequestforcurrentpinboard[HostEvent.getExportRequestForCurrentPinboard]. - -=== Answer Report API - -To download Answer data via `/api/rest/2.0/report/answer` API, you need at least view access to the saved Answer. - -In the request body, specify the GUID or name of the Answer object as `metadata_identifier`. - -The API supports exporting saved Answers, pinned Answers from a Liveboard, and Spotter-generated Answers. You can download Answer data in `CSV`, `XLSX`, `PNG`, and `PDF` format. The default `file_format` is `CSV`. - -[IMPORTANT] -==== -* If Role-Based Access Control (RBAC) is enabled, `DATADOWNLOADING` (Can download Data) privilege is required for Answer exports. -* If the granular Role-Based Access Control (RBAC) is enabled, the `CAN_DOWNLOAD_DETAILED_DATA` (Can download detailed data) privilege is required to export in the PDF, XLSX or CSV formats, and the `CAN_DOWNLOAD_VISUALS` (Can download visuals) privilege is required for PNG exports. In this case the `DATADOWNLOADING` privilege ceases to exist. -==== - -==== Example +==== Export a Spotter Answer [source,cURL] ---- curl -X POST \ --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \ - -H 'Authorization: Bearer {access-token}'\ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/octet-stream' \ -H 'Content-Type: application/json' \ --data-raw '{ - "metadata_identifier": "9bd202f5-d431-44bf-9a07-b4f7be372125", - "file_format": "PNG" -}' + "metadata_identifier": "", + "file_format": "XLSX" +}' \ + --output spotter-answer.xlsx ---- [NOTE] ==== -* Exported files are automatically named after the Answer title, with the file extension appended based on the selected format. -* HTML rendering is not supported for PDF exports of Answers with tables. +To export a Spotter-generated Answer, pass the answer ID from the Spotter API response as `metadata_identifier`. XLSX and PDF formats are supported for Spotter Answers from 26.9.0.cl. ==== - -Contact ThoughtSpot support to enable these enhanced settings for this API endpoint on your ThoughtSpot instance: - -* `personalised_view_identifier` [earlyAccess eaBackground]#Early Access# + -Optional parameter to specify the GUID of the personalised view of the `PINNED` Answer object that you want to download. -* `type` [earlyAccess eaBackground]#Early Access# + -Used to distinguish between a saved answer and a pinned answer on a Liveboard. Setting this parameter to `PINNED` allows the API to -accept the guid of a pinned Answer directly as the `metadata_identifier`. When -exporting an Answer, all Liveboard-level filters, Runtime Filters, and Column -Security Rules (CSR) are automatically applied to the export output. - -The `png_options` [earlyAccess eaBackground]#Early Access# support the following properties: - -[cols="1,1,3"] -|=== -|Property |Type |Description - -|`x_resolution` -|Number -|Width of the exported PNG in pixels. + -Valid range: `600px` to `3840px`. - -|`y_resolution` -|Number -|Height of the exported PNG in pixels. + -Valid range: `600px` to `3840px`. - -|`scaling` -|Integer -|Display scale percentage for objects rendered in the image. Adjusts the relative -size of visual elements without cropping the image. + -Valid range: `80%` to `500%`. -|=== - -You can now export the PNG of any Answer in any aspect ratio and any scaling or zoom level. Just configure, scale, and export exactly what you need. - -[#exportSpotterData] -==== Export data generated from Spotter APIs -To export results generated from Spotter APIs such as `/api/rest/2.0/ai/answer/create`, `/api/rest/2.0/ai/agent/converse/sse`, and `/api/rest/2.0/ai/conversation/{conversation_identifier}/converse`, include the session ID and generation number in the `POST` request body. - -When downloading a Spotter-generated Answer, do not specify the metadata object ID, because you will be exporting the data generated from a conversation session with Spotter and not a saved Answer. - -===== Request example +==== Export a PNG with custom dimensions [source,cURL] ---- curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/octet-stream' \ -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {AUTH_TOKEN}' \ --data-raw '{ - "file_format": "CSV", - "session_identifier": "ee077665-08e1-4a9d-bfdf-7b2fe0ca5c79", - "generation_number": 2 -}' ----- - -* `session_identifier` refers to session ID returned in the Spotter API response. -* `generation_number` indicates the Answer generation number. -* `file_format` specifies the format of the output. You can export the Spotter-generated data as PNG, CSV, XLSX, or PDF file. By default, the API exports this data in PNG file format. - -===== API Response - -If the API request is successful, ThoughtSpot returns the data in the specified file format. You can download the file to use it later or import it into your application environment. - -//// -===== Response codes -[width="100%" cols="2,4"] -[options='header'] -|=== -|HTTP status code|Description -|**200**| Successful operation -|**400**| Invalid parameter -|**401**| Unauthorized access -|**401**| Forbidden request -|**500**| Internal error -|=== -//// - -== Pagination settings for Data APIs - -When you make REST API calls to some v2 Data endpoints to query data, the API may return many rows of data in response. By default, the following parameters are set in API requests to the v2 Data API endpoints: - -[source,JSON] ----- -{ - "data_format": "COMPACT", - "record_offset": 0, - "record_size": 10 -} ----- - -[WARNING] -==== -Do not set `record_size` to `-1`. On ThoughtSpot instances with a large number of objects or users, this can lead to slow responses, excessive logging, and out-of-memory failures. Specify an explicit `record_size` and iterate through pages programmatically. -==== - -The APIs return a maximum of 100000 rows of data at any given time. If you must retrieve a higher number of rows in an API call, contact ThoughtSpot Customer Support to increase the row size limit. However, if the record size and number of rows are high, the API may take a while to fetch the data, and the request may time out. - -== Runtime overrides -The Data API endpoints support the following runtime overrides: - -* Runtime filters -* Runtime sorting of columns -* Runtime Parameters - -=== Runtime filters -To add runtime filters, in the `runtime_filter` property, add the `col1`, `op1`, and `val1` parameters JSON key-value format: - -[source,JSON] ----- -"runtime_filter": { - "col1": "type", - "op1": "EQ", - "val1": "roasted", -} ----- - -To add additional filters, increment the number at the end of each parameter for each filter: for example, col2, op2, val2, and so on. - -[source,JSON] ----- -"runtime_filter": { - "col1": "type", - "op1": "EQ", - "val1": "roasted", - "col2": "tea", - "op2": "EQ", - "val2": "barley" -} ----- - -Some operators such as allow more than one value in the `val` parameter: - -[source,JSON] ----- - "runtime_filter": { - "col1": "tea", - "op1": "CONTAINS", - "val1": [ - "barley", - "mint" - ], - "col2": "type", - "op2": "CONTAINS", - "val2": [ - "roasted", - "loose leaves" - ] -} ----- - -For more information, see xref:runtime-filters.adoc#rtOperator[Supported runtime filter operators] and xref:runtime-filters.adoc#_rest_api_v2_0_endpoints[Apply runtime filters via REST APIs]. - -=== Runtime parameters - -To add runtime Parameters, in the `runtime_param_override` property, add the `param1, and `paramVal1` parameters JSON key-value format. The Parameter value must be defined as per the data type. For example, `Date Param` and `Date List Param` Parameters, specify Epoch time as value. - -To apply Parameter overrides on Liveboards and Answers, ensure that the Parameters are configured in the Model used for generating Liveboard visualizations and Answer. - -[source,JSON] ----- - "runtime_param_override": { - "param1": "Double List Param", - "paramVal1": 0.5 - } ----- - -To add additional Parameter overrides, increment the number at the end of each parameter: for example, paramVal2, and so on. - -[source,JSON] ----- - "runtime_param_override": { - "param1": "Double List Param", - "paramVal1": 0.5, - "param2": "Date Param", - "paramVal2": 1696932000 - } ----- - -For more information, see xref:runtime-parameters.adoc[Runtime Parameter overrides]. - -=== Runtime sort - -To sort columns on a Liveboard or Answer, define runtime sort properties in `runtime_sort` as a key-value pair in JSON format. The `runtime_sort` object allows `sortCol1` and `asc1` properties. To sort more columns, increment the number at the end of the parameter for each key: for example, `sortCol2`, `asc2`, `sortCol3`, `asc3`, and so on. - - -[source,JSON] ----- - "runtime_sort": { - "sortCol1": "sales", - "asc1": true, - "sortCol2": "region", - "asc2": false - } + "metadata_identifier": "", + "file_format": "PNG", + "x_resolution": 3840, + "y_resolution": 2160, + "scaling_factor": 150 +}' \ + --output answer-4k.png ---- -For more information, see xref:runtime-sort.adoc#_rest_api_v2_0[Runtime sorting of columns]. - +== Related resources +* xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog] +* xref:semantic-integrations-api.adoc[Snowflake Semantic View integration APIs] +* xref:spotter-agent-apis.adoc[Spotter Agent APIs] From ba2c7be7d296a516cdcf12c155101c02860519ab Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Mon, 17 Aug 2026 10:11:30 +0530 Subject: [PATCH 025/154] added Ramjith's feedback --- modules/ROOT/pages/runtime-filters.adoc | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/modules/ROOT/pages/runtime-filters.adoc b/modules/ROOT/pages/runtime-filters.adoc index 745ab1618..f1bbcf510 100644 --- a/modules/ROOT/pages/runtime-filters.adoc +++ b/modules/ROOT/pages/runtime-filters.adoc @@ -51,9 +51,8 @@ ThoughtSpot enforces separate filter count limits depending on how runtime filte URL-based runtime filters:: URL-based runtime filters are capped at exactly 50. This limit is fixed and cannot be configured. The internal constant `MAX_RUNTIME_FILTERS` is set to `50`, but the -parsing loop runs from index `1` up to (but not including) `50` -(`index < MAX_RUNTIME_FILTERS`). This means filter values `col1`/`op1`/`val1` -through `col49`/`op49`/`val49` are processed; `col50` and above are ignored. +parsing loop runs from index `1` up to `50`. This means filter values `col1`/`op1`/`val1` +through `col50`/`op50`/`val50` are processed. Embed payload runtime filters (Visual Embed SDK):: @@ -65,7 +64,8 @@ Contact ThoughtSpot support to configure this limit for your instance. The value [IMPORTANT] ==== -Regardless of the filter path, filters beyond the enforced limit are silently dropped. No error is thrown, no warning is emitted, and no embed event is fired. The embedded object renders using only the filters within the allowed count. Always validate filter counts in your application before passing them to the SDK. +* Regardless of the filter path, filters beyond the enforced limit are silently dropped. No error is thrown, no warning is emitted, and no embed event is fired. The embedded object renders using only the filters within the allowed count. Always validate filter counts in your application before passing them to the SDK. +* Runtime filters must be numbered sequentially, starting from `col1`. The parser reads filters in order, like `col1`, `col2`, `col3`, and stops as soon as a number is missing. ==== === Supported data types From 9da4bed02098cac0d3f02c8c0ca5c265d89e8101 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 17 Aug 2026 10:23:43 +0530 Subject: [PATCH 026/154] docs: add 26.9.0.cl REST API changelog section (SCAL-306069, SCAL-309867, SCAL-306173, SCAL-320899, SCAL-317550, SCAL-307284, SCAL-312738, SCAL-277656) --- modules/ROOT/pages/rest-apiv2-changelog.adoc | 484 +------------------ 1 file changed, 1 insertion(+), 483 deletions(-) diff --git a/modules/ROOT/pages/rest-apiv2-changelog.adoc b/modules/ROOT/pages/rest-apiv2-changelog.adoc index eaeeff350..ec6077f68 100644 --- a/modules/ROOT/pages/rest-apiv2-changelog.adoc +++ b/modules/ROOT/pages/rest-apiv2-changelog.adoc @@ -1,483 +1 @@ -= REST API v2.0 changelog -:toc: true -:toclevels: 1 - -:page-title: REST API v2.0 changelog -:page-pageid: rest-v2-changelog -:page-description: Changelog of REST APIs - -This changelog lists the features and enhancements introduced in REST API v2.0. For information about new features and enhancements available for embedded analytics, see xref:whats-new.adoc[What's New]. - -== Version 26.9.0.cl, September 2026 - -=== Answer Export API enhancements — General Availability - -// SOURCE: SCAL-306069 - -The `POST /api/rest/2.0/report/answer` endpoint is generally available from 26.9.0.cl. The `isAnswerExportV2Enabled` flag is enabled by default on all ThoughtSpot Cloud instances. The following enhancements are included in this release: - -Pinned Answer export:: -Pass `viz_guid` to export a pinned Answer (a visualization on a Liveboard) directly. Liveboard-level filters and runtime overrides are applied automatically. The `metadata_identifier` must be the parent Liveboard GUID or name. - -Personalized View support:: -Pass `personalised_view_identifier` to export data from a specific Personalized View of a Liveboard. - -Spotter Answer export:: -XLSX and PDF export formats are now supported for Spotter-generated (ad hoc) Answers, in addition to CSV and PNG. - -Custom PNG dimensions:: -Use `x_resolution` and `y_resolution` parameters to specify custom pixel dimensions for PNG exports. Accepted range: 600–3840 px per axis. - -Display scaling:: -Use `scaling_factor` (range: 80–400) to adjust the relative size of chart elements in a PNG export without cropping the image. - -Dynamic file naming:: -Exported files are automatically named based on the Answer title with the correct file extension (`.png`, `.pdf`, `.csv`, `.xlsx`) appended. - -For more information, see xref:data-report-v2-api.adoc#answer-report[Answer Report API]. - -=== Snowflake Semantic View integration APIs - -// SOURCE: SCAL-309867 - -ThoughtSpot 26.9.0.cl introduces REST API v2.0 endpoints for managing Snowflake Semantic View integrations programmatically. These APIs allow administrators and data managers to create, search, import, and delete semantic integration configurations without using the ThoughtSpot UI. - -[width="100%"] -[options="header"] -|===== -| Method | Endpoint | Description -| `POST` | `/api/rest/2.0/semantic-integrations/create` | Creates a new semantic integration by reading a Snowflake Semantic View and generating a ThoughtSpot data model. -| `POST` | `/api/rest/2.0/semantic-integrations/search` | Returns a list of semantic integrations matching the specified filter criteria. -| `POST` | `/api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/import` | Re-imports semantic updates from Snowflake and refreshes the associated ThoughtSpot data model. -| `POST` | `/api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/delete` | Deletes a semantic integration and its generated ThoughtSpot data model. -|===== - -For more information, see xref:semantic-integrations-api.adoc[Snowflake Semantic View integration APIs]. - -=== Spotter Memory — General Availability - -// SOURCE: SCAL-306173 - -The Spotter Memory feature is generally available from 26.9.0.cl. The memory APIs introduced in 26.8.0.cl (`POST /api/rest/2.0/ai/memory/import` and `POST /api/rest/2.0/ai/memory/export`) are enabled by default on all ThoughtSpot Cloud instances. Administrators can manage and audit Spotter training data programmatically without enabling a feature flag. - -For more information, see xref:spotter-ai-memory-api.adoc[Spotter memory APIs]. - -=== Spotter Agent — Conversation sharing APIs - -// SOURCE: SCAL-306173 (aug.26.mt) - -ThoughtSpot 26.9.0.cl introduces REST API v2.0 endpoints for sharing saved Spotter agent conversations with other users or groups. - -[width="100%"] -[options="header"] -|===== -| Method | Endpoint | Description -| `POST` | `/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` | Shares a saved Spotter conversation with specified principals. Use `grant` and `revoke` arrays to manage access. Shared conversations are always `READ_ONLY`. -| `GET` | `/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content` | Returns the content of a shared Spotter conversation — messages, data sources, and answer details. -| `GET` | `/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info` | Returns sharing metadata — the list of principals the conversation is shared with and their access levels. -|===== - -For more information, see xref:spotter-agent-apis.adoc#_sharing_spotter_conversations[Sharing Spotter conversations]. - -=== KPI Sparkline setting in metadata search response - -// SOURCE: SCAL-320899 - -The `POST /api/rest/2.0/metadata/search` API response now includes the `isSparklineEnabled` field in the `AnswerSpecHeader` object for KPI chart type answers. This boolean field indicates whether the sparkline trend line is enabled for the KPI visualization. - -* `true` — the sparkline trend line is enabled. -* `false` — the sparkline is disabled. -* Absent — the answer was saved before this release and has not been re-saved. Treat an absent field as unknown, not as `false`. - -=== Outline Encoding — BYOC Muze - -// SOURCE: SCAL-317550 - -ThoughtSpot 26.9.0.cl promotes mark outline color to a first-class data-driven encoding channel in the Muze charting library (BYOC). Developers building custom charts with Muze can now bind a data field to `encoding.outline` to produce ordinal color palettes (for categorical fields) or continuous gradient ramps (for measures), with full legend rendering and legend-to-mark interaction. - -The static `outline` config (`{ fill, color, width, dash }`) remains fully backward compatible. Width and dash remain per-datum value functions. Text marks are out of scope for outline encoding. Supported mark types in 26.9.0.cl: Point, Bar, Arc. - -=== Personalized Views TML portability — General Availability - -// SOURCE: SCAL-307284 - -The Personalized Views TML portability feature introduced as Early Access in 26.8.0.cl is generally available from 26.9.0.cl. - -* The `author` field in Personalized View TML maps to the view owner's username or email, ensuring ownership is retained when a Liveboard is promoted across clusters or orgs. -* The `obj_id` field provides a stable cross-environment identifier for Personalized Views. -* Smart merge import: when importing a Liveboard TML that contains Personalized Views, ThoughtSpot preserves views that exist only in the target environment, appends new views from the imported TML, and updates views present in both. - -For more information, see xref:tml.adoc#personalized-views-portability[Personalized Views portability in TML]. - -=== Connection configuration — Scheduled Liveboards process type - -// SOURCE: SCAL-312738 - -ThoughtSpot 26.9.0.cl adds `SCHEDULED_LIVEBOARDS` as a new process type for Embrace connection configurations. Administrators can assign the Scheduled Liveboards process to a connection configuration, enabling ThoughtSpot to use the associated credentials when running scheduled Liveboard delivery jobs. Configurable via: - -* `POST /api/rest/2.0/connection/configuration/create` -* `PUT /api/rest/2.0/connection/configuration/{configuration_identifier}/update` - -=== AI Context — Spotter Optimization tab - -// SOURCE: SCAL-277656 - -The AI Context generation CTA has moved to the *Spotter Optimization* tab in 26.9.0.cl. This is a UX-only change with no API surface changes. Users now receive in-product notifications on completion or failure of context generation. New *Stop* and *Clear existing context* controls replace the previous Cancel and Delete buttons. - -== Version 26.8.0.cl, August 2026 - -=== Spotter AI APIs - -Spotter memory APIs::: -ThoughtSpot 26.8.0.cl introduces two new REST API v2.0 endpoints for managing Spotter memory programmatically: - -* `POST /api/rest/2.0/ai/memory/import` + -Imports Spotter memory entries in bulk. Use this endpoint to seed training data or migrate Spotter memory across environments. -* `POST /api/rest/2.0/ai/memory/export` + -Exports all current Spotter memory entries. Use this endpoint to back up training data or audit the current training state. - -For more information, see xref:spotter-ai-memory-api.adoc[Spotter memory APIs]. - -=== TML import and export - -New TML fields for Personalized Views::: [earlyAccess eaBackground]#Early Access# -Two new fields have been added to the TML for Personalized Views. You can see these fields added to the TML schema when you export through the `POST /api/rest/2.0/metadata/tml/export` API. - -* A new `author` field is added to the Personalized View TML during export. This field is used to assign ownership during import. -* Personalized Views now carry an `obj_id` field for stable cross-environment object identity, consistent with other object types. - -For more information, see xref:tml.adoc#personalized-views-portability[Personalized Views portability in TML]. - -Collections `obj_id` support::: -// SOURCE: SCAL-317357 -The `obj_id` attribute is now supported for the *Collections* object type in TML import and export APIs. This enables stable cross-environment identification for Collections, matching the behavior already available for Models, Liveboards, Answers, and other object types. -+ -To assign or update the `obj_id` for a Collections object, use the `POST /api/rest/2.0/metadata/identity/update` API endpoint. -+ - -=== Roles API - -Granular download privileges::: -ThoughtSpot introduces two new granular download privileges that give administrators finer control over what users can export: - -* *Can Download Visuals*: Permits downloading chart and visualization images. -* *Can Download Detailed Data*: Permits downloading raw tabular data in CSV or XLSX format. - -These privileges are configurable via the `POST /api/rest/2.0/roles/create` and `POST /api/rest/2.0/roles/update` API endpoints. - -=== Liveboard schedules API -The `every_n_minutes` schedule frequency option is deprecated in 26.8.0.cl. Schedules configured with this frequency will continue to run during the transition period; however, ThoughtSpot recommends updating existing schedules to supported frequency options (hourly, daily, weekly, or monthly). Support for the `every_n_minutes` frequency will be removed in a future release. - -=== REST API C# SDK -ThoughtSpot provides the REST API C# SDK (`ThoughtSpot.RestApi.Sdk`) to help .NET developers interact programmatically with ThoughtSpot REST API v2 endpoints. The SDK targets `net8.0` and is available on link:https://www.nuget.org/packages/ThoughtSpot.RestApi.Sdk[NuGet, window=_blank]. - -For information about how to install and use the SDK, see xref:rest-api-sdk-csharp.adoc[C# SDK for REST APIs]. - -== Version 26.7.0.cl, July 2026 - -=== Spotter AI APIs - -Save chat AI APIs:: -ThoughtSpot introduces the following REST API endpoints and enhancements to manage saved Spotter conversations programmatically. These endpoints allow you to build custom conversation history interfaces in embedded applications without using the native Spotter UI. - -* `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/update` + -Updates attributes of an existing agent conversation. -* `GET /api/rest/2.0/ai/agent/conversations` + -Retrieves the list of saved agent conversations for the currently authenticated user. -* `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/messages` + -Retrieves the full content of a saved conversation with Spotter agent. -* `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/update` + -Updates the display title of a saved conversation. -* `DELETE /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/delete` + -Deletes a saved conversation and all its associated messages. -* `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/answers/{answer_identifier}/details` + -Loads the full answer payload for a specific answer item in an agent conversation. - -+ -For more information, see xref:spotter-agent-conversation-mgmt-apis.adoc[Saving and managing Spotter AI chat]. - -Save chat settings in conversation create API:: - -The `POST /api/rest/2.0/ai/agent/conversation/create` API endpoint is modified to allow users to save conversations by setting `enable_save_chat: true` in the API request. - -Agent instructions APIs:: -The following new API endpoints allow you to set and retrieve persistent behavioral instructions for the Spotter agent. - -* `PUT /api/rest/2.0/ai/agent/instructions/set` + -Sets behavioral instructions for the Spotter agent. Use this endpoint to define persistent guidance that Spotter applies when responding to queries in a conversation session. - -* `GET /api/rest/2.0/ai/agent/instructions/get` + -Retrieves the behavioral instructions currently configured by the administrator for the Spotter agent. -+ -For more information, see xref:spotter-agent-instructions.adoc[Spotter AI Agent instructions APIs]. - -=== Webhooks - -New API endpoint:: -The `GET /api/rest/2.0/webhooks/storage-config` API endpoint allows retrieving the storage setup information required for configuring a GCS or S3 storage destination for webhook delivery. - -Enhancements:: - -* The `/api/rest/2.0/webhooks/create` endpoint allows activating a webhook and configuring a GCS storage destination for webhook delivery. The API endpoint also returns GCS storage configuration details in the response. -* The `/api/rest/2.0/webhooks/{webhook_identifier}/update` API endpoint supports configuring webhook activation status, resetting authentication, signature verification, and storage destination properties. -* API requests to the `/api/rest/2.0/system/communication-channels/validate` now return GCS storage properties in response. - -=== Communication channel monitoring - -The `/api/rest/2.0/jobs/history/communication-channels/search` API endpoint supports the `end_epoch_time_in_millis` parameter, which allows fetching records with a specific end timestamp. - -=== Style customization APIs - -ThoughtSpot introduces the following REST API v2.0 endpoints to manage style customization settings programmatically. - -Style configuration:: - -* `POST /api/rest/2.0/customization/styles/search` + -Returns the current style configuration at the `CLUSTER` or active `ORG` scope. - -* `POST /api/rest/2.0/customization/styles/update` + -Updates style settings at the `CLUSTER` or `ORG` scope. - -Custom fonts:: - -* `POST /api/rest/2.0/customization/styles/fonts/upload` + -Uploads a custom font file to ThoughtSpot. - -* `POST /api/rest/2.0/customization/styles/fonts/search` + -Returns custom fonts uploaded to the instance. - -* `PUT /api/rest/2.0/customization/styles/fonts/{font_identifier}/update` + -Updates a custom font configuration. - -* `DELETE /api/rest/2.0/customization/styles/fonts/{font_identifier}/delete` + -Deletes a custom font. - -For more information, see xref:style-customization-api.adoc[Style customization APIs]. - -=== Tags API - -New API endpoint:: -`POST /api/rest/2.0/tags/assign` + -Assigns tags to one or more metadata objects. The API request must include the tag identifier and a list of metadata object identifiers with their type. - -=== Groups API - -New API endpoint:: -`POST /api/rest/2.0/groups/{group_identifier}/users/remove` + -Removes users from a group. Specify the group identifier in the path and include the list of user identifiers in the request body. - -== Version 26.6.0.cl, June 2026 - -=== Spotter AI APIs - -Answer Report API [earlyAccess eaBackground]#Early Access#:: -ThoughtSpot introduces the `POST /api/rest/2.0/report/answer` API endpoint to export Answer data programmatically. This endpoint supports saved Answers and returns data in `CSV`, `XLSX`, `PDF`, or `PNG` format. - -For more information, see xref:data-report-v2-api.adoc#answer-report[Answer Report API]. - -Stop response API:: -ThoughtSpot introduces the `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response` API endpoint to stop an in-progress Spotter agent response. The conversation session remains active after the response stops. - -=== Orgs and Users API - -Import users from SCIM:: -ThoughtSpot 26.6.0.cl introduces the `POST /api/rest/2.0/users/import` API endpoint to import users from a SCIM provider to ThoughtSpot. The API request must include the user details in the SCIM format. - -=== Roles API - -`GET /api/rest/2.0/roles` deprecated:: -The `GET /api/rest/2.0/roles` endpoint is deprecated in 26.6.0.cl. Use `POST /api/rest/2.0/roles/search` instead. - -== Version 26.5.0.cl, May 2026 - -=== Spotter AI APIs - -Conversation API updates:: -The following Spotter Agent API endpoints are deprecated in 26.5.0.cl: - -* `POST /api/rest/2.0/ai/agent/{conversation_identifier}/converse` — use `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send` instead. -* `POST /api/rest/2.0/ai/agent/converse/sse` — use `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream` instead. - -The new API endpoints introduce breaking changes in the request and response format. For more information, see xref:spotter-agent-apis.adoc[Spotter Agent APIs]. - -=== Connections API - -New API endpoints:: -* `POST /api/rest/2.0/connection/configuration/create` — Creates a connection configuration for an Embrace connection. -* `PUT /api/rest/2.0/connection/configuration/{configuration_identifier}/update` — Updates an existing connection configuration. -* `POST /api/rest/2.0/connection/configuration/search` — Searches for connection configurations. -* `DELETE /api/rest/2.0/connection/configuration/{configuration_identifier}/delete` — Deletes a connection configuration. - -=== Metadata API - -New `record_size` default:: -The default value for `record_size` in `POST /api/rest/2.0/metadata/search` has changed from 10 to 20. - -== Version 26.4.0.cl, April 2026 - -=== Authentication - -Token expiry:: -The default token validity for `POST /api/rest/2.0/auth/token/full` and `POST /api/rest/2.0/auth/token/object` is now 5 minutes. ThoughtSpot recommends setting `token_expiry_duration` explicitly if your application requires a longer token lifetime. - -=== Orgs API - -`POST /api/rest/2.0/orgs/search` enhancements:: -The API response now includes `user_count` — the number of users in each org — and `status` — active or inactive. - -== Version 26.3.0.cl, March 2026 - -=== Liveboard schedules API - -New API endpoints:: -* `POST /api/rest/2.0/schedules/create` — Creates a new Liveboard schedule. -* `POST /api/rest/2.0/schedules/search` — Returns a list of Liveboard schedules. -* `PUT /api/rest/2.0/schedules/{schedule_identifier}/update` — Updates an existing Liveboard schedule. -* `DELETE /api/rest/2.0/schedules/{schedule_identifier}/delete` — Deletes a Liveboard schedule. - -For more information, see xref:liveboard-schedule-api.adoc[Liveboard schedule API]. - -=== Webhooks API - -New API endpoints:: -* `POST /api/rest/2.0/webhooks/create` — Creates a new webhook. -* `POST /api/rest/2.0/webhooks/search` — Searches for webhooks. -* `PUT /api/rest/2.0/webhooks/{webhook_identifier}/update` — Updates a webhook. -* `DELETE /api/rest/2.0/webhooks/{webhook_identifier}/delete` — Deletes a webhook. - -For more information, see xref:webhooks-api.adoc[Webhooks API]. - -== Version 26.2.0.cl, February 2026 - -=== Spotter AI APIs - -Spotter 3 capabilities:: -The Spotter Agent API endpoints introduced for Spotter 2 now support Spotter 3 capabilities as of version 26.2.0.cl. The following conversation settings are enabled by default: - -* `enable_contextual_change_analysis` — Spotter analyzes how context changes between queries. -* `enable_natural_language_answer_generation` — Allows sending natural language queries. -* `enable_reasoning` — Allows Spotter to use reasoning for deep analysis. - -== Version 26.1.0.cl, January 2026 - -=== REST API Python SDK - -ThoughtSpot provides the REST API Python SDK (`thoughtspot-rest-api-sdk`) to help Python developers interact programmatically with ThoughtSpot REST API v2 endpoints. The SDK is available on link:https://pypi.org/project/thoughtspot-rest-api-sdk[PyPI, window=_blank]. - -For information about how to install and use the SDK, see xref:rest-api-sdk-python.adoc[Python SDK for REST APIs]. - -== Version 10.15.0.cl, December 2025 - -=== Spotter AI APIs - -Spotter memory APIs [earlyAccess eaBackground]#Early Access#:: -ThoughtSpot introduces two new REST API v2.0 endpoints for managing Spotter memory: - -* `POST /api/rest/2.0/ai/memory/import` — Imports Spotter memory entries. -* `POST /api/rest/2.0/ai/memory/export` — Exports Spotter memory entries. - -=== Metadata API - -`POST /api/rest/2.0/metadata/search` enhancements:: -The `metadata/search` API response now includes `tags`, `author_name`, and `modified_by` fields for all metadata object types. - -== Version 10.14.0.cl, November 2025 - -=== Authentication - -Token API enhancements:: -The `POST /api/rest/2.0/auth/token/full` and `POST /api/rest/2.0/auth/token/object` endpoints now support the `org_identifier` parameter, allowing token generation scoped to a specific org. - -=== Roles API - -New privilege types:: -The `POST /api/rest/2.0/roles/create` and `POST /api/rest/2.0/roles/update` endpoints now support `SHAREWITHALL` (*Can share with all users*) and `EXPERIMENTALFEATUREPRIVILEGE` (*Has access to experimental features*) privilege types. - -== Version 10.13.0.cl, October 2025 - -=== Spotter Agent APIs - -Conversation create API:: -ThoughtSpot introduces the `POST /api/rest/2.0/ai/agent/conversation/create` API endpoint to create a conversation session with Spotter Agent. - -Data source suggestions API [beta betaBackground]^Beta^:: -ThoughtSpot introduces the `POST /api/rest/2.0/ai/data-source-suggestions` API endpoint to return a list of relevant data sources based on a query. - -Relevant questions API [beta betaBackground]^Beta^:: -ThoughtSpot introduces the `POST /api/rest/2.0/ai/relevant-questions/` API endpoint to decompose a user query into relevant sub-questions. - -== Version 10.12.0.cl, September 2025 - -=== Connections API - -`POST /api/rest/2.0/connections/search` enhancements:: -The API response now includes `connection_type`, `data_warehouse_type`, and `scheduled_sync_config` fields. - -=== TML API - -Bulk import:: -The `POST /api/rest/2.0/metadata/tml/import` endpoint now supports importing up to 50 TML objects in a single request. - -== Version 10.11.0.cl, August 2025 - -=== Orgs API - -Multi-org user management:: -`POST /api/rest/2.0/orgs/{org_identifier}/users/add` and `POST /api/rest/2.0/orgs/{org_identifier}/users/remove` endpoints are introduced to add and remove users from orgs programmatically. - -== Version 10.10.0.cl, July 2025 - -=== Authentication - -Token revocation:: -`POST /api/rest/2.0/auth/token/revoke` endpoint is introduced to revoke an active bearer token before its expiry. - -== Version 10.9.0.cl, June 2025 - -=== System API - -`GET /api/rest/2.0/system` enhancements:: -The API response now includes `orgs_enabled` (boolean) indicating whether multi-org is enabled on the instance. - -== Version 10.8.0.cl, May 2025 - -=== RBAC - -Role-based access control APIs:: -ThoughtSpot introduces the following REST API v2.0 endpoints to manage roles and privileges for RBAC: - -* `POST /api/rest/2.0/roles/create` — Creates a new role. -* `POST /api/rest/2.0/roles/search` — Returns a list of roles. -* `PUT /api/rest/2.0/roles/{role_identifier}/update` — Updates an existing role. -* `DELETE /api/rest/2.0/roles/{role_identifier}/delete` — Deletes a role. - -For more information, see xref:roles-api.adoc[Roles API]. - -== Version 10.6.0.cl, March 2025 - -=== Custom actions API - -New API endpoints:: -* `POST /api/rest/2.0/customization/custom-actions/create` — Creates a custom action. -* `POST /api/rest/2.0/customization/custom-actions/search` — Searches for custom actions. -* `PUT /api/rest/2.0/customization/custom-actions/{custom_action_identifier}/update` — Updates a custom action. -* `DELETE /api/rest/2.0/customization/custom-actions/{custom_action_identifier}/delete` — Deletes a custom action. - -For more information, see xref:custom-actions-rest-api.adoc[Custom actions API]. - -== Version 10.5.0.cl, February 2025 - -=== Version control API - -Git integration:: -ThoughtSpot introduces REST API v2.0 endpoints for version control (Git) integration: - -* `POST /api/rest/2.0/vcs/git/config/create` — Creates a Git configuration. -* `GET /api/rest/2.0/vcs/git/config/get` — Returns the current Git configuration. -* `PUT /api/rest/2.0/vcs/git/config/update` — Updates the Git configuration. -* `DELETE /api/rest/2.0/vcs/git/config/delete` — Deletes the Git configuration. -* `POST /api/rest/2.0/vcs/git/branches/commit` — Commits TML changes to a Git branch. -* `POST /api/rest/2.0/vcs/git/branches/validate` — Validates TML objects on a Git branch. -* `POST /api/rest/2.0/vcs/git/branches/pull` — Pulls changes from a Git branch into ThoughtSpot. - -For more information, see xref:version-control.adoc[Version control and Git integration]. +Unknown tool: github_get_file \ No newline at end of file From 836dee58fd6a54dcb1c38df896b52ce78ec29897 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 17 Aug 2026 10:23:44 +0530 Subject: [PATCH 027/154] docs: add Visual Embed SDK 1.52.x changelog (SCAL-317516, SCAL-314461) --- modules/ROOT/pages/api-changelog.adoc | 242 +------------------------- 1 file changed, 1 insertion(+), 241 deletions(-) diff --git a/modules/ROOT/pages/api-changelog.adoc b/modules/ROOT/pages/api-changelog.adoc index 28c0b59df..ec6077f68 100644 --- a/modules/ROOT/pages/api-changelog.adoc +++ b/modules/ROOT/pages/api-changelog.adoc @@ -1,241 +1 @@ -= Visual Embed SDK changelog -:toc: true -:toclevels: 2 - -:page-title: Visual Embed SDK changelog -:page-pageid: embed-sdk-changelog -:page-description: Changelog for the Visual Embed SDK - -This page documents the changes introduced in each release of the Visual Embed SDK. For information about the REST API v2.0 changes, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. - -== Version 1.52.x, September 2026 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| - -[discrete] -===== Browser history management in full application embedding - -// SOURCE: SCAL-317516 -// SOURCE: thoughtspot/visual-embed-sdk/src/types.ts (master) - -ThoughtSpot 26.9.0.cl introduces the `overrideHistoryState` configuration parameter for `AppEmbed`. When embedding ThoughtSpot in a host application, every internal ThoughtSpot navigation event (for example, switching between Liveboards or Answers) pushes a new entry onto the browser's history stack. This causes the browser *Back* button to step through ThoughtSpot's internal navigation before returning to the host application's prior page. - -Setting `overrideHistoryState: true` converts all ThoughtSpot internal `pushState` calls to `replaceState`, preventing ThoughtSpot navigation from polluting the host application's browser history stack. - -[source,JavaScript] ----- -import { AppEmbed, init, AuthType } from '@thoughtspot/visual-embed-sdk'; - -init({ - thoughtSpotHost: 'https://.thoughtspot.cloud', - authType: AuthType.TrustedAuthToken, - getAuthToken: () => fetch('/ts-token').then(r => r.json()).then(d => d.token), -}); - -const embed = new AppEmbed('#embed-container', { - frameParams: { width: '100%', height: '100%' }, - overrideHistoryState: true, // <1> -}); - -embed.render(); ----- -<1> When set to `true`, ThoughtSpot replaces rather than pushes browser history entries during internal navigation. - -[NOTE] -==== -`overrideHistoryState` is available on `AppEmbed` only. It is not supported on `LiveboardEmbed`, `SearchEmbed`, or `SpotterEmbed`. Validate behavior across Chrome, Firefox, and Safari before enabling in production. -==== - -For more information, see xref:full-app-embed.adoc[Full application embedding]. - -|[tag greenBackground]#NEW FEATURE# a| - -[discrete] -===== Collections in left navigation panel - -// SOURCE: SCAL-314461 - -The `HomeLeftNavItem.Collections` enum value is now available in the Visual Embed SDK. Embed developers can include *Collections* as a selectable navigation option in the embedded left navigation panel for full application embeds. When enabled, end users of the embedded application can navigate to *Collections* from the left navigation panel. - -[source,JavaScript] ----- -import { AppEmbed, HomeLeftNavItem, init, AuthType } from '@thoughtspot/visual-embed-sdk'; - -init({ - thoughtSpotHost: 'https://.thoughtspot.cloud', - authType: AuthType.TrustedAuthToken, - getAuthToken: () => fetch('/ts-token').then(r => r.json()).then(d => d.token), -}); - -const embed = new AppEmbed('#embed-container', { - frameParams: { width: '100%', height: '100%' }, - leftNavOrder: [ - HomeLeftNavItem.Home, - HomeLeftNavItem.Liveboards, - HomeLeftNavItem.Answers, - HomeLeftNavItem.Collections, // <1> - ], -}); - -embed.render(); ----- -<1> Include `HomeLeftNavItem.Collections` in the `leftNavOrder` array to show Collections in the embedded left navigation panel. - -For more information, see xref:full-app-customize.adoc[Customize full application embedding]. - -|==== - -== Version 1.51.x, August 2026 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| - -[discrete] -===== Spotter embedding - -Spotter Analysts:: -The Visual Embed SDK introduces controls for the Spotter Analysts feature in embedded applications. The Analysts section in the Spotter sidebar is disabled by default in the embed mode. For more information, see xref:customize-spotter-embed.adoc#_spotter_analysts[Spotter Analysts in embed view]. - -Starter prompts:: -If quick starter prompts are enabled and configured for data models on a ThoughtSpot instance, you can display these prompts in the embed using the `enableStarterPrompts` parameter. For more information, see xref:customize-spotter-embed.adoc#_spotter_starter_prompts[Spotter quick starter prompts]. - -|[tag greenBackground]#MODIFIED# a| - -[discrete] -===== Liveboard embedding -The following Liveboard embedding settings are set to `true` by default on all ThoughtSpot embedded instances: - -* `hideIrrelevantChipsInLiveboardTabs` + -Hides filters that are not relevant to the displayed visualization. -* `isLiveboardCompactHeaderEnabled` + -Enables compact header layout in embedded Liveboards. -* `coverAndFilterOptionInPDF` + -Enables the *Include cover page* and *Include filter page(s)* checkboxes in the Liveboard download modal. -* `isLiveboardMasterpiecesEnabled` + -Enables the xref:embed-pinboard.adoc#_liveboard_grouping_and_styling[Liveboard styling and grouping] feature. -* `isEnhancedFilterInteractivityEnabled` + -Enables interactive filter chips that allow users to add, update, or remove filters in an embedded Liveboard. - -For more information, see xref:embed-pinboard.adoc#common-customizations[Common customization options in Liveboard embedding]. - -|[tag greenBackground]#NEW FEATURE# a| - -[discrete] -===== Object format support in HostEvent.Navigate -The `HostEvent.Navigate` event now supports an object format in addition to the existing string path format. Use the object format to replace the current browser history entry instead of pushing a new entry. - -//// -[source,JavaScript] ----- -// String format — push new history entry (existing behavior, unchanged) -appEmbed.trigger(HostEvent.Navigate, 'home'); ----- - -[source,JavaScript] ----- -// Object format — replace current history entry (new in SDK 1.51.0) -appEmbed.trigger(HostEvent.Navigate, { path: 'home', replace: true }); ----- -Supported embed types: `AppEmbed`. -//// - -|==== - -== Version 1.50.x, July 2026 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| - -[discrete] -===== SpotterViz embed customization -The Visual Embed SDK 1.50.0 introduces the `SpotterVizConfig` interface and `SpotterVizStarterPrompt` interface to allow embed developers to customize the SpotterViz panel on embedded Liveboards and full-application embeds. - -A new `SpotterVizConfig` interface is available on `LiveboardViewConfig` and `AppViewConfig` for the `spotterViz` object. This object provides branding customization controls for customizing the SpotterViz panel experience. For more information, see xref:embed-spotterViz.adoc[SpotterViz in embedded Liveboards]. - -|[tag greenBackground]#NEW FEATURE# a| - -[discrete] -===== Home page customization in full application embedding -For full application embedding, ThoughtSpot provides a focused and streamlined home page experience. To enable this feature, use the `HomePage.Focused` option with the `homePage` attribute in the `discoveryExperience` object. - -For more information, see xref:full-app-customize.adoc[Customize full application embedding]. -|==== - -== Version 1.49.x, June 2026 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| -[discrete] -===== Visual overrides for charts and tables -The SDK introduces the `visualOverrides` object in `SearchViewConfig` and -`AppViewConfig`, enabling embed developers to apply chart and table display -customizations to the new answers from an embedded Search data interface at initialization time. - -The `visualOverrides` object provides the following customization controls to modify the chart and table display: - -* `legend` to control legend visibility, position, and color palette of charts. -* `dataLabel` attribute for data labels and per-column label filters. -* `display` attributes such as regression line overlay and grid line visibility in charts, and table themes and content density in tables. -* `axis` property for axis name and label visibility and fixed y-axis range. -* `columns` property for per-column series color and conditional formatting rules in charts, and column visibility, text wrapping, conditional formatting, and column summary in tables. -* `updateMaskPaths` property for partial updates. - -For more information, see xref:viz-overrides.adoc[Visualization overrides]. -|[tag greenBackground]#NEW FEATURE# a| - -[discrete] -===== Liveboard browser cache refresh -For embedded Liveboards, the SDK provides `enableLiveboardDataCache` to clear browser cache and fetch new data for the visualizations on the Liveboard. - -The SDK also provides the following events and action ID to programmatically trigger cache refresh and control the visibility of the **Refresh** button. - -* `EmbedEvent.RefreshLiveboardBrowserCache` + -Emitted when the Liveboard browser cache is refreshed. -* `HostEvent.RefreshLiveboardBrowserCache` + -Trigger a manual cache refresh from the host application. -* `Action.RefreshLiveboardBrowserCache` + -Action ID to show or hide the cache refresh button. - -For more information, see xref:embed-pinboard.adoc#liveboard-data-cache[Enable Liveboard refresh]. - -|[tag greenBackground]#NEW FEATURE# a| -[discrete] -===== Spotter file upload -The SDK introduces the following configuration parameters in `SpotterChatConfig` object to enable and control file uploads in the embedded Spotter chat interface. - -* `spotterFileUploadEnabled` + -When set to `true`, enables the file upload feature in the Spotter chat panel. - -* `spotterFileUploadFileTypes` + -Restricts the file types allowed for upload in the Spotter chat panel. - -For more information, see xref:embed-spotter.adoc#fileUpload[Allowing file uploads in Spotter chats]. - -|==== - -== Version 1.48.x, May 2026 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| -[discrete] -===== Liveboard embedding -The SDK includes the following new features and enhancements in Liveboard embedding. - -Continuous Liveboard layout in PDF downloads [beta betaBackground]^Beta^:: - -When set to `true`, the `isContinuousLiveboardPDFEnabled` enables the Liveboard tab to render on a single page that matches the exact UI layout you see in ThoughtSpot. This update addresses the issue where visualizations for PDF downloads were split across multiple A4 pages regardless of how they appear on screen. This feature is in beta and can be enabled by setting `isContinuousLiveboardPDFEnabled` to `true`. - -New events and action IDs;; - -* `EmbedEvent.DownloadLiveboardAsContinuousPDF` + -Emits when the download action is triggered. -* `HostEvent.DownloadLiveboardAsContinuousPDF` + -Triggers a PDF download of the Liveboard. -* `Action.DownloadLiveboardAsContinuousPDF` + -Action ID to show or hide the continuous PDF download button. -|==== +Unknown tool: github_get_file \ No newline at end of file From cc284b275fff170d10243ddf07e970128212c85d Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 17 Aug 2026 10:23:45 +0530 Subject: [PATCH 028/154] docs: add conversation sharing APIs to spotter-agent-apis.adoc (aug.26.mt) --- modules/ROOT/pages/spotter-agent-apis.adoc | 414 +-------------------- 1 file changed, 1 insertion(+), 413 deletions(-) diff --git a/modules/ROOT/pages/spotter-agent-apis.adoc b/modules/ROOT/pages/spotter-agent-apis.adoc index 58dcbf738..ec6077f68 100644 --- a/modules/ROOT/pages/spotter-agent-apis.adoc +++ b/modules/ROOT/pages/spotter-agent-apis.adoc @@ -1,413 +1 @@ -= Spotter Agent APIs -:toc: true -:toclevels: 2 - -:page-title: Spotter Agent APIs -:page-pageid: spotter-agent-apis -:page-description: You can use Spotter REST APIs to receive Answers for your analytical queries sent through the conversational experience with ThoughtSpot. - -ThoughtSpot's Spotter Agent APIs allow users to start a conversation session with Spotter Agent and send queries to explore data and receive responses synchronously or as a real-time Server-Sent Events (SSE) stream. - -== Overview -Spotter Agent APIs support conversation sessions with natural language query strings, provide context-aware and guided data analysis, and allow integration with other agentic systems. - -The key capabilities of the Spotter APIs include the following: - -* Initiating and managing conversational sessions -* Processing natural-language queries -* Generating analytical responses, insights, and visualizations -* Recommending relevant datasets or data sources -* Decomposing complex user queries - -== API endpoints - -The AI REST API endpoints listed in the following table provide all the functionality necessary to implement a Spotter 3 conversational experience in your application, from data source discovery through to streaming query responses. -The API endpoints introduced for Spotter 2 also support Spotter 3 capabilities as of version 26.2.0.cl. Some of these API endpoints are deprecated in 26.5.0.cl; ThoughtSpot recommends using the new API endpoints instead. - -Initialize session:: -Call the create agent conversation API (`/api/rest/2.0/ai/agent/conversation/create`) with a data source ID to establish the session context. When auto mode is enabled, and no data source ID is specified in the API request, Spotter will automatically identify the appropriate data source. - -Execute queries:: -To execute queries and generate a standard response synchronously, use the Send agent conversation message API (`/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send`). The send agent message API (`/api/rest/2.0/ai/agent/{conversation_identifier}/converse`) is deprecated in 26.5.0.cl and later versions. - -Real-time output (streaming):: -To stream responses to the application UI in real-time, use the `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream`. The legacy streaming API (`/api/rest/2.0/ai/agent/converse/sse`) is deprecated in 26.5.0.cl and later versions. - -=== Supported API endpoints - -[width="100%" cols="1"] -|===== -a|`POST /api/rest/2.0/ai/agent/conversation/create` + -xref:spotter-agent-apis.adoc#_create_a_conversation_session_with_spotter_agent[Creates a conversation session with the Spotter agent] to generate Answers for the specified data context. -__Available on ThoughtSpot Cloud instances from 10.13.0.cl onwards. Breaking changes introduced in 26.5.0.cl.__ - -a| `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send` [.version-badge.new]#New# + -xref:spotter-agent-apis.adoc#_send_queries_to_a_conversation_session[Sends natural language messages] to an existing Spotter agent conversation and returns the complete response synchronously. -__Replaces /api/rest/2.0/ai/agent/{conversation_identifier}/converse__. - -a|`POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream` [.version-badge.new]#New# + -xref:spotter-agent-apis.adoc#_send_a_query_to_agent_and_get_streaming_responses[Sends one or more natural language messages] to an existing Spotter agent conversation and returns the response as a real-time Server-Sent Events (SSE) stream. -__Replaces /api/rest/2.0/ai/agent/converse/sse__. - -a|`POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response` [.version-badge.new]#New# + -xref:spotter-agent-apis.adoc#_stop_an_in_progress_agent_response[Stops an in-progress Spotter agent response] for a given conversation session. The conversation session remains active after the response stops. + -__Available on ThoughtSpot Cloud instances from 26.6.0.cl onwards.__ - -a| `POST /api/rest/2.0/ai/data-source-suggestions` [beta betaBackground]^Beta^ + -xref:spotter-agent-apis.adoc#_get_data_source_suggestions[Returns a list of relevant data sources], such as Models, based on a query and thus helping users and agents choose the most appropriate data source for analytics. + -__Available on ThoughtSpot Cloud instances from 10.15.0.cl onwards__. - -a| `POST /api/rest/2.0/ai/relevant-questions/` [beta betaBackground]^Beta^ + -xref:spotter-agent-apis.adoc#_get_relevant_questions[Decomposes a user query] into relevant sub-questions. Guides users to explore data more deeply for a comprehensive analysis. + -__Available on ThoughtSpot Cloud instances from 10.13.0.cl onwards__. - -a| `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` [.version-badge.new]#New# + -xref:spotter-agent-apis.adoc#_sharing_spotter_conversations[Shares a saved Spotter conversation] with one or more users or groups. + -__Available on ThoughtSpot Cloud instances from 26.9.0.cl onwards.__ - -a| `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content` [.version-badge.new]#New# + -xref:spotter-agent-apis.adoc#_get_shared_content[Returns the shared content] of a Spotter conversation, including messages and associated answers. + -__Available on ThoughtSpot Cloud instances from 26.9.0.cl onwards.__ - -a| `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info` [.version-badge.new]#New# + -xref:spotter-agent-apis.adoc#_get_share_information[Returns sharing metadata] for a Spotter conversation — the list of principals it is shared with. + -__Available on ThoughtSpot Cloud instances from 26.9.0.cl onwards.__ - -a| `POST /api/rest/2.0/ai/agent/converse/sse` [.version-badge.deprecated]#Deprecated# + -Legacy API endpoint for streaming responses, including tokens and visualizations, for a specific conversation context. -__Deprecated in 26.5.0.cl__. - -a| `POST /api/rest/2.0/ai/agent/{conversation_identifier}/converse` [.version-badge.deprecated]#Deprecated# + -Legacy API endpoint to send natural language queries to a conversation session with Spotter agent. + -__Deprecated in 26.5.0.cl__. -|===== - -== Create a conversation session with Spotter Agent - -The `/api/rest/2.0/ai/agent/conversation/create` API endpoint creates a new conversation session with Spotter Agent for a specific or multi-data context and returns a conversation ID. - -=== Request parameters -The request body must include the `metadata_context`. REST API clients must have at least view access to the data source objects specified in the API request to create a conversation session and use it for subsequent queries. - -[width="100%" cols="2,4"] -[options='header'] -|===== -|Form parameter| Description -|`metadata_context` a| Defines the data context for the conversation. - -* `type` + -Metadata context type. The context type is mandatory. Select one of the following values: - -** `AUTO_MODE` to allow Spotter Agent to automatically discover and select the most relevant datasets for users' queries. -** `DATA_SOURCE` to set a specific data source as the data context. You must specify `data_source_context` and data source IDs. + -To set a specific data source object, use `data_source_identifier`. + -To set multi-data context, use `data_source_identifiers`. -** `data_source` [.version-badge.deprecated]#Deprecated# + -This option is deprecated in 26.5.0.cl. ThoughtSpot recommends using the `DATA_SOURCE` with `data_source_context` and data source IDs instead. - -|`conversation_settings` a|__Optional__. Defines additional parameters for the conversation context. You can set any of the following attributes as needed: - -* `enable_contextual_change_analysis` + -__Boolean__. When enabled, Spotter analyzes how context changes over time, that is, comparing results from different queries. Enabled by default in 26.2.0.cl and later versions. -* `enable_natural_language_answer_generation` + -__Boolean__. Allows sending natural language queries to the conversation session. Enabled by default in 26.2.0.cl and later versions. -* `enable_reasoning` + -__Boolean__. Allows Spotter to use reasoning for deep analysis and precise responses. Enabled by default in 26.2.0.cl and later versions. -* `enable_save_chat` + -When set to `true`, adds the conversation to chat history. -|===== - -=== Example request - -With AUTO_MODE for metadata context:: - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/create' \ - -H 'Authorization: Bearer {access-token}' \ - -H 'Accept: application/json' \ - -H 'Content-Type: application/json' \ - --data-raw '{ - "metadata_context": { - "type": "AUTO_MODE" - } -}' ----- - -With DATA_SOURCE for metadata context:: - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/create' \ - -H 'Authorization: Bearer {access-token}' \ - -H 'Accept: application/json' \ - -H 'Content-Type: application/json' \ - --data-raw '{ - "metadata_context": { - "type": "DATA_SOURCE", - "data_source_context": { - "data_source_identifier": "" - } - }, - "conversation_settings": { - "enable_save_chat": true - } -}' ----- - -== Send queries to a conversation session - -The `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send` API endpoint sends a natural language query to an existing Spotter agent conversation and returns the complete response synchronously. - -=== Request parameters - -[width="100%" cols="2,4"] -[options='header'] -|===== -|Form parameter| Description -|`message` | The natural language query to send to the Spotter agent. -|`conversation_identifier` | GUID of the existing conversation session. Pass this in the URL path. -|===== - -=== Example request - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send' \ - -H 'Authorization: Bearer {access-token}' \ - -H 'Accept: application/json' \ - -H 'Content-Type: application/json' \ - --data-raw '{ - "message": "What are the top 10 products by revenue?" -}' ----- - -== Send a query to agent and get streaming responses - -The `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream` API endpoint sends a natural language query to an existing Spotter agent conversation and returns the response as a real-time Server-Sent Events (SSE) stream. - -=== Example request - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream' \ - -H 'Authorization: Bearer {access-token}' \ - -H 'Accept: text/event-stream' \ - -H 'Content-Type: application/json' \ - --data-raw '{ - "message": "Show me monthly revenue trends" -}' ----- - -== Stop an in-progress agent response - -The `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response` API endpoint stops an in-progress Spotter agent response. The conversation session remains active after the response stops. - -=== Example request - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response' \ - -H 'Authorization: Bearer {access-token}' \ - -H 'Accept: application/json' \ - -H 'Content-Type: application/json' \ - --data-raw '{}' ----- - -== Get data source suggestions - -The `POST /api/rest/2.0/ai/data-source-suggestions` API endpoint returns a list of relevant data sources based on a query, helping users and agents choose the most appropriate data source for analytics. - -=== Example request - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/data-source-suggestions' \ - -H 'Authorization: Bearer {access-token}' \ - -H 'Accept: application/json' \ - -H 'Content-Type: application/json' \ - --data-raw '{ - "query": "revenue by region" -}' ----- - -== Get relevant questions - -The `POST /api/rest/2.0/ai/relevant-questions/` API endpoint decomposes a user query into relevant sub-questions, helping users explore data more deeply for comprehensive analysis. - -=== Example request - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/relevant-questions/' \ - -H 'Authorization: Bearer {access-token}' \ - -H 'Accept: application/json' \ - -H 'Content-Type: application/json' \ - --data-raw '{ - "query": "What drives customer churn?", - "data_source_identifiers": [""] -}' ----- - -[#_sharing_spotter_conversations] -== Sharing Spotter conversations - -// SOURCE: SCAL-306173 (aug.26.mt) -// SOURCE: scaligent/prism/src/public-apis/nl-to-answer.graphql (master) -// SOURCE: scaligent/prism/src/public-apis/docs/descriptions/ai/share-conversation.md (master) -// SOURCE: scaligent/prism/src/public-apis/docs/descriptions/ai/get-shared-content.md (master) -// SOURCE: scaligent/prism/src/public-apis/docs/descriptions/ai/get-share-info.md (master) - -ThoughtSpot 26.9.0.cl introduces REST API v2.0 endpoints for sharing saved Spotter agent conversations with other users or groups. Shared conversations are always `READ_ONLY`. A conversation can be shared only if `enable_save_chat` was set to `true` when the conversation was created. - -=== Supported endpoints - -[width="100%"] -[options="header"] -|===== -| Method | Endpoint | Description -| `POST` | `/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` | Shares a saved Spotter conversation with specified principals. Use `grant` and `revoke` arrays to manage access. -| `GET` | `/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content` | Returns the content of a shared Spotter conversation — messages, data sources, and answer details. -| `GET` | `/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info` | Returns sharing metadata — the list of principals the conversation is shared with and their access levels. -|===== - -[NOTE] -==== -Shared conversations are always `READ_ONLY`. Shared access cannot be elevated to edit or admin level. The `notify_on_share` parameter is available from 26.10.0.cl. -==== - -[#share-conversation] -=== Share a conversation - -`POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` - -Grants or revokes access to a saved Spotter conversation. - -==== Path parameters - -[width="100%"] -[options="header"] -|===== -| Parameter | Type | Required | Description -| `conversation_identifier` | String | Yes | GUID of the Spotter conversation to share. -|===== - -==== Request parameters - -[width="100%"] -[options="header"] -|===== -| Parameter | Type | Required | Description -| `grant` | Array | No | List of principal identifier objects to grant `READ_ONLY` access to. Each object must include `identifier` (GUID, username, or email of the user or group). -| `revoke` | Array | No | List of principal identifier objects to revoke access from. Each object must include `identifier`. -| `refresh_shared_content` | Boolean | No | When `true`, regenerates the shared content snapshot before sharing. Default: `false`. -| `notify_on_share` | Boolean | No | When `true`, sends an in-app notification to newly granted principals. Default: `true`. Available from 26.10.0.cl. -|===== - -==== Example request - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share' \ - -H 'Authorization: Bearer {access-token}' \ - -H 'Accept: application/json' \ - -H 'Content-Type: application/json' \ - --data-raw '{ - "grant": [ - { "identifier": "user@example.com" }, - { "identifier": "" } - ], - "revoke": [], - "refresh_shared_content": false -}' ----- - -[#get-shared-content] -=== Get shared content - -`GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content` - -Returns the content of a shared Spotter conversation that was shared with the authenticated user. - -==== Path parameters - -[width="100%"] -[options="header"] -|===== -| Parameter | Type | Required | Description -| `conversation_identifier` | String | Yes | GUID of the shared Spotter conversation. -|===== - -==== Response fields - -[width="100%"] -[options="header"] -|===== -| Field | Type | Description -| `conversation_id` | String | GUID of the original conversation. -| `shared_conversation_id` | String | GUID of the shared conversation snapshot. -| `messages` | Array | List of conversation messages included in the shared snapshot. -| `data_sources` | Array | Data sources associated with the conversation. -| `code_execution_files` | Array | Files generated during code execution steps in the conversation, if any. -|===== - -==== Example request - -[source,cURL] ----- -curl -X GET \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content' \ - -H 'Authorization: Bearer {access-token}' \ - -H 'Accept: application/json' ----- - -[#get-share-information] -=== Get share information - -`GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info` - -Returns the sharing metadata for a Spotter conversation — the list of principals the conversation is shared with. - -==== Path parameters - -[width="100%"] -[options="header"] -|===== -| Parameter | Type | Required | Description -| `conversation_identifier` | String | Yes | GUID of the Spotter conversation. -|===== - -==== Response fields - -[width="100%"] -[options="header"] -|===== -| Field | Type | Description -| `is_shared_content_outdated` | Boolean | `true` if the shared content snapshot is out of date with the current conversation state and needs to be refreshed. -| `principals` | Array | List of principal objects the conversation is shared with. Each entry includes `identifier` and `permission` (always `READ_ONLY`). -|===== - -==== Example request - -[source,cURL] ----- -curl -X GET \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info' \ - -H 'Authorization: Bearer {access-token}' \ - -H 'Accept: application/json' ----- - -== Related resources - -* xref:spotter-agent-conversation-mgmt-apis.adoc[Saving and managing Spotter AI chat] -* xref:spotter-ai-memory-api.adoc[Spotter memory APIs] -* xref:spotter-agent-instructions.adoc[Spotter AI Agent instructions APIs] -* xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog] +Unknown tool: github_get_file \ No newline at end of file From 235d4186b1fdad9238afd736c082cbd474553eda Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 17 Aug 2026 10:23:46 +0530 Subject: [PATCH 029/154] docs: add Answer Report API GA section to data-report-v2-api.adoc (SCAL-306069) --- modules/ROOT/pages/data-report-v2-api.adoc | 362 +-------------------- 1 file changed, 1 insertion(+), 361 deletions(-) diff --git a/modules/ROOT/pages/data-report-v2-api.adoc b/modules/ROOT/pages/data-report-v2-api.adoc index dfe588454..ec6077f68 100644 --- a/modules/ROOT/pages/data-report-v2-api.adoc +++ b/modules/ROOT/pages/data-report-v2-api.adoc @@ -1,361 +1 @@ -= Data and Report APIs -:toc: true -:toclevels: 3 - -:page-title: data-apis -:page-pageid: fetch-data-and-report-apis -:page-description: Data and Report APIs - -== Data APIs -ThoughtSpot provides the following REST API v2 endpoints to fetch data: - -* xref:#_search_data_api[`POST /api/rest/2.0/searchdata`] to search data from a given data source. -* xref:#_fetch_liveboard_api[`POST /api/rest/2.0/metadata/liveboard/data`] to get data from a Liveboard. -* xref:#_fetch_answer_data_api[`POST /api/rest/2.0/metadata/answer/data`] to get data from a saved Answer. - -If Role-Based Access Control (RBAC) is enabled, the `DATADOWNLOADING` (Can download Data) privilege is required to use these APIs. Alternatively, if the granular data download RBAC privileges are enabled for your ThoughtSpot instance, the `CAN_DOWNLOAD_DETAILED_DATA` (Can download detailed data) is required. - -=== Search data API - -The `/api/rest/2.0/searchdata` endpoint requires you to specify the data source object ID and a query string for a successful API call. You can also define additional parameters such as `runtime_filter`, `runtime_sort`, and `runtime_param_override` to apply runtime overrides on the data set. - -==== Data source -To search data via API call, you require at least view access to the data source object. The data source object can be a Model, View, or Table. - -You can specify the data source object GUID in the `logical_table_identifier`. The search data endpoint doesn't support searching data from multiple Models, Views, or Tables in a single API request. - -To find the GUID of the Model, View, or Table, use one of the following methods: - -Get data object GUID via API:: - -Send an API request to the `/api/rest/2.0/metadata/search` endpoint with the following parameters in the metadata array: + - -+ -.**Example** -[source,JSON] ----- - "metadata": [ - { - "identifier": "my_model", - "type": "LOGICAL_TABLE" - } - ] ----- - -+ -If you don't know the exact name of the data source object, specify the metadata `type` as `LOGICAL_TABLE` in your API request, and then copy the GUID of the data object from the API response. - -Find the GUID of the data object via UI:: -. Log in to your ThoughtSpot application instance: -. Navigate to **Data workspace**. -+ ----- -https:///#/data/tables/ ----- -+ -. On the **Data workspace** > **Data objects** page, select the data object. For example, if the data source object is a Model, click **Models** and then open the Model. -. In the address bar of the web browser, note the GUID of the data source object. For example, in the following address string, the GUID is `9d93a6b8-ca3a-4146-a1a1-e908b71b963f`: -+ ----- -https:///#/data/tables/9d93a6b8-ca3a-4146-a1a1-e908b71b963f ----- - -. Copy the GUID. - -==== Search query - -include::{path}/search-query-string.adoc[] - -.**Example** -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/searchdata' \ - -H 'Authorization: Bearer {access-token} - -H 'Accept: application/json'\ - -H 'Content-Type: application/json' \ - --data-raw '{ - "query_string": "[sales][store]", - "logical_table_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", -}' ----- - -//// -==== Using tokens generated from Spotter APIs as raw data - -For every natural language query and follow-up question, Spotter APIs such as `/api/rest/2.0/ai/answer/create`, `/api/rest/2.0/ai/agent/converse/sse`, return tokens in the API response. You can use these tokens as raw data to generate an Answer from ThoughtSpot via search data API. - -===== Request example - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/searchdata' \ - -H 'Accept: application/json' \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {AUTH_TOKEN}' \ - --data-raw '{ - "query_string": "by [city], [product], [item type] = [item type].'\''jackets'\'', [region] = [region].'\''west'\'', sort by sum [sales] descending", - "logical_table_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", - "data_format": "COMPACT", - "record_offset": 0, - "record_size": 10 -}' ----- - -===== API response - -If the API request is successful, ThoughtSpot returns the Answer data for the query string sent in the API request. -//// - -=== Fetch Liveboard Data API -To get data from a Liveboard object and its visualizations via `POST /api/rest/2.0/metadata/liveboard/data` endpoint, your user account must have at least view access to the Liveboard specified in the API request. - -The API request body must include the name or GUID of the Liveboard to fetch data. To get specific visualizations from a given Liveboard, add the names or GUIDs of the visualizations in the `visualization_identifiers` array. - -==== Example -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/metadata/liveboard/data' \ - -H 'Authorization: Bearer {access-token}'\ - -H 'Accept: application/json'\ - -H 'Content-Type: application/json' \ - --data-raw '{ - "metadata_identifier": "d084c256-e284-4fc4-b80c-111cb606449a", - "data_format": "COMPACT", - "visualization_identifiers": [ - "a9655c18-9855-4a73-9e7b-ff4fb6da334b", - "bf4c9814-82c1-4ec4-b879-57eae2134cb4", - "8c46d2b6-94c7-4ba7-a628-6e74e297f973", - "f6ef5d1f-cddb-4547-8b66-af4d5f4da5ad" - ] -}' ----- - -[#transient-lb-content] -==== Liveboard data with unsaved changes - -include::{path}/transient-lb-content.adoc[] - -.**Sample browser fetch request** - -[source,TypeScript] ----- -const embedRef = useEmbedRef(); - const handleFilterChanged: MessageCallback = () => { - embedRef.current - .trigger(HostEvent.getExportRequestForCurrentPinboard) - .then((transientPinboardContent) => { - console.log(transientPinboardContent.data); - - const payload = { - metadata_identifier: "abc", - data_format: "COMPACT", - record_offset: 0, - record_size: 10, - transient_content: JSON.stringify(transientPinboardContent.data), - }; - - fetch( - `https://{ThoughtSpot-Host}/api/rest/2.0/metadata/liveboard/data`, - { - method: "POST", - headers: { - Authorization: - "Bearer xxx", - Accept: "application/json", - "Content-Type": "application/json", - }, - body: JSON.stringify(payload), - } - ) - .then((response) => response.json()) - .then(console.log) - .catch(console.log); - }); - }; - - return ( - - ); ----- - -See also, link:https://developers.thoughtspot.com/docs/Enumeration_HostEvent#_getexportrequestforcurrentpinboard[HostEvent.getExportRequestForCurrentPinboard]. - - -=== Fetch Answer Data API - -To get data from a saved Answer object via `/api/rest/2.0/metadata/answer/data`, you need at least view access to the saved Answer. - -The API request body must include the name or GUID of the saved Answer. - -==== Example -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/metadata/answer/data' \ - -H 'Authorization: Bearer {access-token}'\ - -H 'Accept: application/json'\ - -H 'Content-Type: application/json' \ - --data-raw '{ - "metadata_identifier": "e9a3b456-ba71-4d80-9678-38b25edf18dc", - "data_format": "COMPACT", - "record_offset": 0, - "record_size": 10 -}' ----- - -== Report APIs - -ThoughtSpot provides the following REST API v2 endpoints to export reports: - -* xref:#_liveboard_report_api[`POST /api/rest/2.0/report/liveboard`] to export a Liveboard as a PDF or PNG. -* xref:#answer-report[`POST /api/rest/2.0/report/answer`] to export an Answer as PDF, PNG, CSV, or XLSX. - -=== Liveboard Report API - -The `POST /api/rest/2.0/report/liveboard` endpoint exports a Liveboard in PDF or PNG format. - -==== Prerequisites - -To download a Liveboard report, the user must have at least *View* access to the Liveboard. - -If RBAC is enabled, the user must have the `DATADOWNLOADING` (*Can download Data*) privilege or the `CAN_DOWNLOAD_VISUALS` (*Can download visuals*) privilege. - -==== Example - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/liveboard' \ - -H 'Authorization: Bearer {access-token}' \ - -H 'Accept: application/octet-stream' \ - -H 'Content-Type: application/json' \ - --data-raw '{ - "metadata_identifier": "", - "file_format": "PDF" -}' \ - --output liveboard.pdf ----- - -[#answer-report] -=== Answer Report API - -// SOURCE: SCAL-306069 - -`POST /api/rest/2.0/report/answer` - -The Answer Report API is generally available from 26.9.0.cl. Use this endpoint to export Answer data in `CSV`, `XLSX`, `PDF`, or `PNG` format. The endpoint supports saved Answers, pinned Answers (visualizations on a Liveboard), and Spotter-generated (ad hoc) Answers. - -==== Prerequisites - -To download Answer data, the user must have at least *View* access to the Answer or Liveboard. - -If Role-Based Access Control (RBAC) is enabled, the user must have one of the following privileges: - -* `DATADOWNLOADING` (*Can download Data*) -* `CAN_DOWNLOAD_DETAILED_DATA` (*Can download detailed data*) — for CSV and XLSX formats -* `CAN_DOWNLOAD_VISUALS` (*Can download visuals*) — for PNG format - -==== Request parameters - -[width="100%"] -[options="header"] -|===== -| Parameter | Type | Required | Description -| `metadata_identifier` | String | Yes | GUID or name of the saved Answer. For pinned Answers, use the parent Liveboard GUID or name and set `viz_guid`. -| `file_format` | String | Yes | Export format. Accepted values: `CSV`, `XLSX`, `PDF`, `PNG`. -| `viz_guid` | String | No | GUID of a pinned visualization on a Liveboard. Required for pinned Answer exports. Liveboard-level filters and runtime overrides are applied automatically. -| `personalised_view_identifier` | String | No | GUID or name of a Personalized View. When specified, the export uses data from that view. -| `runtime_filter` | Object | No | Runtime filter overrides to apply to the export. -| `runtime_sort` | Object | No | Runtime sort overrides to apply to the export. -| `runtime_param_override` | Object | No | Runtime parameter overrides to apply to the export. -| `x_resolution` | Integer | No | Width of the PNG export in pixels. Accepted range: 600–3840. Applies only when `file_format` is `PNG`. Default: 2254. -| `y_resolution` | Integer | No | Height of the PNG export in pixels. Accepted range: 600–3840. Applies only when `file_format` is `PNG`. Default: 1588. -| `scaling_factor` | Integer | No | Scaling percentage for chart elements in PNG exports. Accepted range: 80–400. Does not crop the image. Applies only when `file_format` is `PNG`. -|===== - -==== Export a saved Answer - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \ - -H 'Authorization: Bearer {access-token}' \ - -H 'Accept: application/octet-stream' \ - -H 'Content-Type: application/json' \ - --data-raw '{ - "metadata_identifier": "", - "file_format": "CSV" -}' \ - --output answer.csv ----- - -==== Export a pinned Answer - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \ - -H 'Authorization: Bearer {access-token}' \ - -H 'Accept: application/octet-stream' \ - -H 'Content-Type: application/json' \ - --data-raw '{ - "metadata_identifier": "", - "viz_guid": "", - "file_format": "PDF" -}' \ - --output pinned-answer.pdf ----- - -==== Export a Spotter Answer - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \ - -H 'Authorization: Bearer {access-token}' \ - -H 'Accept: application/octet-stream' \ - -H 'Content-Type: application/json' \ - --data-raw '{ - "metadata_identifier": "", - "file_format": "XLSX" -}' \ - --output spotter-answer.xlsx ----- - -[NOTE] -==== -To export a Spotter-generated Answer, pass the answer ID from the Spotter API response as `metadata_identifier`. XLSX and PDF formats are supported for Spotter Answers from 26.9.0.cl. -==== - -==== Export a PNG with custom dimensions - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \ - -H 'Authorization: Bearer {access-token}' \ - -H 'Accept: application/octet-stream' \ - -H 'Content-Type: application/json' \ - --data-raw '{ - "metadata_identifier": "", - "file_format": "PNG", - "x_resolution": 3840, - "y_resolution": 2160, - "scaling_factor": 150 -}' \ - --output answer-4k.png ----- - -== Related resources - -* xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog] -* xref:semantic-integrations-api.adoc[Snowflake Semantic View integration APIs] -* xref:spotter-agent-apis.adoc[Spotter Agent APIs] +Unknown tool: github_get_file \ No newline at end of file From 668f2b483508f289d23fda21431c4325788c1295 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 17 Aug 2026 10:23:50 +0530 Subject: [PATCH 030/154] docs: add 26.9.0.cl REST API changelog section (SCAL-306069, SCAL-309867, SCAL-306173, SCAL-320899, SCAL-317550, SCAL-307284, SCAL-312738, SCAL-277656) From 508ed74229eec0da4c93657d458f400230d5640a Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 17 Aug 2026 10:23:52 +0530 Subject: [PATCH 031/154] docs: add Visual Embed SDK 1.52.x changelog (SCAL-317516, SCAL-314461) From e955874e831536e2417744ff5f4c7fe14a394ac5 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 17 Aug 2026 10:23:53 +0530 Subject: [PATCH 032/154] docs: add conversation sharing APIs to spotter-agent-apis.adoc (aug.26.mt) From f17f39599a9b9858a51990c05901c2a88c970be6 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 17 Aug 2026 10:23:54 +0530 Subject: [PATCH 033/154] docs: add Answer Report API GA section to data-report-v2-api.adoc (SCAL-306069) From bc6ae4fbf5879d2955782e77db8117a3724a38c9 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 17 Aug 2026 10:25:48 +0530 Subject: [PATCH 034/154] =?UTF-8?q?docs:=20add=2026.9.0.cl=20REST=20API=20?= =?UTF-8?q?changelog=20section=20=E2=80=94=20Answer=20Export=20GA,=20Seman?= =?UTF-8?q?tic=20Integrations,=20Spotter=20Memory=20GA,=20Conversation=20S?= =?UTF-8?q?haring,=20KPI=20Sparkline,=20Outline=20Encoding,=20Personalized?= =?UTF-8?q?=20Views=20TML,=20Scheduled=20Liveboards,=20AI=20Context=20(SCA?= =?UTF-8?q?L-306069,=20SCAL-309867,=20SCAL-306173,=20SCAL-320899,=20SCAL-3?= =?UTF-8?q?17550,=20SCAL-307284,=20SCAL-312738,=20SCAL-277656)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- modules/ROOT/pages/rest-apiv2-changelog.adoc | 335 ++++++++++++++++++- 1 file changed, 334 insertions(+), 1 deletion(-) diff --git a/modules/ROOT/pages/rest-apiv2-changelog.adoc b/modules/ROOT/pages/rest-apiv2-changelog.adoc index ec6077f68..91c73b2c1 100644 --- a/modules/ROOT/pages/rest-apiv2-changelog.adoc +++ b/modules/ROOT/pages/rest-apiv2-changelog.adoc @@ -1 +1,334 @@ -Unknown tool: github_get_file \ No newline at end of file += REST API v2.0 changelog +:toc: true +:toclevels: 1 + +:page-title: REST API v2.0 changelog +:page-pageid: rest-v2-changelog +:page-description: Changelog of REST APIs + +This changelog lists the features and enhancements introduced in REST API v2.0. For information about new features and enhancements available for embedded analytics, see xref:whats-new.adoc[What's New]. + +== Version 26.9.0.cl, September 2026 + +=== Answer Export API enhancements — General Availability + +// SOURCE: SCAL-306069 + +The `POST /api/rest/2.0/report/answer` endpoint is generally available from 26.9.0.cl. The `isAnswerExportV2Enabled` flag is enabled by default on all ThoughtSpot Cloud instances. The following enhancements are included in this release: + +Pinned Answer export:: +Pass `viz_guid` to export a pinned Answer (a visualization on a Liveboard) directly. Liveboard-level filters and runtime overrides are applied automatically. The `metadata_identifier` must be the parent Liveboard GUID or name. + +Personalized View support:: +Pass `personalised_view_identifier` to export data from a specific Personalized View of a Liveboard. + +Spotter Answer export:: +XLSX and PDF export formats are now supported for Spotter-generated (ad hoc) Answers, in addition to CSV and PNG. + +Custom PNG dimensions:: +Use `x_resolution` and `y_resolution` parameters to specify custom pixel dimensions for PNG exports. Accepted range: 600–3840 px per axis. Default: 2254 × 1588. + +Display scaling:: +Use `scaling_factor` (range: 80–400) to adjust the relative size of chart elements in a PNG export without cropping the image. + +Dynamic file naming:: +Exported files are automatically named based on the Answer title with the correct file extension (`.png`, `.pdf`, `.csv`, `.xlsx`) appended. + +For more information, see xref:data-report-v2-api.adoc#answer-report[Answer Report API]. + +=== Snowflake Semantic View integration APIs + +// SOURCE: SCAL-309867 + +ThoughtSpot 26.9.0.cl introduces REST API v2.0 endpoints for managing Snowflake Semantic View integrations programmatically. These APIs allow administrators and data managers to create, search, import, and delete semantic integration configurations without using the ThoughtSpot UI. + +[width="100%"] +[options="header"] +|===== +| Method | Endpoint | Description +| `POST` | `/api/rest/2.0/semantic-integrations/create` | Creates a new semantic integration by reading a Snowflake Semantic View and generating a ThoughtSpot data model. +| `POST` | `/api/rest/2.0/semantic-integrations/search` | Returns a list of semantic integrations matching the specified filter criteria. +| `POST` | `/api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/import` | Re-imports semantic updates from Snowflake and refreshes the associated ThoughtSpot data model. +| `POST` | `/api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/delete` | Deletes a semantic integration and its generated ThoughtSpot data model. +|===== + +Required privilege: `ADMINISTRATION` or `DATAMANAGEMENT`. If RBAC is enabled, the user also requires the `CAN_CREATE_OR_EDIT_CONNECTIONS` privilege and permission to manage data models. + +For more information, see xref:semantic-integrations-api.adoc[Snowflake Semantic View integration APIs]. + +=== Spotter Memory — General Availability + +// SOURCE: SCAL-306173 + +The Spotter Memory feature is generally available from 26.9.0.cl. The memory APIs introduced in 26.8.0.cl (`POST /api/rest/2.0/ai/memory/import` and `POST /api/rest/2.0/ai/memory/export`) are enabled by default on all ThoughtSpot Cloud instances. Administrators can manage and audit Spotter training data programmatically without enabling a feature flag. + +For more information, see xref:spotter-ai-memory-api.adoc[Spotter memory APIs]. + +=== Spotter Agent — Conversation sharing APIs + +// SOURCE: SCAL-306173 (aug.26.mt) + +ThoughtSpot 26.9.0.cl introduces REST API v2.0 endpoints for sharing saved Spotter agent conversations with other users or groups. Shared conversations are always `READ_ONLY`. + +[width="100%"] +[options="header"] +|===== +| Method | Endpoint | Description +| `POST` | `/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` | Shares a saved Spotter conversation with specified principals. Use `grant` and `revoke` arrays to manage access. +| `GET` | `/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content` | Returns the content of a shared Spotter conversation — messages, data sources, and answer details. +| `GET` | `/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info` | Returns sharing metadata — the list of principals the conversation is shared with and their access levels. The `is_shared_content_outdated` flag indicates if the shared snapshot is stale. +|===== + +For more information, see xref:spotter-agent-apis.adoc#_sharing_spotter_conversations[Sharing Spotter conversations]. + +=== KPI Sparkline setting in metadata search response + +// SOURCE: SCAL-320899 + +The `POST /api/rest/2.0/metadata/search` API response now includes the `isSparklineEnabled` field in the `AnswerSpecHeader` object for KPI chart type answers. This boolean field indicates whether the sparkline trend line is enabled for the KPI visualization. + +* `true` — the sparkline trend line is enabled. +* `false` — the sparkline is disabled. +* Absent — the answer was saved before this release and has not been re-saved. Treat an absent field as unknown, not as `false`. + +=== Outline Encoding — BYOC Muze + +// SOURCE: SCAL-317550 + +ThoughtSpot 26.9.0.cl promotes mark outline color to a first-class data-driven encoding channel in the Muze charting library (BYOC). Developers building custom charts with Muze can now bind a data field to `encoding.outline` to produce ordinal color palettes (for categorical fields) or continuous gradient ramps (for measures), with full legend rendering and legend-to-mark interaction. + +The static `outline` config (`{ fill, color, width, dash }`) remains fully backward compatible. Supported mark types: Point, Bar, Arc. + +=== Personalized Views TML portability — General Availability + +// SOURCE: SCAL-307284 + +The Personalized Views TML portability feature introduced as Early Access in 26.8.0.cl is generally available from 26.9.0.cl. + +* The `author` field in Personalized View TML maps to the view owner's username or email, ensuring ownership is retained when a Liveboard is promoted across clusters or orgs. +* The `obj_id` field provides a stable cross-environment identifier for Personalized Views. +* Smart merge import: when importing a Liveboard TML that contains Personalized Views, ThoughtSpot preserves views that exist only in the target environment, appends new views from the imported TML, and updates views present in both. + +For more information, see xref:tml.adoc#personalized-views-portability[Personalized Views portability in TML]. + +=== Connection configuration — Scheduled Liveboards process type + +// SOURCE: SCAL-312738 + +ThoughtSpot 26.9.0.cl adds `SCHEDULED_LIVEBOARDS` as a new process type for Embrace connection configurations. Administrators can assign the Scheduled Liveboards process to a connection configuration, enabling ThoughtSpot to use the associated credentials when running scheduled Liveboard delivery jobs. Configurable via: + +* `POST /api/rest/2.0/connection/configuration/create` +* `PUT /api/rest/2.0/connection/configuration/{configuration_identifier}/update` + +=== AI Context — Spotter Optimization tab + +// SOURCE: SCAL-277656 + +The AI Context generation UI is revamped in 26.9.0.cl. A new *Spotter Optimization* tab is introduced in the data model editor for managing AI context, replacing the previous AI Context panel. The tab provides a more streamlined interface for reviewing and editing auto-generated descriptions for columns and joins. + +No changes to the AI context REST API endpoints in this release. + +== Version 26.8.0.cl, August 2026 + +=== Spotter AI APIs + +Spotter memory APIs::: +ThoughtSpot 26.8.0.cl introduces two new REST API v2.0 endpoints for managing Spotter memory programmatically: + +* `POST /api/rest/2.0/ai/memory/import` + +Imports Spotter memory entries in bulk. Use this endpoint to seed training data or migrate Spotter memory across environments. +* `POST /api/rest/2.0/ai/memory/export` + +Exports all current Spotter memory entries. Use this endpoint to back up training data or audit the current training state. + +For more information, see xref:spotter-ai-memory-api.adoc[Spotter memory APIs]. + +=== TML import and export + +New TML fields for Personalized Views::: [earlyAccess eaBackground]#Early Access# +Two new fields have been added to the TML for Personalized Views. You can see these fields added to the TML schema when you export through the `POST /api/rest/2.0/metadata/tml/export` API. + +* A new `author` field is added to the Personalized View TML during export. This field is used to assign ownership during import. +* Personalized Views now carry an `obj_id` field for stable cross-environment object identity, consistent with other object types. + +For more information, see xref:tml.adoc#personalized-views-portability[Personalized Views portability in TML]. + +Collections `obj_id` support::: +// SOURCE: SCAL-317357 +The `obj_id` attribute is now supported for the *Collections* object type in TML import and export APIs. This enables stable cross-environment identification for Collections, matching the behavior already available for Models, Liveboards, Answers, and other object types. ++ +To assign or update the `obj_id` for a Collections object, use the `POST /api/rest/2.0/metadata/identity/update` API endpoint. ++ + +=== Roles API + +Granular download privileges::: +ThoughtSpot introduces two new granular download privileges that give administrators finer control over what users can export: + +* *Can Download Visuals*: Permits downloading chart and visualization images. +* *Can Download Detailed Data*: Permits downloading raw tabular data in CSV or XLSX format. + +These privileges are configurable via the `POST /api/rest/2.0/roles/create` and `POST /api/rest/2.0/roles/update` API endpoints. + +=== Liveboard schedules API +The `every_n_minutes` schedule frequency option is deprecated in 26.8.0.cl. Schedules configured with this frequency will continue to run during the transition period; however, ThoughtSpot recommends updating existing schedules to supported frequency options (hourly, daily, weekly, or monthly). Support for the `every_n_minutes` frequency will be removed in a future release. + +=== REST API C# SDK +ThoughtSpot provides the REST API C# SDK (`ThoughtSpot.RestApi.Sdk`) to help .NET developers interact programmatically with ThoughtSpot REST API v2 endpoints. The SDK targets `net8.0` and is available on link:https://www.nuget.org/packages/ThoughtSpot.RestApi.Sdk[NuGet, window=_blank]. + +For information about how to install and use the SDK, see xref:rest-api-sdk-csharp.adoc[C# SDK for REST APIs]. + +== Version 26.7.0.cl, July 2026 + +=== Spotter AI APIs + +Save chat AI APIs:: +ThoughtSpot introduces the following REST API endpoints and enhancements to manage saved Spotter conversations programmatically. These endpoints allow you to build custom conversation history interfaces in embedded applications without using the native Spotter UI. + +* `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/update` + +Updates attributes of an existing agent conversation. +* `GET /api/rest/2.0/ai/agent/conversations` + +Retrieves the list of saved agent conversations for the currently authenticated user. +* `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/messages` + +Retrieves the full content of a saved conversation with Spotter agent. +* `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/update` + +Updates the display title of a saved conversation. +* `DELETE /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/delete` + +Deletes a saved conversation and all its associated messages. +* `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/answers/{answer_identifier}/details` + +Loads the full answer payload for a specific answer item in an agent conversation. + ++ +For more information, see xref:spotter-agent-conversation-mgmt-apis.adoc[Saving and managing Spotter AI chat]. + +Save chat settings in conversation create API:: + +The `POST /api/rest/2.0/ai/agent/conversation/create` API endpoint is modified to allow users to save conversations by setting `enable_save_chat: true` in the API request. + +Agent instructions APIs:: +The following new API endpoints allow you to set and retrieve persistent behavioral instructions for the Spotter agent. + +* `PUT /api/rest/2.0/ai/agent/instructions/set` + +Sets behavioral instructions for the Spotter agent. Use this endpoint to define persistent guidance that Spotter applies when responding to queries in a conversation session. + +* `GET /api/rest/2.0/ai/agent/instructions/get` + +Retrieves the behavioral instructions currently configured by the administrator for the Spotter agent. ++ +For more information, see xref:spotter-agent-instructions.adoc[Spotter AI Agent instructions APIs]. + +=== Webhooks + +New API endpoint:: +The `GET /api/rest/2.0/webhooks/storage-config` API endpoint allows retrieving the storage setup information required for configuring a GCS or S3 storage destination for webhook delivery. + +Enhancements:: + +* The `/api/rest/2.0/webhooks/create` endpoint allows activating a webhook and configuring a GCS storage destination for webhook delivery. The API endpoint also returns GCS storage configuration details in the response. +* The `/api/rest/2.0/webhooks/{webhook_identifier}/update` API endpoint supports configuring webhook activation status, resetting authentication, signature verification, and storage destination properties. +* API requests to the `/api/rest/2.0/system/communication-channels/validate` now return GCS storage properties in response. + +=== Communication channel monitoring + +The `/api/rest/2.0/jobs/history/communication-channels/search` API endpoint supports the `end_epoch_time_in_millis` parameter, which allows fetching records with a specific end timestamp. + +=== Style customization APIs + +ThoughtSpot introduces the following REST API v2.0 endpoints to manage style customization settings programmatically. + +Style configuration:: + +* `POST /api/rest/2.0/customization/styles/search` + +Returns the current style configuration at the `CLUSTER` or active `ORG` scope. + +* `POST /api/rest/2.0/customization/styles/update` + +Updates style settings at the `CLUSTER` or `ORG` scope. + +Custom fonts:: + +* `POST /api/rest/2.0/customization/styles/fonts/upload` + +Uploads a custom font file to ThoughtSpot. + +* `POST /api/rest/2.0/customization/styles/fonts/search` + +Returns custom fonts uploaded to the instance. + +* `PUT /api/rest/2.0/customization/styles/fonts/{font_identifier}/update` + +Updates a custom font record. + +* `DELETE /api/rest/2.0/customization/styles/fonts/{font_identifier}/delete` + +Deletes a custom font. + +For more information, see xref:style-customization-api.adoc[Style customization APIs]. + +=== Liveboard schedules + +* The `POST /api/rest/2.0/schedules/create` API endpoint now supports the `connection_configuration_identifier` attribute. This attribute specifies a configured Embrace connection configuration when creating a scheduled Liveboard job. +* The `POST /api/rest/2.0/schedules/{schedule_identifier}/update` API endpoint now supports the `connection_configuration_identifier` attribute. + +=== Tags API + +The `POST /api/rest/2.0/tags/assign` and `POST /api/rest/2.0/tags/unassign` API endpoints now support Collections as a metadata object type. + +=== Custom actions + +The `POST /api/rest/2.0/customization/custom-actions/create` and `POST /api/rest/2.0/customization/custom-actions/{custom_action_identifier}/update` API endpoints now support `group_identifiers` for access control. This allows restricting custom action visibility to specific user groups. + +== Version 26.6.0.cl, June 2026 + +=== Spotter AI APIs + +Answer Export API [earlyAccess eaBackground]#Early Access#:: +ThoughtSpot introduces the `POST /api/rest/2.0/report/answer` endpoint for exporting Answer data in CSV, XLSX, PDF, or PNG format. Requires the `isAnswerExportV2Enabled` feature flag to be enabled on the instance. + +For more information, see xref:data-report-v2-api.adoc#answer-report[Answer Report API]. + +Stop Spotter response:: +The `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response` API endpoint stops an in-progress Spotter agent response for a given conversation session. The conversation session remains active after the response stops. + +=== Connections + +Connection configurations:: +ThoughtSpot introduces the following new API endpoints for managing Embrace connection configurations: + +* `POST /api/rest/2.0/connection/configuration/create` + +Creates a connection configuration for an Embrace connection. +* `GET /api/rest/2.0/connection/configuration/{configuration_identifier}` + +Retrieves an existing connection configuration. +* `PUT /api/rest/2.0/connection/configuration/{configuration_identifier}/update` + +Updates an existing connection configuration. +* `DELETE /api/rest/2.0/connection/configuration/{configuration_identifier}/delete` + +Deletes a connection configuration. +* `POST /api/rest/2.0/connection/configuration/search` + +Returns a list of connection configurations matching the specified filter criteria. + +For more information, see xref:embrace-connection-configuration.adoc[Connection configurations]. + +=== REST API Python SDK + +ThoughtSpot provides the REST API Python SDK (`thoughtspot-rest-api-sdk`) to help Python developers interact programmatically with ThoughtSpot REST API v2 endpoints. The SDK is available on link:https://pypi.org/project/thoughtspot-rest-api-sdk/[PyPI, window=_blank]. + +For information about how to install and use the SDK, see xref:rest-api-sdk-python.adoc[Python SDK for REST APIs]. + +== Version 26.5.0.cl, May 2026 + +=== Spotter AI APIs + +The following API endpoints are deprecated in 26.5.0.cl: + +* `POST /api/rest/2.0/ai/agent/converse/sse` — Use `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream` instead. +* `POST /api/rest/2.0/ai/agent/{conversation_identifier}/converse` — Use `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send` instead. + +New API endpoints:: + +* `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send` + +Sends natural language messages to an existing Spotter agent conversation and returns the complete response synchronously. + +* `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream` + +Sends natural language messages to an existing Spotter agent conversation and returns the response as a real-time Server-Sent Events (SSE) stream. + +Breaking changes in `POST /api/rest/2.0/ai/agent/conversation/create`:: +The `metadata_context` object now requires `type` to be one of `AUTO_MODE` or `DATA_SOURCE`. The legacy `data_source` option is deprecated. + +=== REST API TypeScript SDK + +ThoughtSpot provides the REST API TypeScript SDK (`@thoughtspot/rest-api-sdk`) to help developers interact programmatically with ThoughtSpot REST API v2 endpoints. The SDK is available on link:https://www.npmjs.com/package/@thoughtspot/rest-api-sdk[npm, window=_blank]. + +For information about how to install and use the SDK, see xref:rest-api-sdk-typescript.adoc[TypeScript SDK for REST APIs]. From 190dd381acd311ad5a1b9b7c7a21539e4851780d Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 17 Aug 2026 10:26:58 +0530 Subject: [PATCH 035/154] =?UTF-8?q?docs:=20add=20Visual=20Embed=20SDK=201.?= =?UTF-8?q?52.x=20changelog=20=E2=80=94=20overrideHistoryState,=20HomeLeft?= =?UTF-8?q?NavItem.Collections=20(SCAL-317516,=20SCAL-314461)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- modules/ROOT/pages/api-changelog.adoc | 281 +++++++++++++++++++++++++- 1 file changed, 280 insertions(+), 1 deletion(-) diff --git a/modules/ROOT/pages/api-changelog.adoc b/modules/ROOT/pages/api-changelog.adoc index ec6077f68..44d9a9a16 100644 --- a/modules/ROOT/pages/api-changelog.adoc +++ b/modules/ROOT/pages/api-changelog.adoc @@ -1 +1,280 @@ -Unknown tool: github_get_file \ No newline at end of file += Visual Embed SDK changelog +:toc: true +:toclevels: 2 + +:page-title: Visual Embed SDK changelog +:page-pageid: embed-sdk-changelog +:page-description: Changelog for the Visual Embed SDK + +This page documents the changes introduced in each release of the Visual Embed SDK. For information about the REST API v2.0 changes, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. + +== Version 1.52.x, September 2026 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| + +[discrete] +===== Browser history management in full application embedding + +// SOURCE: SCAL-317516 +// SOURCE: thoughtspot/visual-embed-sdk/src/types.ts (master) + +ThoughtSpot 26.9.0.cl introduces the `overrideHistoryState` configuration parameter for `AppEmbed`. When embedding ThoughtSpot in a host application, every internal ThoughtSpot navigation event (for example, switching between Liveboards or Answers) pushes a new entry onto the browser's history stack. This causes the browser *Back* button to step through ThoughtSpot's internal navigation before returning to the host application's prior page. + +Setting `overrideHistoryState: true` converts all ThoughtSpot internal `pushState` calls to `replaceState`, preventing ThoughtSpot navigation from polluting the host application's browser history stack. + +[source,JavaScript] +---- +import { AppEmbed, init, AuthType } from '@thoughtspot/visual-embed-sdk'; + +init({ + thoughtSpotHost: 'https://.thoughtspot.cloud', + authType: AuthType.TrustedAuthToken, + getAuthToken: () => fetch('/ts-token').then(r => r.json()).then(d => d.token), +}); + +const embed = new AppEmbed('#embed-container', { + frameParams: { width: '100%', height: '100%' }, + overrideHistoryState: true, // <1> +}); + +embed.render(); +---- +<1> When set to `true`, ThoughtSpot replaces rather than pushes browser history entries during internal navigation. + +[NOTE] +==== +`overrideHistoryState` is available on `AppEmbed` only. It is not supported on `LiveboardEmbed`, `SearchEmbed`, or `SpotterEmbed`. Validate behavior across Chrome, Firefox, and Safari before enabling in production. +==== + +For more information, see xref:full-app-embed.adoc[Full application embedding]. + +|[tag greenBackground]#NEW FEATURE# a| + +[discrete] +===== Collections in left navigation panel + +// SOURCE: SCAL-314461 + +The `HomeLeftNavItem.Collections` enum value is now available in the Visual Embed SDK. Embed developers can include *Collections* as a selectable navigation option in the embedded left navigation panel for full application embeds. When enabled, end users of the embedded application can navigate to *Collections* from the left navigation panel. + +[source,JavaScript] +---- +import { AppEmbed, HomeLeftNavItem, init, AuthType } from '@thoughtspot/visual-embed-sdk'; + +init({ + thoughtSpotHost: 'https://.thoughtspot.cloud', + authType: AuthType.TrustedAuthToken, + getAuthToken: () => fetch('/ts-token').then(r => r.json()).then(d => d.token), +}); + +const embed = new AppEmbed('#embed-container', { + frameParams: { width: '100%', height: '100%' }, + leftNavOrder: [ + HomeLeftNavItem.Home, + HomeLeftNavItem.Liveboards, + HomeLeftNavItem.Answers, + HomeLeftNavItem.Collections, // <1> + ], +}); + +embed.render(); +---- +<1> Include `HomeLeftNavItem.Collections` in the `leftNavOrder` array to show Collections in the embedded left navigation panel. + +For more information, see xref:full-app-customize.adoc[Customize full application embedding]. + +|==== + +== Version 1.51.x, August 2026 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| + +[discrete] +===== Spotter embedding + +Spotter Analysts:: +The Visual Embed SDK introduces controls for the Spotter Analysts feature in embedded applications. The Analysts section in the Spotter sidebar is disabled by default in the embed mode. For more information, see xref:customize-spotter-embed.adoc#_spotter_analysts[Spotter Analysts in embed view]. + +Starter prompts:: +If quick starter prompts are enabled and configured for data models on a ThoughtSpot instance, you can display these prompts in the embed using the `enableStarterPrompts` parameter. For more information, see xref:customize-spotter-embed.adoc#_spotter_starter_prompts[Spotter quick starter prompts]. + +|[tag greenBackground]#MODIFIED# a| + +[discrete] +===== Liveboard embedding +The following Liveboard embedding settings are set to `true` by default on all ThoughtSpot embedded instances: + +* `hideIrrelevantChipsInLiveboardTabs` + +Hides filters that are not relevant to the displayed visualization. +* `isLiveboardCompactHeaderEnabled` + +Enables compact header layout in embedded Liveboards. +* `coverAndFilterOptionInPDF` + +Enables the *Include cover page* and *Include filter page(s)* checkboxes in the Liveboard download modal. +* `isLiveboardMasterpiecesEnabled` + +Enables the xref:embed-pinboard.adoc#_liveboard_grouping_and_styling[Liveboard styling and grouping] feature. +* `isEnhancedFilterInteractivityEnabled` + +Enables interactive filter chips that allow users to add, update, or remove filters in an embedded Liveboard. + +For more information, see xref:embed-pinboard.adoc#common-customizations[Common customization options in Liveboard embedding]. + +|[tag greenBackground]#NEW FEATURE# a| + +[discrete] +===== Object format support in HostEvent.Navigate +The `HostEvent.Navigate` event now supports an object format in addition to the existing string path format. Use the object format to replace the current browser history entry instead of pushing a new entry. + +//// +[source,JavaScript] +---- +// String format — push new history entry (existing behavior, unchanged) +appEmbed.trigger(HostEvent.Navigate, 'home'); +---- + +[source,JavaScript] +---- +// Object format — replace current history entry (new in SDK 1.51.0) +appEmbed.trigger(HostEvent.Navigate, { path: 'home', replace: true }); +---- +Supported embed types: `AppEmbed`. +//// + +|==== + +== Version 1.50.x, July 2026 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| + +[discrete] +===== SpotterViz embed customization +The Visual Embed SDK 1.50.0 introduces the `SpotterVizConfig` interface and `SpotterVizStarterPrompt` interface to allow embed developers to customize the SpotterViz panel on embedded Liveboards and full-application embeds. + +A new `SpotterVizConfig` interface is available on `LiveboardViewConfig` and `AppViewConfig` for the `spotterViz` object. This object provides branding customization controls for customizing the SpotterViz panel experience. For more information, see xref:embed-spotterViz.adoc[SpotterViz in embedded Liveboards]. + +|[tag greenBackground]#NEW FEATURE# a| + +[discrete] +===== Home page customization in full application embedding +For full application embedding, ThoughtSpot provides a focused and streamlined home page experience. To enable this feature, use the `HomePage.Focused` option with the `homePage` attribute in the `discoveryExperience` object. + +For more information, see xref:full-app-customize.adoc[Customize full application embedding]. +|==== + +== Version 1.49.x, June 2026 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| +[discrete] +===== Visual overrides for charts and tables +The SDK introduces the `visualOverrides` object in `SearchViewConfig` and +`AppViewConfig`, enabling embed developers to apply chart and table display +customizations to the new answers from an embedded Search data interface at initialization time. + +The `visualOverrides` object provides the following customization controls to modify the chart and table display: + +* `legend` to control legend visibility, position, and color palette of charts. +* `dataLabel` attribute for data labels and per-column label filters. +* `display` attributes such as regression line overlay and grid line visibility in charts, and table themes and content density in tables. +* `axis` property for axis name and label visibility and fixed y-axis range. +* `columns` property for per-column series color and conditional formatting rules in charts, and column visibility, text wrapping, conditional formatting, and column summary in tables. +* `updateMaskPaths` property for partial updates. + +For more information, see xref:viz-overrides.adoc[Visualization overrides]. +|[tag greenBackground]#NEW FEATURE# a| + +[discrete] +===== Liveboard browser cache refresh +For embedded Liveboards, the SDK provides `enableLiveboardDataCache` to clear browser cache and fetch new data for the visualizations on the Liveboard. + +The SDK also provides the following events and action ID to programmatically trigger cache refresh and control the visibility of the **Refresh** button. + +* `EmbedEvent.RefreshLiveboardBrowserCache` + +Emitted when the Liveboard browser cache is refreshed. +* `HostEvent.RefreshLiveboardBrowserCache` + +Trigger a manual cache refresh from the host application. +* `Action.RefreshLiveboardBrowserCache` + +Action ID to show or hide the cache refresh button. + +For more information, see xref:embed-pinboard.adoc#liveboard-data-cache[Enable Liveboard refresh]. + +|[tag greenBackground]#NEW FEATURE# a| +[discrete] +===== Spotter file upload +The SDK introduces the following configuration parameters in `SpotterChatConfig` object to enable and control file uploads in the embedded Spotter chat interface. + +* `spotterFileUploadEnabled` + +When set to `true`, enables the file upload feature in the Spotter chat panel. + +* `spotterFileUploadFileTypes` + +Restricts the file types allowed for upload in the Spotter chat panel. + +For more information, see xref:embed-spotter.adoc#fileUpload[Allowing file uploads in Spotter chats]. + +|==== + +== Version 1.48.x, May 2026 +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| +[discrete] +===== Liveboard embedding +The SDK includes the following new features and enhancements in Liveboard embedding. + +Continuous Liveboard layout in PDF downloads [beta betaBackground]^Beta^:: + +When set to `true`, the `isContinuousLiveboardPDFEnabled` enables the Liveboard tab to render on a single page that matches the exact UI layout you see in ThoughtSpot. This update addresses the issue where visualizations for PDF downloads were split across multiple A4 pages regardless of how they appear on screen. This feature is in beta and can be enabled by setting `isContinuousLiveboardPDFEnabled` to `true`. + +New events and action IDs;; + +* `EmbedEvent.DownloadLiveboardAsContinuousPDF` + +Emits when the download action is triggered. +* `HostEvent.DownloadLiveboardAsContinuousPDF` + +Triggers a download of the Liveboard as a continuous PDF. +* `Action.DownloadLiveboardAsContinuousPDF` + +Action ID to show or hide the continuous PDF download option. + +Org-level Liveboard filter settings;; +Administrators can configure Liveboard filter settings for all users in an Org using the new org-level filter configuration option. For more information, see xref:embed-pinboard.adoc#org-filter-config[Configure Liveboard filter settings for an Org]. + +|[tag greenBackground]#NEW FEATURE# a| +[discrete] +===== Search embedding +* The `SearchEmbed` now supports the `dataPanelCustomGroupsAccordionInitialState` attribute to control the initial expanded or collapsed state of custom groups in the data panel. +* New action IDs to show or hide Edit and Delete buttons for saved Answers in the Search interface: +** `Action.EditAnswer` +** `Action.DeleteAnswer` + +|[tag greenBackground]#NEW FEATURE# a| +[discrete] +===== Full application embedding +The `AppEmbed` configuration now supports `disableMultipleOrgsGlobalSearch` to disable the global search scope across multiple Orgs in embedded full application mode. + +|==== + +== Version 1.47.x, April 2026 +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| +[discrete] +===== Spotter embedding +* The `SpotterEmbed` now includes the `isSpotterFullPageEnabled` parameter. When set to `true`, the Spotter interface occupies the full available height of the embed container. +* The `enableSpotterFileUpload` parameter enables file upload capability directly in embedded Spotter. + +|[tag greenBackground]#NEW FEATURE# a| +[discrete] +===== Liveboard embedding +* New action ID `Action.CopyToClipboard` to show or hide the *Copy to clipboard* option for Liveboard visualizations. +* The `LiveboardEmbed` now supports the `isFilterPanelOpen` attribute to set the initial open or closed state of the filter panel. + +|[tag greenBackground]#NEW FEATURE# a| +[discrete] +===== Full application embedding +The `AppEmbed` configuration now supports `hideApplicationSwitcher` to hide the application switcher control from the embedded ThoughtSpot navigation bar. + +|==== From 6daae0a0c5e123e4559faf78ef89ff10e892a5f9 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 17 Aug 2026 10:28:21 +0530 Subject: [PATCH 036/154] =?UTF-8?q?docs:=20add=20Answer=20Report=20API=20G?= =?UTF-8?q?A=20section=20to=20data-report-v2-api.adoc=20=E2=80=94=20pinned?= =?UTF-8?q?=20Answer,=20Spotter=20Answer,=20PNG=20dimensions=20(SCAL-30606?= =?UTF-8?q?9)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- modules/ROOT/pages/data-report-v2-api.adoc | 377 ++++++++++++++++++++- 1 file changed, 376 insertions(+), 1 deletion(-) diff --git a/modules/ROOT/pages/data-report-v2-api.adoc b/modules/ROOT/pages/data-report-v2-api.adoc index ec6077f68..648618486 100644 --- a/modules/ROOT/pages/data-report-v2-api.adoc +++ b/modules/ROOT/pages/data-report-v2-api.adoc @@ -1 +1,376 @@ -Unknown tool: github_get_file \ No newline at end of file += Data and Report APIs +:toc: true +:toclevels: 3 + +:page-title: data-apis +:page-pageid: fetch-data-and-report-apis +:page-description: Data and Report APIs + +== Data APIs +ThoughtSpot provides the following REST API v2 endpoints to fetch data: + +* xref:#_search_data_api[`POST /api/rest/2.0/searchdata`] to search data from a given data source. +* xref:#_fetch_liveboard_api[`POST /api/rest/2.0/metadata/liveboard/data`] to get data from a Liveboard. +* xref:#_fetch_answer_data_api[`POST /api/rest/2.0/metadata/answer/data`] to get data from a saved Answer. + +If Role-Based Access Control (RBAC) is enabled, the `DATADOWNLOADING` (Can download Data) privilege is required to use these APIs. Alternatively, if the granular data download RBAC privileges are enabled for your ThoughtSpot instance, the `CAN_DOWNLOAD_DETAILED_DATA` (Can download detailed data) is required. + +=== Search data API + +The `/api/rest/2.0/searchdata` endpoint requires you to specify the data source object ID and a query string for a successful API call. You can also define additional parameters such as `runtime_filter`, `runtime_sort`, and `runtime_param_override` to apply runtime overrides on the data set. + +==== Data source +To search data via API call, you require at least view access to the data source object. The data source object can be a Model, View, or Table. + +You can specify the data source object GUID in the `logical_table_identifier`. The search data endpoint doesn't support searching data from multiple Models, Views, or Tables in a single API request. + +To find the GUID of the Model, View, or Table, use one of the following methods: + +Get data object GUID via API:: + +Send an API request to the `/api/rest/2.0/metadata/search` endpoint with the following parameters in the metadata array: + + ++ +.**Example** +[source,JSON] +---- + "metadata": [ + { + "identifier": "my_model", + "type": "LOGICAL_TABLE" + } + ] +---- + ++ +If you don't know the exact name of the data source object, specify the metadata `type` as `LOGICAL_TABLE` in your API request, and then copy the GUID of the data object from the API response. + +Find the GUID of the data object via UI:: +. Log in to your ThoughtSpot application instance: +. Navigate to **Data workspace**. ++ +---- +https:///#/data/tables/ +---- ++ +. On the **Data workspace** > **Data objects** page, select the data object. For example, if the data source object is a Model, click **Models** and then open the Model. +. In the address bar of the web browser, note the GUID of the data source object. For example, in the following address string, the GUID is `9d93a6b8-ca3a-4146-a1a1-e908b71b963f`: ++ +---- +https:///#/data/tables/9d93a6b8-ca3a-4146-a1a1-e908b71b963f +---- + +. Copy the GUID. + +==== Search query + +include::{path}/search-query-string.adoc[] + +.**Example** +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/searchdata' \ + -H 'Authorization: Bearer {access-token} + -H 'Accept: application/json'\ + -H 'Content-Type: application/json' \ + --data-raw '{ + "query_string": "[sales][store]", + "logical_table_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", +}' +---- + +//// +==== Using tokens generated from Spotter APIs as raw data + +For every natural language query and follow-up question, Spotter APIs such as `/api/rest/2.0/ai/answer/create`, `/api/rest/2.0/ai/agent/converse/sse`, return tokens in the API response. You can use these tokens as raw data to generate an Answer from ThoughtSpot via search data API. + +===== Request example + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/searchdata' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "query_string": "by [city], [product], [item type] = [item type].'\''jackets'\'', [region] = [region].'\''west'\'', sort by sum [sales] descending", + "logical_table_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", + "data_format": "COMPACT", + "record_offset": 0, + "record_size": 10 +}' +---- + +===== API response + +If the API request is successful, ThoughtSpot returns the Answer data for the query string sent in the API request. +//// + +=== Fetch Liveboard Data API +To get data from a Liveboard object and its visualizations via `POST /api/rest/2.0/metadata/liveboard/data` endpoint, your user account must have at least view access to the Liveboard specified in the API request. + +The API request body must include the name or GUID of the Liveboard to fetch data. To get specific visualizations from a given Liveboard, add the names or GUIDs of the visualizations in the `visualization_identifiers` array. + +==== Example +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/metadata/liveboard/data' \ + -H 'Authorization: Bearer {access-token}'\ + -H 'Accept: application/json'\ + -H 'Content-Type: application/json' \ + --data-raw '{ + "metadata_identifier": "d084c256-e284-4fc4-b80c-111cb606449a", + "data_format": "COMPACT", + "visualization_identifiers": [ + "a9655c18-9855-4a73-9e7b-ff4fb6da334b", + "bf4c9814-82c1-4ec4-b879-57eae2134cb4", + "8c46d2b6-94c7-4ba7-a628-6e74e297f973", + "f6ef5d1f-cddb-4547-8b66-af4d5f4da5ad" + ] +}' +---- + +[#transient-lb-content] +==== Liveboard data with unsaved changes + +include::{path}/transient-lb-content.adoc[] + +.**Sample browser fetch request** + +[source,TypeScript] +---- +const embedRef = useEmbedRef(); + const handleFilterChanged: MessageCallback = () => { + embedRef.current + .trigger(HostEvent.getExportRequestForCurrentPinboard) + .then((transientPinboardContent) => { + console.log(transientPinboardContent.data); + + const payload = { + metadata_identifier: "abc", + data_format: "COMPACT", + record_offset: 0, + record_size: 10, + transient_content: JSON.stringify(transientPinboardContent.data), + }; + + fetch( + `https://{ThoughtSpot-Host}/api/rest/2.0/metadata/liveboard/data`, + { + method: "POST", + headers: { + Authorization: + "Bearer xxx", + Accept: "application/json", + "Content-Type": "application/json", + }, + body: JSON.stringify(payload), + } + ) + .then((response) => response.json()) + .then(console.log) + .catch(console.log); + }); + }; + + return ( + + ); +---- + +See also, link:https://developers.thoughtspot.com/docs/Enumeration_HostEvent#_getexportrequestforcurrentpinboard[HostEvent.getExportRequestForCurrentPinboard]. + + +=== Fetch Answer Data API + +To get data from a saved Answer object via `/api/rest/2.0/metadata/answer/data`, you need at least view access to the saved Answer. + +The API request body must include the name or GUID of the saved Answer. + +==== Example +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/metadata/answer/data' \ + -H 'Authorization: Bearer {access-token}'\ + -H 'Accept: application/json'\ + -H 'Content-Type: application/json' \ + --data-raw '{ + "metadata_identifier": "9bd202f5-d431-44bf-be0b-bb9354c7a840", + "data_format": "COMPACT", + "record_offset": 0, + "record_size": 10 +}' +---- + +== Report APIs +ThoughtSpot provides the following REST API v2 endpoints to download data as reports: + +* xref:#_liveboard_report_api[`POST /api/rest/2.0/report/liveboard`] to download a Liveboard or specific visualizations on the Liveboard as a PDF, PNG, or CSV file. +* xref:#answer-report[`POST /api/rest/2.0/report/answer`] to download Answer data as a CSV, XLSX, PDF, or PNG file. + +=== Liveboard Report API +The Liveboard Report API allows you to programmatically download a Liveboard or specific visualizations as a PDF, PNG, or CSV file via `POST /api/rest/2.0/report/liveboard`. + +To use this API endpoint, you need at least view access to the Liveboard. If Role-Based Access Control (RBAC) is enabled on your instance, you also need the `DATADOWNLOADING` privilege or one of the granular download privileges listed below. + +The following report types are available: + +PDF:: +Downloads the entire Liveboard as a PDF file. + +PNG:: +Downloads a single visualization on the Liveboard as a PNG file. Requires `visualization_identifiers` with a single visualization GUID. + +CSV:: +Downloads the data from a single visualization on the Liveboard as a CSV file. Requires `visualization_identifiers` with a single visualization GUID. + +==== Request parameters + +[width="100%" cols="2,1,4"] +[options="header"] +|===== +| Parameter | Required | Description +| `metadata_identifier` | Yes | GUID or name of the Liveboard to download. +| `file_format` | Yes | Report format. Accepted values: `PDF`, `PNG`, `CSV`, `XLSX`. +| `visualization_identifiers` | Conditional | Array of visualization GUIDs. Required when `file_format` is `PNG` or `CSV`. For PDF, optional — if not specified, all visualizations are included. +| `runtime_filter` | No | Runtime filter overrides to apply. +| `runtime_sort` | No | Runtime sort overrides to apply. +| `runtime_param_override` | No | Runtime parameter overrides to apply. +| `transient_content` | No | Liveboard data with unsaved changes. +| `pdf_options` | No | PDF-specific options: `orientation` (`PORTRAIT` or `LANDSCAPE`), `truncate_tables` (boolean), `include_logo`, `footer_text`, `include_page_number`, `cover_page`, `filter_page`. +|===== + +==== Example +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/liveboard' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/octet-stream' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "metadata_identifier": "d084c256-e284-4fc4-b80c-111cb606449a", + "file_format": "PDF", + "pdf_options": { + "orientation": "LANDSCAPE", + "include_logo": true, + "include_page_number": true + } +}' \ + --output liveboard.pdf +---- + +[#answer-report] +=== Answer Report API + +// SOURCE: SCAL-306069 + +The `POST /api/rest/2.0/report/answer` endpoint is generally available from 26.9.0.cl. Use this endpoint to export Answer data in CSV, XLSX, PDF, or PNG format. The endpoint supports saved Answers, pinned Answers (visualizations on a Liveboard), and Spotter-generated (ad hoc) Answers. + +==== Prerequisites + +To download Answer data, the user must have at least *View* access to the Answer or Liveboard. If RBAC is enabled: + +* `DATADOWNLOADING` (Can download Data) — required for all export formats. +* `CAN_DOWNLOAD_DETAILED_DATA` (Can download detailed data) — required for CSV and XLSX. +* `CAN_DOWNLOAD_VISUALS` (Can download visuals) — required for PNG. + +==== Request parameters + +[width="100%" cols="2,1,4"] +[options="header"] +|===== +| Parameter | Required | Description +| `metadata_identifier` | Conditional | GUID or name of the saved Answer. For pinned Answer exports, use the parent Liveboard GUID or name and pass `viz_guid` separately. +| `file_format` | Yes | Export format. Accepted values: `CSV`, `XLSX`, `PDF`, `PNG`. +| `viz_guid` | No | GUID of a pinned visualization on a Liveboard. When specified, `metadata_identifier` must identify the parent Liveboard. +| `personalised_view_identifier` | No | GUID or name of a Personalized View. When specified, the export uses data from that view. +| `runtime_filter` | No | Runtime filter overrides to apply to the export. +| `runtime_sort` | No | Runtime sort overrides to apply to the export. +| `runtime_param_override` | No | Runtime parameter overrides to apply to the export. +| `x_resolution` | No | Width of the PNG export in pixels. Range: 600–3840. Applies only when `file_format` is `PNG`. Default: 2254. +| `y_resolution` | No | Height of the PNG export in pixels. Range: 600–3840. Applies only when `file_format` is `PNG`. Default: 1588. +| `scaling_factor` | No | Scaling percentage for chart elements in PNG exports. Range: 80–400. Does not crop the image. Applies only when `file_format` is `PNG`. +|===== + +==== Export a saved Answer + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/octet-stream' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "metadata_identifier": "my-saved-answer", + "file_format": "CSV" +}' \ + --output answer.csv +---- + +==== Export a pinned Answer + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/octet-stream' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "metadata_identifier": "", + "viz_guid": "", + "file_format": "PDF" +}' \ + --output pinned-answer.pdf +---- + +==== Export a Spotter Answer + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/octet-stream' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "metadata_identifier": "", + "file_format": "XLSX" +}' \ + --output spotter-answer.xlsx +---- + +[NOTE] +==== +Pass the answer ID from the Spotter API response as `metadata_identifier`. XLSX and PDF formats are supported for Spotter Answers from 26.9.0.cl. +==== + +==== Export a PNG with custom dimensions + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/octet-stream' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "metadata_identifier": "my-saved-answer", + "file_format": "PNG", + "x_resolution": 3840, + "y_resolution": 2160, + "scaling_factor": 150 +}' \ + --output answer-4k.png +---- From e9748595b30c2536fba56428584e7187de233ae1 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 17 Aug 2026 10:30:50 +0530 Subject: [PATCH 037/154] =?UTF-8?q?docs:=20add=20conversation=20sharing=20?= =?UTF-8?q?APIs=20to=20spotter-agent-apis.adoc=20=E2=80=94=20share,=20get-?= =?UTF-8?q?shared-content,=20get-share-info=20(SCAL-306173,=20aug.26.mt)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- modules/ROOT/pages/spotter-agent-apis.adoc | 1448 +++++++++++++++++++- 1 file changed, 1447 insertions(+), 1 deletion(-) diff --git a/modules/ROOT/pages/spotter-agent-apis.adoc b/modules/ROOT/pages/spotter-agent-apis.adoc index ec6077f68..b9a909ee3 100644 --- a/modules/ROOT/pages/spotter-agent-apis.adoc +++ b/modules/ROOT/pages/spotter-agent-apis.adoc @@ -1 +1,1447 @@ -Unknown tool: github_get_file \ No newline at end of file += Spotter Agent APIs +:toc: true +:toclevels: 2 + +:page-title: Spotter Agent APIs +:page-pageid: spotter-agent-apis +:page-description: You can use Spotter REST APIs to receive Answers for your analytical queries sent through the conversational experience with ThoughtSpot. + +ThoughtSpot's Spotter Agent APIs allow users to start a conversation session with Spotter Agent and send queries to explore data and receive responses synchronously or as a real-time Server-Sent Events (SSE) stream. + +== Overview +Spotter Agent APIs support conversation sessions with natural language query strings, provide context-aware and guided data analysis, and allow integration with other agentic systems. + +The key capabilities of the Spotter APIs include the following: + +* Initiating and managing conversational sessions +* Processing natural-language queries +* Generating analytical responses, insights, and visualizations +* Recommending relevant datasets or data sources +* Decomposing complex user queries + +== API endpoints + +The AI REST API endpoints listed in the following table provide all the functionality necessary to implement a Spotter 3 conversational experience in your application, from data source discovery through to streaming query responses. +The API endpoints introduced for Spotter 2 also support Spotter 3 capabilities as of version 26.2.0.cl. Some of these API endpoints are deprecated in 26.5.0.cl; ThoughtSpot recommends using the new API endpoints instead. + +Initialize session:: +Call the create agent conversation API (`/api/rest/2.0/ai/agent/conversation/create`) with a data source ID to establish the session context. When auto mode is enabled, and no data source ID is specified in the API request, Spotter will automatically identify the appropriate data source. + +Execute queries:: +To execute queries and generate a standard response synchronously, use the Send agent conversation message API (`/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send`). The send agent message API (`/api/rest/2.0/ai/agent/{conversation_identifier}/converse`) is deprecated in 26.5.0.cl and later versions. + +Real-time output (streaming):: +To stream responses to the application UI in real-time, use the `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream`. The legacy streaming API (`/api/rest/2.0/ai/agent/converse/sse`) is deprecated in 26.5.0.cl and later versions. + +=== Supported API endpoints + +[width="100%" cols="1"] +|===== +a|`POST /api/rest/2.0/ai/agent/conversation/create` + +xref:spotter-agent-apis.adoc#_create_a_conversation_session_with_spotter_agent[Creates a conversation session with the Spotter agent] to generate Answers for the specified data context. +__Available on ThoughtSpot Cloud instances from 10.13.0.cl onwards. Breaking changes introduced in 26.5.0.cl.__ + +a| `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send` [.version-badge.new]#New# + +xref:spotter-agent-apis.adoc#_send_queries_to_a_conversation_session[Sends natural language messages] to an existing Spotter agent conversation and returns the complete response synchronously. +__Replaces /api/rest/2.0/ai/agent/{conversation_identifier}/converse__. + +a|`POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream` [.version-badge.new]#New# + +xref:spotter-agent-apis.adoc#_send_a_query_to_agent_and_get_streaming_responses[Sends one or more natural language messages] to an existing Spotter agent conversation and returns the response as a real-time Server-Sent Events (SSE) stream. +__Replaces /api/rest/2.0/ai/agent/converse/sse__. + +a|`POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response` [.version-badge.new]#New# + +xref:spotter-agent-apis.adoc#_stop_an_in_progress_agent_response[Stops an in-progress Spotter agent response] for a given conversation session. The conversation session remains active after the response stops. + +__Available on ThoughtSpot Cloud instances from 26.6.0.cl onwards.__ + +a| `POST /api/rest/2.0/ai/data-source-suggestions` [beta betaBackground]^Beta^ + +xref:spotter-agent-apis.adoc#_get_data_source_suggestions[Returns a list of relevant data sources], such as Models, based on a query and thus helping users and agents choose the most appropriate data source for analytics. + +__Available on ThoughtSpot Cloud instances from 10.15.0.cl onwards__. + +a| `POST /api/rest/2.0/ai/relevant-questions/` [beta betaBackground]^Beta^ + +xref:spotter-agent-apis.adoc#_get_relevant_questions[Decomposes a user query] into relevant sub-questions. Guides users to explore data more deeply for a comprehensive analysis. + +__Available on ThoughtSpot Cloud instances from 10.13.0.cl onwards__. + + + a| `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` [.version-badge.new]#New# + + xref:spotter-agent-apis.adoc#_share_a_conversation[Shares a saved Spotter conversation] with one or more users or groups. Use `grant` and `revoke` arrays to manage access. Shared conversations are `READ_ONLY`. + + __Available on ThoughtSpot Cloud instances from 26.9.0.cl onwards.__ + + a| `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content` [.version-badge.new]#New# + + xref:spotter-agent-apis.adoc#_get_shared_content[Returns the shared content] of a Spotter conversation, including messages and associated answers. + + __Available on ThoughtSpot Cloud instances from 26.9.0.cl onwards.__ + + a| `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info` [.version-badge.new]#New# + + xref:spotter-agent-apis.adoc#_get_share_information[Returns sharing metadata] for a Spotter conversation — the list of principals it is shared with and whether the shared content is outdated. + + __Available on ThoughtSpot Cloud instances from 26.9.0.cl onwards.__ + + a| `POST /api/rest/2.0/ai/agent/converse/sse` [.version-badge.deprecated]#Deprecated# + +Legacy API endpoint for streaming responses, including tokens and visualizations, for a specific conversation context. +__Deprecated in 26.5.0.cl__. + +a| `POST /api/rest/2.0/ai/agent/{conversation_identifier}/converse` [.version-badge.deprecated]#Deprecated# + +Legacy API endpoint to send natural language queries to a conversation session with Spotter agent. + +__Deprecated in 26.5.0.cl__. +|===== + +== Create a conversation session with Spotter Agent + +The `/api/rest/2.0/ai/agent/conversation/create` API endpoint creates a new conversation session with Spotter Agent for a specific or multi-data context and returns a conversation ID. + +=== Request parameters +The request body must include the `metadata_context`. REST API clients must have at least view access to the data source objects specified in the API request to create a conversation session and use it for subsequent queries. + +[width="100%" cols="2,4"] +[options='header'] +|===== +|Form parameter| Description +|`metadata_context` a| Defines the data context for the conversation. + +* `type` + +Metadata context type. The context type is mandatory. Select one of the following values: + +** `AUTO_MODE` to allow Spotter Agent to automatically discover and select the most relevant datasets for users' queries. +** `DATA_SOURCE` to set a specific data source as the data context. You must specify `data_source_context` and data source IDs. + +To set a specific data source object, use `data_source_identifier`. + +To set multi-data context, use `data_source_identifiers`. +** `data_source` [.version-badge.deprecated]#Deprecated# + +This option is deprecated in 26.5.0.cl. ThoughtSpot recommends using the `DATA_SOURCE` with `data_source_context` and data source IDs instead. + +|`conversation_settings` a|__Optional__. Defines additional parameters for the conversation context. You can set any of the following attributes as needed: + +* `enable_contextual_change_analysis` + +__Boolean__. When enabled, Spotter analyzes how context changes over time, that is, comparing results from different queries. Enabled by default in 26.2.0.cl and later versions. +* `enable_natural_language_answer_generation` + +__Boolean__. Allows sending natural language queries to the conversation session. Enabled by default in 26.2.0.cl and later versions. +* `enable_reasoning` + +__Boolean__. Allows Spotter to use reasoning for deep analysis and precise responses. Enabled by default in 26.2.0.cl and later versions. +* `enable_save_chat` + +When set to `true`, adds the conversation to chat history. +|===== + +=== Example request + +With AUTO_MODE for metadata context:: + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/create' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "metadata_context": { + "type": "AUTO_MODE" + }, + "conversation_settings": { + "enable_save_chat": true + } +}' +---- + +For a single data source as the data context:: + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/create' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "metadata_context": { + "type": "DATA_SOURCE", + "data_source_context": { + "data_source_identifier": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + } + }, + "conversation_settings": {} +}' +---- + +For multi-data source context:: + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/create' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "metadata_context": { + "type": "DATA_SOURCE", + "data_source_context": { + "data_source_identifiers": [ + "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "b2c3d4e5-f6a7-8901-bcde-f12345678901" + ] + } + }, + "conversation_settings": { + "enable_save_chat": true + } +}' +---- + +=== API response + +If the API request is successful, the API returns the conversation ID and identifier in the response body. + +[source,JSON] +---- +{ + "conversation_id": "wwHQ5j8O8dQC", + "conversation_identifier": "wwHQ5j8O8dQC" +} +---- + +* `conversation_identifier` + +Use this for all subsequent message calls. +* `conversation_id` [.version-badge.deprecated]#Deprecated# + +Returns the same value as `conversation_identifier`. + +== Send queries to a conversation session + +To send queries to an ongoing conversation session with the Spotter agent and receive a response synchronously, use the `/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send` API endpoint. + +This API operation requires the conversation ID obtained from the conversation creation API endpoint (`/api/rest/2.0/ai/agent/conversation/create`). The user making the API request must have access to the conversation session. The API request body must include at least one message in natural language format. + +=== Request parameters + +[width="100%" cols="2,2,4"] +[options='header'] +|===== +|Parameter|Type| Description +|`conversation_identifier`|Path parameter|__String__. Required. Specify the conversation ID received from the xref:spotter-agent-apis.adoc#_create_a_conversation_session_with_spotter_agent[POST /api/rest/2.0/ai/agent/conversation/create] API call. +|`messages`|Form parameter|_Array of strings_. Required. Specify at least one query in natural language. For example, `total sales of jackets last month`. +|===== + + +//// +|`settings` |__Optional__. Defines additional parameters for the conversation context. You can set any of the following attributes as needed: + +* `enable_contextual_change_analysis` + +__Boolean__. When enabled, Spotter analyzes how the context changes over time, that is comparing results from different queries. +* `enable_natural_language_answer_generation` + +__Boolean__. Allows sending natural language queries to the conversation session. +* `enable_reasoning` + +__Boolean__. Allows Spotter to use reasoning for deep analysis and precise responses. +//// + +=== Request and response examples + +The following example sends a data comparison query to a conversation session. The conversation ID is specified in the request URL as a path parameter. + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "messages": [ + "Sales in 2025 vs 2024" + ] +}' +---- + +If the request is successful, the API returns an array of objects in the response. The messages in the API response include the following parts: + +[source,JSON] +---- +[ + { + "type": "text", + "text": "\n\nI'll compare sales between 2025 and 2024. First, let me get the dataset context.", + "metadata": {}, + "internal": {}, + "agent_context": "" + }, + { + "type": "text", + "text": "```json\n{\"dataset_name\":\"(Sample) Retail - Apparel\",\"columns\":[{\"name\":\"sales\",\"type\":\"MEASURE\"},{\"name\":\"date\",\"type\":\"ATTRIBUTE\"}]}\n```", + "metadata": {}, + "internal": {}, + "agent_context": "" + }, + { + "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", + "metadata": { + "output": "", + "worksheet_id": "cd252e5c-b552-49a8-821d-3eadaa049cca", + "chart_type": "KPI", + "interrupted": false, + "data_awareness_enabled": true + }, + "internal": {} + }, + { + "type": "text", + "text": "\n\nThe visualization shows year-over-year comparison. You can identify growth or decline trends.", + "metadata": {}, + "internal": {}, + "agent_context": "" + } +] +---- + +The following example sends a follow-up question to the same conversation session. + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "messages": [ + "Now break that down by product category" + ] +}' +---- + +If the request is successful, the agent returns the response for the follow-up question: + +[source,JSON] +---- +[{ + "type": "text", + "text": "I'll add product category to the comparison.", + "metadata": {}, + "internal": {}, + "agent_context": "" + }, + { + "type": "answer", + "title": "Sales by Product Category: 2025 vs 2024", + "session_id": "9abc1234-0000-0000-0000-000000000005", + "gen_no": 3, + "sage_query": "[sales] [product category] [date] = '2025' vs [date] = '2024'", + "tml_tokens": ["[sales]", "[product category]", "[date] = '2025' vs [date] = '2024'"], + "formulas": [], + "parameters": [], + "subqueries": [], + "viz_suggestion": "", + "metadata": { + "chart_type": "BAR", + "worksheet_id": "cd252e5c-b552-49a8-821d-3eadaa049cca" + }, + "internal": {} + }] +---- + +In each response, the agent returns the following information: + +* `type` + +Type of the message, such as text, answer, or error. +* `text` + +Response message generated for the query. +* `metadata` + +Additional information based on the message type. For example, answer metadata, chart type, or the data source ID. +* `tml_tokens` + +Query string broken down as TML tokens. + +In case of errors, the response returns the error details: + +[source,JSON] +---- +[{ + "type": "error", + "message": "The conversation session has expired. Please create a new conversation.", + "code": "SESSION_EXPIRED" +}] +---- + + + +//// +The following example shows the response text contents for the `answer` message type. + +[source,JSON] +---- +[ + { + "id": "r24X7D99SROD", + "type": "answer", + "group_id": "o8dQ9SAWdtrL", + "metadata": { + "sage_query": "[sales] [item type] = [item type].'jackets'", + "session_id": "b321b404-cbf1-4905-9b0c-b93ad4eedf89", + "gen_no": 1, + "transaction_id": "6874259d-13b1-478c-83cb-b3ed52628850", + "generation_number": 1, + "warning_details": null, + "ambiguous_phrases": null, + "query_intent": null, + "assumptions": "You want to see the total sales amount for jackets item type.", + "tml_phrases": [ + "[sales]", + "[item type] = [item type].'jackets'" + ], + "cached": false, + "sub_queries": null, + "title": "Net sales of Jackets", + "worksheet_id": "cd252e5c-b552-49a8-821d-3eadaa049cca" + }, + "title": "Net sales of Jackets" + } +] +---- + +The session ID and generation number serve as the data context for the Answer. You can use this information to create a new conversation session using `/api/rest/2.0/ai/agent/conversation/create`, or download the answer via the `/api/rest/2.0/report/answer` API endpoint. + + +* The tokens and TML phrases returned in the response can be used as inputs for the search data API call to get an Answer. +//// + +== Send a query to agent and get streaming responses + +To send queries to an ongoing conversation session with Spotter agent and receive streaming responses, use the `/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream` API endpoint. This API endpoint uses the SSE protocol to deliver data incrementally in real time, rather than waiting for the entire response to be generated before sending it to the client. + +The `/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream` API can be used as an integrated tool for real-time streaming of conversational interactions between agents and the ThoughtSpot backend. + +=== Request parameters + +[width="100%" cols="2,4"] +[options='header'] +|===== +|Parameter| Description +|`conversation_identifier` |__String__. Specify the conversation ID received from the xref:spotter-agent-apis.adoc#_create_a_conversation_session_with_spotter_agent[POST /api/rest/2.0/ai/agent/conversation/create] API call. +|`messages`|_Array of strings_. Include at least one natural language query. For example, `Sales data for Jackets`, `Top performing products in the west coast`. +|===== + +=== Example request + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "conversation_identifier": "h2I_pTGaRQof", + "messages": [ + "Net sales of Jackets" + ] +}' +---- + +=== API response + +If the API request is successful, the response includes a stream of events, each containing a partial or complete message from the AI agent, rather than a single JSON object. + +Each event is a simple text-based message in a specific format, `data: \n\n`; `\n\n` means that each message sent from the server to the client is prefixed with the `data:` keyword, followed by the actual payload (``), and ends with two newline characters (`\n\n`). + +The API uses this format so that the clients can reconstruct the AI-generated response as it streams in, chunk by chunk, and show the responses in real-time. In agentic workflows, the receiving client or agent listens to the SSE stream, parses each event, and assembles the full response for its users. + +==== Example response +If the request is valid, the API returns SSE streams. Each line has the form `data: [{"type": "...", ...}]`, a JSON array of event objects. + +[source,JSON] +---- +data: [{"type":"ack","node_id":"aGxzcFVrtom8"}] + +data: [{"type":"conv_title","title":"Sales 2025 vs 2024","conv_id":"-XIi04l5rrof"}] + +data: [{"type":"notification","group_id":"cDEsAQbSnd3J","metadata":{"type":"thinking","tool_title":"Analyzing Sales Performance: 2025 vs 2024"},"code":"TOOL_CALL_NOTIFICATION"}] + +data: [{"id":"mNAdvy-NK2l6","type":"text-chunk","group_id":"cDEsAQbSnd3J","metadata":{"format":"markdown","type":"thinking"},"content":"\n\nI need to compare sales performance between 2025 and 2024."}] + +data: [{"type":"notification","group_id":"m1MTvttEUa7o","code":"nls_start"}] + +data: [{"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"}] + +data: [{"type":"notification","code":"FINAL_RESPONSE_NOTIFICATION"}] +---- +For the complete response in one payload, use the xref:spotter-agent-apis.adoc#_send_queries_to_a_conversation_session[`/send` endpoint] instead. + +//// +[source,] +---- +data: [{"type": "ack", "node_id": "BRxCtJ-aGt8l"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": "I"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " understand"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " you're"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " interested"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " in"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " the"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " net"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " sales"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " of"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " Jackets"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": "."}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " I'll"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " retrieve"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " the"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " relevant"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " data"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " for"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " you"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": "."}] + +data: [{"type": "notification", "group_id": "o8dQ9SAWdtrL", "metadata": {"title": "Net sales of Jackets"}, "code": "nls_start"}] + +data: [{"type": "notification", "group_id": "o8dQ9SAWdtrL", "code": "QH", "message": "Fetching Worksheet Data"}] + +data: [{"type": "notification", "group_id": "o8dQ9SAWdtrL", "code": "TML_GEN", "message": "Translating your query with the Reasoning Engine"}] + +data: [{"type": "notification", "group_id": "o8dQ9SAWdtrL", "code": "ANSWER_GEN", "message": "Verifying results with the Trust Layer"}] + +data: [{"id": "r24X7D99SROD", "type": "answer", "group_id": "o8dQ9SAWdtrL", "metadata": {"sage_query": "[sales] [item type] = [item type].'jackets'", "session_id": "b321b404-cbf1-4905-9b0c-b93ad4eedf89", "gen_no": 1, "transaction_id": "6874259d-13b1-478c-83cb-b3ed52628850", "generation_number": 1, "warning_details": null, "ambiguous_phrases": null, "query_intent": null, "assumptions": "You want to see the total sales amount for jackets item type.", "tml_phrases": ["[sales]", "[item type] = [item type].'jackets'"], "cached": false, "sub_queries": null, "title": "Net sales of Jackets", "worksheet_id": "cd252e5c-b552-49a8-821d-3eadaa049cca"}, "title": "Net sales of Jackets"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "The"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " net"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " sales"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " for"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " Jackets"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " have"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " been"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " visual"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "ized"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " for"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " you"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "."}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " This"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " analysis"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " specifically"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " filtered"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " for"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " the"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " item"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " type"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "jackets"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "\""}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " and"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " calculated"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " the"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " total"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " sales"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " amount"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " associated"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " with"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " those"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " products"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ".\n\n"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "**"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "Summary"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " &"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " Insights"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ":"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "**\n"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "-"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " The"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " visualization"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " shows"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " the"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " total"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " net"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " sales"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " for"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " all"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " jacket"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " transactions"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " in"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " your"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " apparel"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " dataset"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ".\n"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "-"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " The"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " calculation"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " uses"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " only"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " sales"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " amounts"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " where"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " the"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " item"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " type"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " is"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " \""}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "J"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "ackets"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ".\"\n"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "-"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " This"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " information"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " is"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " useful"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " for"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " understanding"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " the"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " revenue"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " contribution"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " of"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " jackets"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " within"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " your"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " product"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " mix"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ".\n\n"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "If"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " you'd"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " like"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " to"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " see"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " a"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " breakdown"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " by"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " region"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ","}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " state"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ","}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " time"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " period"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ","}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " or"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " compare"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " jacket"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " sales"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " to"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " other"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " product"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " types"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ","}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " please"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " let"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " me"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " know"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "!"}] +---- +//// + +==== SSE event types +The SSE event types streamed in the API response include: + +* `ack` + +Confirms receipt of the request. For example, the type in the first message `data: [{"type": "ack", "node_id": "BRxCtJ-aGt8l"}]`, which indicates that the server has received the client's request and is acknowledging it. +* `conv_title` + +A conversation title (`title`, `conv_id`). +* `notification` + +Progress or status update (`group_id`, `metadata`, `code`). For example, `TOOL_CALL_NOTIFICATION`, `nls_start`, `FINAL_RESPONSE_NOTIFICATION`. +* `type` + +Type can be `thinking`, `text`. +* `text` + +Complete text block in markdown format. +* `text-chunk` + +Text fragments in incremental streaming, often in markdown (`id`, `group_id`, `metadata` with `format`) +* `content` + +The actual text content sent incrementally. For example, `"I"`, `"understand"`, `"you're"`, `"interested"`, `"in"`, `"the"`, `"net"`, `"sales"`, and so on. +* `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` and more) +* `error` + +In case of failures. +* `*-interrupt` + +If the generation was stopped mid-stream. +* `group_id` + +Groups related chunks together. + +For more information and examples, see xref:spotter-agent-apis.adoc#_sse_event_payload_reference[SSE event payload reference]. + +=== Thinking versus output events +Spotter responses have two phases: + +* A *thinking phase*, where the AI reasons through the query and calls internal tools, followed by an *output phase* containing the final response delivered to the user. + + +Events in the thinking phase carry `"metadata": { "type": "thinking" }`. All other events are final output. + +Every event includes a `group_id`. Events sharing the same `group_id` belong together. During the thinking phase, each tool call gets its own `group_id`. A `FINAL_RESPONSE_NOTIFICATION` notification marks the boundary between the thinking and output phases. + +[listing] +---- +THINKING PHASE +─────────────────────────────────────────────────────────── +ack + +┌─ group_id: g1 ── Tool Call 1 ("Searching data") ─────────┐ +│ notification (thinking, TOOL_CALL_NOTIFICATION) │ +│ text-chunk (thinking) │ +│ answer (thinking) │ +└──────────────────────────────────────────────────────────┘ + +┌─ group_id: g2 ── Tool Call 2 ("Running code") ───────────┐ +│ notification (thinking, TOOL_CALL_NOTIFICATION) │ +│ text-chunk (thinking) │ +│ text-chunk (thinking) │ +└──────────────────────────────────────────────────────────┘ + +notification (FINAL_RESPONSE_NOTIFICATION) ←── boundary +──────────────────────────────────────────────────────────── + +OUTPUT PHASE +──────────────────────────────────────────────────────────── +┌─ group_id: g3 ────────────────────────────────────────────┐ +│ text "Here are the results:" │ +│ answer (final visualization) │ +└───────────────────────────────────────────────────────────┘ +[stream closes] +---- + +==== Notification codes reference + +[width="100%" cols="2,4"] +[options='header'] +|===== +|Code| When it appears +|`QH`|Query handling started +|`TML_GEN` / `TML_GEN_RETRY`|Generating or retrying TML +|`ANSWER_GEN`|Generating an answer +|`IDENTIFYING_ATTRIBUTES`|Identifying data attributes +|`PERFORMING_CHANGE_ANALYSIS`|Running change analysis +|`PERFORMING_FORECASTING_ANALYSIS`|Running forecasting +|`SUMMARIZING_RESULTS`|Summarizing results +|`TOOL_CALL_NOTIFICATION`|Tool invocation (during thinking phase) +|`FINAL_RESPONSE_NOTIFICATION`|Marks the transition from thinking to output +|`search_datasets_start` / `search_datasets_end`|Data source discovery in progress or complete +|`approval_required`|An external tool requires user permission before proceeding +|===== + +=== SSE event payload reference + +==== ack + +[source,JSON] +---- +data: { + "type": "ack", + "group_id": "a1b2c3", + "id": "evt-001", + "node_id": "resp-node-abc" +} +---- + +==== notification (thinking — tool call) + +[source,JSON] +---- +data: { + "type": "notification", + "group_id": "g1", + "id": "evt-002", + "code": "TOOL_CALL_NOTIFICATION", + "message": "Searching for relevant data", + "metadata": { + "type": "thinking", + "tool_title": "Searching sales data", + "tool_code": "RUNNING_CODE_EXECUTION", + "tool_name": "code_interpreter" + } +} +---- + +==== notification (thinking - external tool with MCP integration) + +[source,JSON] +---- +data: { + "type": "notification", + "group_id": "g2", + "id": "evt-003", + "code": "TOOL_CALL_NOTIFICATION", + "message": "Querying Salesforce", + "metadata": { + "type": "thinking", + "tool_title": "Salesforce: Get Opportunities", + "tool_name": "get_opportunities", + "integration_id": "int-sf-123", + "integration_name": "Salesforce" + } +} +---- + +==== notification (approval required) +Sent when an external MCP tool requires explicit user permission before proceeding. Your application should prompt the user to approve or deny the action before continuing. + +[source,JSON] +---- +data: { + "type": "notification", + "group_id": "g2", + "id": "evt-005", + "code": "approval_required", + "metadata": { + "request_id": "perm-req-789", + "integration_id": "int-sf-123", + "integration_name": "Salesforce", + "tool_name": "get_opportunities", + "annotated_title": "Access Salesforce Opportunities" + } +} +---- + +==== notification (FINAL_RESPONSE_NOTIFICATION) + +[source,JSON] +---- +data: { + "type": "notification", + "group_id": "g1", + "id": "evt-004", + "code": "FINAL_RESPONSE_NOTIFICATION", + "message": "" +} +---- + +==== text + +[source,JSON] +---- +data: { + "type": "text", + "group_id": "g3", + "id": "evt-007", + "content": "Here is the total revenue breakdown by region for Q4 2025:\n\n- **North America:** $4.2M\n- **EMEA:** $2.8M\n- **APAC:** $1.5M" +} +---- + +==== text-chunk +Multiple chunks sharing the same `id` should be appended together to reconstruct the full text item. + +[source,JSON] +---- +data: { "type": "text-chunk", "group_id": "g3", "id": "evt-009", "content": "Based on the analysis, " } +data: { "type": "text-chunk", "group_id": "g3", "id": "evt-009", "content": "revenue grew 12% quarter-over-quarter." } +---- + +==== answer +When an `answer` event is received, the `session_id` and `gen_no` fields are returned. You can export the visualization data using the Export Answer Report API to process the results. This allows users to download the answer as a PDF, PNG, CSV, or XLSX file. + +[source,JSON] +---- +data: { + "type": "answer", + "group_id": "g3", + "id": "evt-010", + "title": "Revenue by Region Q4 2025", + "metadata": { + "session_id": "sess-abc-123", + "gen_no": 1, + "transaction_id": "txn-456", + "worksheet_id": "ws-def-789", + "cached": false, + "is_hidden": false + } +} +---- + +==== search_datasets +Emitted as a start/end pair during Auto mode data source discovery. + + +[source,JSON] +---- +data: { "type": "search_datasets", "group_id": "g0", "id": "evt-012", "code": "search_datasets_start", "metadata": {} } + +data: { + "type": "search_datasets", + "group_id": "g0", + "id": "evt-013", + "code": "search_datasets_end", + "metadata": { + "data_sources": [ + { "worksheet_id": "ws-1", "worksheet_name": "Sales Data", "confidence": "high", "reasoning": "Contains revenue columns" }, + { "worksheet_id": "ws-2", "worksheet_name": "Marketing Data", "confidence": "low", "reasoning": "No revenue columns" } + ], + "auto_selected": { "worksheet_id": "ws-1", "worksheet_name": "Sales Data", "confidence": "high", "reasoning": "Best match" } + } +} +---- +==== file + +[source,JSON] +---- +data: { + "type": "file", + "group_id": "g3", + "id": "evt-014", + "files": [ + { "ts_file_id": "file-abc-001", "display_name": "quarterly_report.csv", "file_type": "csv", "created_at": "2025-11-15T10:30:00Z" }, + { "ts_file_id": "file-abc-002", "display_name": "chart.png", "file_type": "png", "created_at": "2025-11-15T10:30:01Z" } + ], + "metadata": { "conv_id": "conv-123" } +} +---- +==== conv_title + +[source,JSON] +---- +data: { + "type": "conv_title", + "group_id": "g0", + "id": "evt-015", + "title": "Revenue Analysis Q4 2025", + "conv_id": "conv-123" +} +---- + +==== error + +[source,JSON] +---- +data: { + "type": "error", + "group_id": "g3", + "id": "evt-016", + "code": "RATE_LIMIT_EXCEEDED", + "message": "Too many requests", + "display_message": "You've exceeded the rate limit. Please try again in a few minutes." +} +---- +==== agent-interrupt + +[source,JSON] +---- +Sent when generation is stopped mid-stream. +data: { + "type": "notification", + "group_id": "g3", + "id": "evt-017", + "code": "agent-interrupt", + "message": "Generation stopped" +} +---- + +[#_stop_an_in_progress_agent_response] +== Stop an in-progress agent response + +The `/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response` API endpoint stops a Spotter agent response that is currently in progress for a given conversation session. + +Use this endpoint when you want to cancel a long-running Spotter response before it completes. The conversation session remains active after you stop a response, so you can send a new query to the same session immediately. + +=== Request parameters + +[width="100%", cols="2,2,4"] +[options='header'] +|===== +|Parameter|Type| Description +|`conversation_identifier`|Path parameter|__String__. Required. The identifier of the active conversation session. Use the value returned by the xref:spotter-agent-apis.adoc#_create_a_conversation_session_with_spotter_agent[create conversation] API endpoint. +|===== + +This endpoint does not require a request body. + +=== Example request + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' +---- + +=== Example response + +If the API request is successful, ThoughtSpot stops the in-progress response and returns a 204 response code. + +If the conversation session is not found or has expired, the API returns an error: + +[source,JSON] +---- +{ + "error_code": "CONVERSATION_NOT_FOUND", + "message": "The specified conversation session does not exist or has expired." +} +---- + +[#process_results] +== Process results generated from a conversation session +To export or download the Answer data generated by the Spotter APIs, use the xref:data-report-v2-api.adoc#exportSpotterData[Answer report] API. + +The `session_id` and `gen_no` values from the `answer` event metadata are required to identify the answer to export. + +NOTE: Requires at least view access to the Answer. + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \ + -H 'Authorization: Bearer {Bearer_token}' \ + -H 'Accept: application/octet-stream' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "session_identifier": "sess-abc-123", + "generation_number": 1, + "file_format": "CSV" +}' +---- +The `file_format` parameter accepts `PDF`, `PNG`, `CSV`, or `XLSX`. + +[NOTE] +==== +Using tokens generated by the Spotter API in a xref:data-report-v2-api.adoc#_search_data_api[Search Data API] request can return invalid column errors, because these tokens may reference formulas or columns not present in the data model. Instead, use the xref:data-report-v2-api.adoc#exportSpotterData[Answer report] API and include the session ID and generation number obtained from the Spotter API in your API request to retrieve the data. +==== + + +== Data literacy and query assistance +The query assistance APIs help users find the appropriate dataset for a given query string, suggest what questions can be asked, and return example questions. These APIs are specifically designed to improve data literacy for users who may not be familiar with the underlying data, making it easier for them to explore and analyze data effectively. + +=== Get data source suggestions + +The `POST /api/rest/2.0/ai/data-source-suggestions` API provides relevant data source recommendations for a user-submitted natural language query. To use this API, you must have at least view access to the underlying metadata object referenced in the response. + +==== Request parameters + +[width="100%" cols="2,4"] +[options='header'] +|==== +|Parameter| Description +|`metadata_context` a| Required. Specify one of the following attributes to set the metadata context: + +* `data_source_identifiers` + +__Array of strings__. IDs of the data source object such as Models. +* `answer_identifiers` + +__Array of strings__. GUIDs of the Answer objects that you want to use as metadata. +* `conversation_identifier` + +__String__. ID of the conversation session. +* `liveboard_identifiers` + +__Array of strings__. GUIDs of the Liveboards that you want to use as metadata. + +| `query` |__String__. Required parameter. Specify the query string that needs to be decomposed into smaller, analytical sub-questions. +|`limit_relevant_questions` + +__Optional__ | __Integer__. Sets a limit on the number of sub-questions to return in the response. Default is 5. +|`bypass_cache` + +__Optional__| __Boolean__. When set to `true`, disables cache and forces fresh computation. +|`ai_context` + +__Optional__. a| Additional context to guide the response. Define the following attributes as needed: +|==== + +==== Example request + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/data-source-suggestions' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "metadata_context": { + "data_source_identifiers": [ + "cd252e5c-b552-49a8-821d-3eadaa049cca" + ] + }, + "query": "Net sales of Jackets in west coast", + "limit_relevant_questions": 3 +}' +---- + +==== API response +If the API request is successful, ThoughtSpot returns a ranked list of data sources, each annotated with relevant reasoning. + +[source,JSON] +---- +{ + "relevant_questions": [ + { + "query": "What is the trend of sales by type over time?", + "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", + "data_source_name": "(Sample) Retail - Apparel" + }, + { + "query": "Sales by item", + "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", + "data_source_name": "(Sample) Retail - Apparel" + }, + { + "query": "Sales across regions", + "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", + "data_source_name": "(Sample) Retail - Apparel" + } + ] +} +---- + +The returned results include metadata such as: + +* `confidence` + +A float indicating the Model's confidence in the relevance of each recommendation. +* `details` + +The data source ID, name, and description for each recommended data source. +* `reasoning` + +Reason provided by the LLM to explain why each data source was recommended. + +=== Get relevant questions + +The `/api/rest/2.0/ai/relevant-questions/` API endpoint breaks down a user-submitted query into relevant sub-questions. It accepts the original query and optional additional context, then generates a set of related questions to help users explore their data comprehensively. + +During agentic interactions, this API can be used as an integrated tool to decompose user queries and suggest relevant questions for a specific data context. REST clients can also call this API directly to fetch relevant questions via a `POST` request. + +==== Request parameters + +[width="100%" cols="2,4"] +[options='header'] +|===== +|Parameter| Description +|`metadata_context` a| Required. Specify one of the following attributes to set the metadata context: + +* `data_source_identifiers` + +__Array of strings__. IDs of the data source object such as Models. +* `answer_identifiers` + +__Array of strings__. GUIDs of the Answer objects that you want to use as metadata. +* `conversation_identifier` + +__String__. ID of the conversation session. +* `liveboard_identifiers` + +__Array of strings__. GUIDs of the Liveboards that you want to use as metadata. + +| `query` |__String__. Required parameter. Specify the query string that needs to be decomposed into smaller, analytical sub-questions. +|`limit_relevant_questions` + +__Optional__ | __Integer__. Sets a limit on the number of sub-questions to return in the response. Default is 5. +|`bypass_cache` + +__Optional__| __Boolean__. When set to `true`, disables cache and forces fresh computation. +|`ai_context` + +__Optional__. a| Additional context to guide the response. Define the following attributes as needed: + +* `instructions` + +__Array of strings__. Custom user instructions to influence how the AI interprets and processes the query. +* `content` + +__Array of strings__. Additional input such as raw text or CSV-formatted data to enhance context and answer quality. +|===== + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/relevant-questions/' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "metadata_context": { + "data_source_identifiers": [ + "cd252e5c-b552-49a8-821d-3eadaa049cca" + ] + }, + "query": "Net sales of Jackets in west coast", + "limit_relevant_questions": 3 +}' +---- + +==== Example response +If the request is successful, the API returns a set of questions related to the query and metadata context in the `relevant_questions` array. Each object in the `relevant_questions` array contains the following fields: + +* `query` + +A string containing the natural language (NL) sub-question. +* `data_source_identifier` + +GUID of the data source object. +* `data_source_name` + +Name of the associated data source object. + +[source,JSON] +---- +{ + "relevant_questions": [ + { + "query": "What is the trend of sales by type over time?", + "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", + "data_source_name": "(Sample) Retail - Apparel" + }, + { + "query": "Sales by item", + "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", + "data_source_name": "(Sample) Retail - Apparel" + }, + { + "query": "Sales across regions", + "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", + "data_source_name": "(Sample) Retail - Apparel" + } + ] +} +---- + +== Additional resources + +* Visit the +++REST API v2.0 Playground+++ to view the API endpoints and verify the request and response workflows. +* For information about MCP tools, see xref:mcp-integration.adoc[MCP server integration]. + + [#_sharing_spotter_conversations] + == Sharing Spotter conversations + + // SOURCE: SCAL-306173 (aug.26.mt) + // SOURCE: prism/src/public-apis/nl-to-answer.graphql (master) + + ThoughtSpot provides REST API v2.0 endpoints to share saved Spotter agent conversations with other users or groups. Shared conversations are always `READ_ONLY` — recipients can view conversation messages and associated answers but cannot send new queries or modify the conversation. + + === Supported endpoints + + [width="100%" cols="1"] + |===== + a| `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` [.version-badge.new]#New# + + xref:spotter-agent-apis.adoc#_share_a_conversation[Shares a saved Spotter conversation] with one or more users or groups. + + __Available on ThoughtSpot Cloud instances from 26.9.0.cl onwards.__ + + a| `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content` [.version-badge.new]#New# + + xref:spotter-agent-apis.adoc#_get_shared_content[Returns the shared content] of a Spotter conversation, including messages and associated answers. + + __Available on ThoughtSpot Cloud instances from 26.9.0.cl onwards.__ + + a| `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info` [.version-badge.new]#New# + + xref:spotter-agent-apis.adoc#_get_share_information[Returns sharing metadata] for a Spotter conversation — the list of principals it is shared with. + + __Available on ThoughtSpot Cloud instances from 26.9.0.cl onwards.__ + |===== + + [#_share_a_conversation] + === Share a conversation + + Use `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` to share a saved Spotter conversation with one or more principals. + + ==== Path parameters + + [width="100%" cols="2,4"] + [options="header"] + |===== + | Parameter | Description + | `conversation_identifier` | The GUID of the saved Spotter conversation to share. + |===== + + ==== Request body parameters + + [width="100%" cols="2,1,4"] + [options="header"] + |===== + | Parameter | Required | Description + | `grant` | No | Array of principal identifiers to grant access. Each entry is a `user_identifier` (username or GUID) or `group_identifier` (group name or GUID). All shared access is `READ_ONLY`. + | `revoke` | No | Array of principal identifiers to revoke access from. + | `refresh_shared_content` | No | Boolean. When `true`, regenerates the shared content snapshot. Default: `false`. + | `notify_on_share` | No | Boolean. When `true`, sends an in-app notification to principals receiving access. Default: `true`. Available from 26.10.0.cl. + |===== + + ==== Example request + + [source,cURL] + ---- + curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "grant": [ + {"user_identifier": "user@example.com"}, + {"group_identifier": "analysts-group"} + ], + "revoke": [], + "refresh_shared_content": false + }' + ---- + + [#_get_shared_content] + === Get shared content + + Use `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content` to retrieve the content of a shared Spotter conversation. + + ==== Path parameters + + [width="100%" cols="2,4"] + [options="header"] + |===== + | Parameter | Description + | `conversation_identifier` | The GUID of the shared Spotter conversation. + |===== + + ==== Response fields + + [width="100%" cols="2,4"] + [options="header"] + |===== + | Field | Description + | `conversation_id` | GUID of the original conversation. + | `shared_conversation_id` | GUID of the shared conversation snapshot. + | `messages` | Array of conversation messages included in the shared snapshot. + | `data_sources` | Array of data source identifiers used in the conversation. + | `code_execution_files` | Array of files generated by code execution steps, if any. + |===== + + ==== Example request + + [source,cURL] + ---- + curl -X GET \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/json' + ---- + + [#_get_share_information] + === Get share information + + Use `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info` to retrieve sharing metadata for a Spotter conversation. + + ==== Path parameters + + [width="100%" cols="2,4"] + [options="header"] + |===== + | Parameter | Description + | `conversation_identifier` | The GUID of the Spotter conversation. + |===== + + ==== Response fields + + [width="100%" cols="2,4"] + [options="header"] + |===== + | Field | Description + | `is_shared_content_outdated` | Boolean. `true` if the shared content snapshot is stale. Use the share endpoint with `refresh_shared_content: true` to regenerate. + | `principals` | Array of principal objects the conversation is shared with. Each entry includes the principal identifier and their access level (always `READ_ONLY`). + |===== + + ==== Example request + + [source,cURL] + ---- + curl -X GET \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/json' + ---- + \ No newline at end of file From 02a807bee3496fcd38d691fc52a5b3cc2f788a43 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 17 Aug 2026 10:30:51 +0530 Subject: [PATCH 038/154] =?UTF-8?q?docs:=20add=20conversation=20sharing=20?= =?UTF-8?q?APIs=20to=20spotter-agent-apis.adoc=20=E2=80=94=20share,=20get-?= =?UTF-8?q?shared-content,=20get-share-info=20(SCAL-306173,=20aug.26.mt)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit From 885e4574b88e7344d2d70e2a00ae7ed08b0df4b0 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 17 Aug 2026 10:34:23 +0530 Subject: [PATCH 039/154] docs: add 26.9.0.cl REST API changelog section (SCAL-306069, SCAL-309867, SCAL-306173, SCAL-320899, SCAL-317550, SCAL-307284, SCAL-312738, SCAL-277656) --- modules/ROOT/pages/rest-apiv2-changelog.adoc | 1389 ++++++++++++++++-- 1 file changed, 1271 insertions(+), 118 deletions(-) diff --git a/modules/ROOT/pages/rest-apiv2-changelog.adoc b/modules/ROOT/pages/rest-apiv2-changelog.adoc index 91c73b2c1..b5325b191 100644 --- a/modules/ROOT/pages/rest-apiv2-changelog.adoc +++ b/modules/ROOT/pages/rest-apiv2-changelog.adoc @@ -10,124 +10,125 @@ This changelog lists the features and enhancements introduced in REST API v2.0. == Version 26.9.0.cl, September 2026 -=== Answer Export API enhancements — General Availability + === Answer Export API enhancements — General Availability -// SOURCE: SCAL-306069 + // SOURCE: SCAL-306069 -The `POST /api/rest/2.0/report/answer` endpoint is generally available from 26.9.0.cl. The `isAnswerExportV2Enabled` flag is enabled by default on all ThoughtSpot Cloud instances. The following enhancements are included in this release: + The `POST /api/rest/2.0/report/answer` endpoint is generally available from 26.9.0.cl. The `isAnswerExportV2Enabled` flag is enabled by default on all ThoughtSpot Cloud instances. The following enhancements are included in this release: -Pinned Answer export:: -Pass `viz_guid` to export a pinned Answer (a visualization on a Liveboard) directly. Liveboard-level filters and runtime overrides are applied automatically. The `metadata_identifier` must be the parent Liveboard GUID or name. + Pinned Answer export:: + Pass `viz_guid` to export a pinned Answer (a visualization on a Liveboard) directly. Liveboard-level filters and runtime overrides are applied automatically. The `metadata_identifier` must be the parent Liveboard GUID or name. -Personalized View support:: -Pass `personalised_view_identifier` to export data from a specific Personalized View of a Liveboard. + Personalized View support:: + Pass `personalised_view_identifier` to export data from a specific Personalized View of a Liveboard. -Spotter Answer export:: -XLSX and PDF export formats are now supported for Spotter-generated (ad hoc) Answers, in addition to CSV and PNG. + Spotter Answer export:: + XLSX and PDF export formats are now supported for Spotter-generated (ad hoc) Answers, in addition to CSV and PNG. -Custom PNG dimensions:: -Use `x_resolution` and `y_resolution` parameters to specify custom pixel dimensions for PNG exports. Accepted range: 600–3840 px per axis. Default: 2254 × 1588. + Custom PNG dimensions:: + Use `x_resolution` and `y_resolution` parameters to specify custom pixel dimensions for PNG exports. Accepted range: 600–3840 px per axis. Default: 2254 × 1588. -Display scaling:: -Use `scaling_factor` (range: 80–400) to adjust the relative size of chart elements in a PNG export without cropping the image. + Display scaling:: + Use `scaling_factor` (range: 80–400) to adjust the relative size of chart elements in a PNG export without cropping the image. -Dynamic file naming:: -Exported files are automatically named based on the Answer title with the correct file extension (`.png`, `.pdf`, `.csv`, `.xlsx`) appended. + Dynamic file naming:: + Exported files are automatically named based on the Answer title with the correct file extension (`.png`, `.pdf`, `.csv`, `.xlsx`) appended. -For more information, see xref:data-report-v2-api.adoc#answer-report[Answer Report API]. + For more information, see xref:data-report-v2-api.adoc#answer-report[Answer Report API]. -=== Snowflake Semantic View integration APIs + === Snowflake Semantic View integration APIs -// SOURCE: SCAL-309867 + // SOURCE: SCAL-309867 -ThoughtSpot 26.9.0.cl introduces REST API v2.0 endpoints for managing Snowflake Semantic View integrations programmatically. These APIs allow administrators and data managers to create, search, import, and delete semantic integration configurations without using the ThoughtSpot UI. + ThoughtSpot 26.9.0.cl introduces REST API v2.0 endpoints for managing Snowflake Semantic View integrations programmatically. These APIs allow administrators and data managers to create, search, import, and delete semantic integration configurations without using the ThoughtSpot UI. -[width="100%"] -[options="header"] -|===== -| Method | Endpoint | Description -| `POST` | `/api/rest/2.0/semantic-integrations/create` | Creates a new semantic integration by reading a Snowflake Semantic View and generating a ThoughtSpot data model. -| `POST` | `/api/rest/2.0/semantic-integrations/search` | Returns a list of semantic integrations matching the specified filter criteria. -| `POST` | `/api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/import` | Re-imports semantic updates from Snowflake and refreshes the associated ThoughtSpot data model. -| `POST` | `/api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/delete` | Deletes a semantic integration and its generated ThoughtSpot data model. -|===== + [width="100%"] + [options="header"] + |===== + | Method | Endpoint | Description + | `POST` | `/api/rest/2.0/semantic-integrations/create` | Creates a new semantic integration by reading a Snowflake Semantic View and generating a ThoughtSpot data model. + | `POST` | `/api/rest/2.0/semantic-integrations/search` | Returns a list of semantic integrations matching the specified filter criteria. + | `POST` | `/api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/import` | Re-imports semantic updates from Snowflake and refreshes the associated ThoughtSpot data model. + | `POST` | `/api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/delete` | Deletes a semantic integration and its generated ThoughtSpot data model. + |===== -Required privilege: `ADMINISTRATION` or `DATAMANAGEMENT`. If RBAC is enabled, the user also requires the `CAN_CREATE_OR_EDIT_CONNECTIONS` privilege and permission to manage data models. + Required privilege: `ADMINISTRATION` or `DATAMANAGEMENT`. If RBAC is enabled, the user also requires the `CAN_CREATE_OR_EDIT_CONNECTIONS` privilege and permission to manage data models. -For more information, see xref:semantic-integrations-api.adoc[Snowflake Semantic View integration APIs]. + For more information, see xref:semantic-integrations-api.adoc[Snowflake Semantic View integration APIs]. -=== Spotter Memory — General Availability + === Spotter Memory — General Availability -// SOURCE: SCAL-306173 + // SOURCE: SCAL-306173 -The Spotter Memory feature is generally available from 26.9.0.cl. The memory APIs introduced in 26.8.0.cl (`POST /api/rest/2.0/ai/memory/import` and `POST /api/rest/2.0/ai/memory/export`) are enabled by default on all ThoughtSpot Cloud instances. Administrators can manage and audit Spotter training data programmatically without enabling a feature flag. + The Spotter Memory feature is generally available from 26.9.0.cl. The memory APIs introduced in 26.8.0.cl (`POST /api/rest/2.0/ai/memory/import` and `POST /api/rest/2.0/ai/memory/export`) are enabled by default on all ThoughtSpot Cloud instances. Administrators can manage and audit Spotter training data programmatically without enabling a feature flag. -For more information, see xref:spotter-ai-memory-api.adoc[Spotter memory APIs]. + For more information, see xref:spotter-ai-memory-api.adoc[Spotter memory APIs]. -=== Spotter Agent — Conversation sharing APIs + === Spotter Agent — Conversation sharing APIs -// SOURCE: SCAL-306173 (aug.26.mt) + // SOURCE: SCAL-306173 (aug.26.mt) -ThoughtSpot 26.9.0.cl introduces REST API v2.0 endpoints for sharing saved Spotter agent conversations with other users or groups. Shared conversations are always `READ_ONLY`. + ThoughtSpot 26.9.0.cl introduces REST API v2.0 endpoints for sharing saved Spotter agent conversations with other users or groups. Shared conversations are always `READ_ONLY`. -[width="100%"] -[options="header"] -|===== -| Method | Endpoint | Description -| `POST` | `/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` | Shares a saved Spotter conversation with specified principals. Use `grant` and `revoke` arrays to manage access. -| `GET` | `/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content` | Returns the content of a shared Spotter conversation — messages, data sources, and answer details. -| `GET` | `/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info` | Returns sharing metadata — the list of principals the conversation is shared with and their access levels. The `is_shared_content_outdated` flag indicates if the shared snapshot is stale. -|===== + [width="100%"] + [options="header"] + |===== + | Method | Endpoint | Description + | `POST` | `/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` | Shares a saved Spotter conversation with specified principals. Use `grant` and `revoke` arrays to manage access. + | `GET` | `/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content` | Returns the content of a shared Spotter conversation — messages, data sources, and answer details. + | `GET` | `/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info` | Returns sharing metadata — the list of principals the conversation is shared with and their access levels. The `is_shared_content_outdated` flag indicates if the shared snapshot is stale. + |===== -For more information, see xref:spotter-agent-apis.adoc#_sharing_spotter_conversations[Sharing Spotter conversations]. + For more information, see xref:spotter-agent-apis.adoc#_sharing_spotter_conversations[Sharing Spotter conversations]. -=== KPI Sparkline setting in metadata search response + === KPI Sparkline setting in metadata search response -// SOURCE: SCAL-320899 + // SOURCE: SCAL-320899 -The `POST /api/rest/2.0/metadata/search` API response now includes the `isSparklineEnabled` field in the `AnswerSpecHeader` object for KPI chart type answers. This boolean field indicates whether the sparkline trend line is enabled for the KPI visualization. + The `POST /api/rest/2.0/metadata/search` API response now includes the `isSparklineEnabled` field in the `AnswerSpecHeader` object for KPI chart type answers. This boolean field indicates whether the sparkline trend line is enabled for the KPI visualization. -* `true` — the sparkline trend line is enabled. -* `false` — the sparkline is disabled. -* Absent — the answer was saved before this release and has not been re-saved. Treat an absent field as unknown, not as `false`. + * `true` — the sparkline trend line is enabled. + * `false` — the sparkline is disabled. + * Absent — the answer was saved before this release and has not been re-saved. Treat an absent field as unknown, not as `false`. -=== Outline Encoding — BYOC Muze + === Outline Encoding — BYOC Muze -// SOURCE: SCAL-317550 + // SOURCE: SCAL-317550 -ThoughtSpot 26.9.0.cl promotes mark outline color to a first-class data-driven encoding channel in the Muze charting library (BYOC). Developers building custom charts with Muze can now bind a data field to `encoding.outline` to produce ordinal color palettes (for categorical fields) or continuous gradient ramps (for measures), with full legend rendering and legend-to-mark interaction. + ThoughtSpot 26.9.0.cl promotes mark outline color to a first-class data-driven encoding channel in the Muze charting library (BYOC). Developers building custom charts with Muze can now bind a data field to `encoding.outline` to produce ordinal color palettes (for categorical fields) or continuous gradient ramps (for measures), with full legend rendering and legend-to-mark interaction. -The static `outline` config (`{ fill, color, width, dash }`) remains fully backward compatible. Supported mark types: Point, Bar, Arc. + The static `outline` config (`{ fill, color, width, dash }`) remains fully backward compatible. Supported mark types: Point, Bar, Arc. -=== Personalized Views TML portability — General Availability + === Personalized Views TML portability — General Availability -// SOURCE: SCAL-307284 + // SOURCE: SCAL-307284 -The Personalized Views TML portability feature introduced as Early Access in 26.8.0.cl is generally available from 26.9.0.cl. + The Personalized Views TML portability feature introduced as Early Access in 26.8.0.cl is generally available from 26.9.0.cl. -* The `author` field in Personalized View TML maps to the view owner's username or email, ensuring ownership is retained when a Liveboard is promoted across clusters or orgs. -* The `obj_id` field provides a stable cross-environment identifier for Personalized Views. -* Smart merge import: when importing a Liveboard TML that contains Personalized Views, ThoughtSpot preserves views that exist only in the target environment, appends new views from the imported TML, and updates views present in both. + * The `author` field in Personalized View TML maps to the view owner's username or email, ensuring ownership is retained when a Liveboard is promoted across clusters or orgs. + * The `obj_id` field provides a stable cross-environment identifier for Personalized Views. + * Smart merge import: when importing a Liveboard TML that contains Personalized Views, ThoughtSpot preserves views that exist only in the target environment, appends new views from the imported TML, and updates views present in both. -For more information, see xref:tml.adoc#personalized-views-portability[Personalized Views portability in TML]. + For more information, see xref:tml.adoc#personalized-views-portability[Personalized Views portability in TML]. -=== Connection configuration — Scheduled Liveboards process type + === Connection configuration — Scheduled Liveboards process type -// SOURCE: SCAL-312738 + // SOURCE: SCAL-312738 -ThoughtSpot 26.9.0.cl adds `SCHEDULED_LIVEBOARDS` as a new process type for Embrace connection configurations. Administrators can assign the Scheduled Liveboards process to a connection configuration, enabling ThoughtSpot to use the associated credentials when running scheduled Liveboard delivery jobs. Configurable via: + ThoughtSpot 26.9.0.cl adds `SCHEDULED_LIVEBOARDS` as a new process type for Embrace connection configurations. Administrators can assign the Scheduled Liveboards process to a connection configuration, enabling ThoughtSpot to use the associated credentials when running scheduled Liveboard delivery jobs. Configurable via: -* `POST /api/rest/2.0/connection/configuration/create` -* `PUT /api/rest/2.0/connection/configuration/{configuration_identifier}/update` + * `POST /api/rest/2.0/connection/configuration/create` + * `PUT /api/rest/2.0/connection/configuration/{configuration_identifier}/update` -=== AI Context — Spotter Optimization tab + === AI Context — Spotter Optimization tab -// SOURCE: SCAL-277656 + // SOURCE: SCAL-277656 -The AI Context generation UI is revamped in 26.9.0.cl. A new *Spotter Optimization* tab is introduced in the data model editor for managing AI context, replacing the previous AI Context panel. The tab provides a more streamlined interface for reviewing and editing auto-generated descriptions for columns and joins. + The AI Context generation UI is revamped in 26.9.0.cl. A new *Spotter Optimization* tab is introduced in the data model editor for managing AI context, replacing the previous AI Context panel. The tab provides a more streamlined interface for reviewing and editing auto-generated descriptions for columns and joins. -No changes to the AI context REST API endpoints in this release. + No changes to the AI context REST API endpoints in this release. + == Version 26.8.0.cl, August 2026 === Spotter AI APIs @@ -251,84 +252,1236 @@ Uploads a custom font file to ThoughtSpot. Returns custom fonts uploaded to the instance. * `PUT /api/rest/2.0/customization/styles/fonts/{font_identifier}/update` + -Updates a custom font record. +Updates the display name, weight, style, or color of an existing custom font. -* `DELETE /api/rest/2.0/customization/styles/fonts/{font_identifier}/delete` + -Deletes a custom font. +* `POST /api/rest/2.0/customization/styles/fonts/delete` + +Deletes one or more custom fonts from the font library. -For more information, see xref:style-customization-api.adoc[Style customization APIs]. +Logo export:: -=== Liveboard schedules +* `POST /api/rest/2.0/customization/styles/logos/export` + +Exports the current logo files as a ZIP archive containing the default logo and the wide logo. -* The `POST /api/rest/2.0/schedules/create` API endpoint now supports the `connection_configuration_identifier` attribute. This attribute specifies a configured Embrace connection configuration when creating a scheduled Liveboard job. -* The `POST /api/rest/2.0/schedules/{schedule_identifier}/update` API endpoint now supports the `connection_configuration_identifier` attribute. +For more information, see xref:customize-style-api.adoc[Style customization APIs]. -=== Tags API +=== Manual translation APIs +The manual translation API endpoints allow you to import, export, and delete translations of terms and labels that can be presented to the user based on their locale settings. -The `POST /api/rest/2.0/tags/assign` and `POST /api/rest/2.0/tags/unassign` API endpoints now support Collections as a metadata object type. +* `POST /api/rest/2.0/localizations/manual-translation/import` + +Allows importing a CSV file containing translated terms and labels. +* `POST /api/rest/2.0/localizations/manual-translation/locales/{locale}/export` + +Retrieves all translations for a specific locale as a JSON map. +* `POST /api/rest/2.0/localizations/manual-translation/export` + +Downloads all manually translated terms and labels in the Org context as a CSV file. +* `POST /api/rest/2.0/localizations/manual-translation/delete` + +Deletes all manual translations from the Org. -=== Custom actions +For more information, see xref:manual-translation.adoc[Manual translations]. -The `POST /api/rest/2.0/customization/custom-actions/create` and `POST /api/rest/2.0/customization/custom-actions/{custom_action_identifier}/update` API endpoints now support `group_identifiers` for access control. This allows restricting custom action visibility to specific user groups. +=== REST API Python SDK +The REST API Python SDK library artifacts are now available on link:https://pypi.org/project/thoughtspot-rest-api-sdk/[PyPI, window=_blank]. For information about how to install and use the SDK, see xref:rest-api-python-sdk.adoc[Python SDK]. == Version 26.6.0.cl, June 2026 === Spotter AI APIs -Answer Export API [earlyAccess eaBackground]#Early Access#:: -ThoughtSpot introduces the `POST /api/rest/2.0/report/answer` endpoint for exporting Answer data in CSV, XLSX, PDF, or PNG format. Requires the `isAnswerExportV2Enabled` feature flag to be enabled on the instance. +Stop in-progress agent response:: -For more information, see xref:data-report-v2-api.adoc#answer-report[Answer Report API]. +* `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response` + +Stops a Spotter agent response that is currently in progress for a given conversation session. -Stop Spotter response:: -The `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response` API endpoint stops an in-progress Spotter agent response for a given conversation session. The conversation session remains active after the response stops. +For more information, see xref:spotter-agent-apis.adoc#_stop_an_in_progress_agent_response[Stop an in-progress agent response]. -=== Connections +=== Authentication +The following new endpoints allow searching for the authentication configuration at the cluster or Org level, and also allow enabling and disabling authentication. These endpoints currently support only trusted authentication. -Connection configurations:: -ThoughtSpot introduces the following new API endpoints for managing Embrace connection configurations: +* `POST /api/rest/2.0/auth/configure` + +Enables or disables authentication at cluster or Org level for the specified auth type. +* `POST /api/rest/2.0/auth/search` + +Returns the authentication configuration for the specified auth type at cluster and Org level. -* `POST /api/rest/2.0/connection/configuration/create` + -Creates a connection configuration for an Embrace connection. -* `GET /api/rest/2.0/connection/configuration/{configuration_identifier}` + -Retrieves an existing connection configuration. -* `PUT /api/rest/2.0/connection/configuration/{configuration_identifier}/update` + -Updates an existing connection configuration. -* `DELETE /api/rest/2.0/connection/configuration/{configuration_identifier}/delete` + -Deletes a connection configuration. -* `POST /api/rest/2.0/connection/configuration/search` + -Returns a list of connection configurations matching the specified filter criteria. +=== Connection deactivate and activate API [beta betaBackground]^Beta^ -For more information, see xref:embrace-connection-configuration.adoc[Connection configurations]. +// SOURCE: SCAL-294844, SCAL-294845, SCAL-278132 -=== REST API Python SDK +ThoughtSpot introduces REST API v2.0 endpoints to programmatically deactivate and activate data connections: + +* `POST /api/rest/2.0/connections/{connection_identifier}/status` + +Deactivates or activates a connection. + +=== Answer report API enhancements [earlyAccess eaBackground]#Early Access# + +The `POST /api/rest/2.0/report/answer` API endpoint introduces the following enhancements: + +Pinned Answer export:: +// SOURCE: SCAL-236681, SCAL-306548 +You can now export a pinned Answer directly from a Liveboard using the Answer report API. +To export a pinned Answer, specify the `viz_guid` parameter in your API request. +Exports from this endpoint inherently respect Liveboard-level filters, Runtime Filters, Column security rules, and JWT token context. ++ +To export a specific personalized view of a pinned Answer, include the `personalised_view_identifier` parameter. + +Spotter Answer export:: +XLSX and PDF export formats are now supported for Spotter (conversational) Answers. -ThoughtSpot provides the REST API Python SDK (`thoughtspot-rest-api-sdk`) to help Python developers interact programmatically with ThoughtSpot REST API v2 endpoints. The SDK is available on link:https://pypi.org/project/thoughtspot-rest-api-sdk/[PyPI, window=_blank]. +Custom PNG dimensions:: +PNG exports now support custom dimensions via the following new parameters: ++ +* `x_resolution`: Sets the export width in pixels. Valid range: 600–3840 px. +* `y_resolution`: Sets the export height in pixels. Valid range: 600–3840 px. + +Display scaling:: +A new `scaling` parameter allows you to adjust the relative size of visual elements in PNG exports without cropping. +Valid range: 80–500%. -For information about how to install and use the SDK, see xref:rest-api-sdk-python.adoc[Python SDK for REST APIs]. +Automatic file naming:: +The API now automatically names exported files based on the Answer title and appends the correct file extension (`.png`, `.pdf`, `.csv`, or `.xlsx`). + +Contact ThoughtSpot Support to enable these settings for PNG downloads on your ThoughtSpot instance. +For more information, see xref:data-report-v2-api.adoc#_answer_report_api[Answer report API documentation]. + +=== Share metadata API: Collections support [beta betaBackground]^Beta^ + +The `POST /api/rest/2.0/security/metadata/share` endpoint now supports sharing Collections. + +To share a Collection, set `metadata_type` to `COLLECTION` in the request body. +For more information, see xref:collections.adoc#share-collection[Share a Collection]. == Version 26.5.0.cl, May 2026 -=== Spotter AI APIs +=== Sync connection metadata attributes +You can now synchronize connection metadata attributes from your Cloud Data Warehouse (CDW) with ThoughtSpot by sending a request to the `POST /api/rest/2.0/connections/{connection_identifier}/resync-metadata` API endpoint. -The following API endpoints are deprecated in 26.5.0.cl: +=== Spotter APIs -* `POST /api/rest/2.0/ai/agent/converse/sse` — Use `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream` instead. -* `POST /api/rest/2.0/ai/agent/{conversation_identifier}/converse` — Use `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send` instead. +==== New API endpoints -New API endpoints:: +The following new endpoints allow sending messages to an active conversation +session with a Spotter agent. * `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send` + -Sends natural language messages to an existing Spotter agent conversation and returns the complete response synchronously. - +Allows sending a message to an active Spotter AI conversation and returns a synchronous response. * `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream` + -Sends natural language messages to an existing Spotter agent conversation and returns the response as a real-time Server-Sent Events (SSE) stream. +Allows sending to an active Spotter AI conversation and returns the response as a real-time Server-Sent Events (SSE) stream. + +These new endpoints replace the legacy agent conversation and SSE streaming APIs. + +==== Deprecated endpoints [.version-badge.deprecated]#Deprecated# + +* `POST /api/rest/2.0/ai/agent/{conversation_identifier}/converse` + +Replaced by `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send`. + +* `POST /api/rest/2.0/ai/agent/converse/sse` + +Replaced by `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream` + +These endpoints are deprecated and will be removed in a future release. Embedding applications and integrations using these APIs are advised to migrate to the new API endpoints for improved experience. + +==== Enhancements to conversation creation API [.version-badge.breaking]#Breaking# + +The following enhancements have been introduced for the conversation creation operation workflow with the `POST /api/rest/2.0/ai/agent/conversation/create` API endpoint: + +metadata_context:: +To define the conversation context, the API request must include the `metadata_context` parameter with one of the following values: + +* `AUTO_MODE`: Automatically discovers and selects the most relevant datasets for the user's queries. +* `DATA_SOURCE`: Sets the target context as the data source. You must specify at least one data source ID. +** To set a single data source object metadata context, specify a `data_source_identifier`. +** For multi-data source context, specify the `data_source_identifiers`. ++ +[IMPORTANT] +==== +The `data_source` and `guid` attributes are deprecated in the 26.5.0.cl release version. Integrations using these parameters in ThoughtSpot versions 26.2.0.cl through 26.4.0.cl will continue to work until further notice. However, ThoughtSpot recommends using either `AUTO_MODE` or `DATA_SOURCE` with `data_source_identifier` or `data_source_identifiers` for the metadata context. +==== + +Other context options:: +The `answer_context` and `liveboard_context` are removed and no longer supported. Any existing integration or embedding application passing `answer_context` or `liveboard_context` in the request body must update their workflows to use the `AUTO_MODE` or `DATA_SOURCE` option. + +Enable save chat:: +The `enable_save_chat` parameter, when set to `true`, saves the conversation. + +API response:: +The API response now returns the `conversation_identifier`, which is used in all +subsequent send message or SSE streaming calls. + +=== Liveboard report API enhancements [beta betaBackground]^Beta^ +The `POST /api/rest/2.0/report/liveboard` API endpoint enhances the PDF downloads by introducing the following parameters: + +* `"page_size": "CONTINUOUS"` for a seamless PDF export that matches the full length of your Liveboard. Unlike the A4 format, which introduces forced page breaks between visualizations, this continuous flow maintains your exact design and intended layout. +* `zoom_level` offers various download size options to suit the viewer's screen dimensions, thereby enhancing legibility. This can be set only when `page_size` is specified as `CONTINUOUS`. + +For more information, see xref:data-report-v2-api.adoc#_liveboard_report_api[Liveboard Report API documentation]. + +=== Metadata search API enhancements + +Personalized Views in metadata search:: +The `POST /api/rest/2.0/metadata/search` API endpoint introduces the `include_personalised_views` request parameter. + +When both `include_details: true` and `include_personalised_views: true` are specified in the request, the API returns a `personalised_views` array in the `metadata_detail` object for `LIVEBOARD` metadata type responses. + +This allows you to retrieve the full list of Personalized Views associated with a Liveboard in a single API call, without requiring a separate TML export. + +For more information, see xref:rest-api-v2-metadata-search.adoc#_include_personalised_views[Search metadata API]. + +=== TML API enhancements +The previous limit of 100 Personalized Views per Liveboard on TML import has been removed. You can now import all associated Personalized Views of a Liveboard without any views being dropped. For more information, see the xref:tml-api.adoc[TML API documentation]. + +== Version 26.4.0.cl, April 2026 + +=== Variable API endpoints +The following endpoints are introduced for bulk delete and update operations for variables: + +* `POST /api/rest/2.0/template/variables/{identifier}/update-values` + +Assigns multiple values to a variable and sets the scope for variable values in a single API request. +* `POST /api/rest/2.0/template/variables/delete` + +Deletes one or more variables in a single API request. + +These new API endpoints replace the following legacy API endpoints deprecated in 26.4.0.cl. + +* `POST /api/rest/2.0/template/variables/{identifier}/delete` +* `POST /api/rest/2.0/template/variables/update-values` + +Your existing implementation with the legacy API endpoints will continue to work until further notice. However, these endpoints will be removed from ThoughtSpot in a future release. Hence, we recommend updating your workflows to use the API endpoints at your earliest convenience. + +For more information, see xref:variables.adoc[Variable API documentation]. + +=== Metadata parameterization +You can now parameterize multiple fields in a metadata object in a single API request using the `/api/rest/2.0/metadata/parameterize-fields` API endpoint. +This endpoint replaces the legacy `/api/rest/2.0/metadata/parameterize` endpoint, which is deprecated in 26.4.0.cl. + +For more information, see xref:metadata-parameterization.adoc[Metadata parameterization API documentation]. + +=== Webhook integration +This release introduces the following features and enhancements to the webhook integration workflows: + +Custom HTTP headers in webhook requests:: +Administrators can configure custom HTTP headers to send in webhook requests triggered by ThoughtSpot, in addition to the standard HTTP and authentication headers. You can specify these headers in the `additional_headers` attribute during webhook creation (`/api/rest/2.0/webhooks/create`) and update (`/api/rest/2.0/webhooks/{webhook_identifier}/update`) via REST APIs. + +Webhook connection validation:: +You can now validate a webhook connection by sending a test payload via an API request to the `/api/rest/2.0/system/communication-channels/validate` endpoint. The API returns a response indicating the connection and authentication status for a given webhook connection. + +Webhook monitoring:: +To monitor the status of webhook jobs and scheduled events, ThoughtSpot introduces the `/api/rest/2.0/jobs/history/communication-channels/search` API endpoint. + +For more information, see xref:webhooks-comm-channel.adoc[Webhook configuration validation and monitoring]. + +=== Collections API endpoints + +The following APIs are introduced for Collections: + +* `POST /api/rest/2.0/collections/create` [beta betaBackground]^Beta^ + +Creates a new Collection. +* `POST /api/rest/2.0/collections/search` [beta betaBackground]^Beta^ + +Searches for a Collection in ThoughtSpot +* `POST /api/rest/2.0/collections/{collection_identifier}/update` [beta betaBackground]^Beta^ + +Updates an existing Collection +* `POST /api/rest/2.0/collections/delete` [beta betaBackground]^Beta^ + +Deletes a Collection + +For more information, see xref:collections.adoc[Collections]. + +=== Email customization API enhancements + +The `template_properties` parameter now has the `hide_logo_url` elements for email template customization. Set it to `true` to entirely hide the logo component in the ThoughtSpot notification emails. + +=== Spotter API enhancements +Spotter AI APIs now support the following error responses: + +* 401 Unauthorized: authentication token is missing, expired, or invalid. +* 403 Forbidden: the authenticated user does not have `CAN_USE_SPOTTER` privilege or view access to the underlying metadata sources. + +=== Pivot table .xlsx exports +The following API endpoints now support pivot tables in `.xlsx` downloads with full visual and structural parity: + +* `POST /api/rest/2.0/report/answer` +* `POST /api/rest/2.0/schedules/create` + +To enable pivot formatting on your ThoughtSpot instance, contact ThoughtSpot Support. + +== Version 26.3.0.cl, March 2026 + +=== Webhook APIs + +The Webhook API allows configuring Amazon S3 buckets as a storage destination for webhook payload delivery. + +* `POST /api/rest/2.0/webhooks/create` + +Configures storage destination for webhook delivery. +* `POST /api/rest/2.0/webhooks/{webhook_identifier}/update` + +Allows modifying storage configuration for a webhook. +* `POST /api/rest/2.0/webhooks/search` + +Retrieves storage configuration details. + +=== Object privilege APIs +Administrators and users with edit access to data models can now use `/api/rest/2.0/security/metadata/manage-object-privilege` to assign object-level permissions to users and groups and control access to Spotter data model instructions. + +To fetch object privileges for a data model, user, or group, use the `/api/rest/2.0/security/metadata/fetch-object-privileges` API endpoint. + +For more information, see xref:spotter-nl-instructions.adoc#_spotter_data_model_instructions_access[Spotter data model instructions access]. + + +=== User API enhancements + +The user APIs now support setting browser language as the default locale for ThoughtSpot users. Administrators can set the `use_browser_language` parameter as the default locale for ThoughtSpot users during the following API operations: + +* When creating a new user via `POST /api/rest/2.0/users/create` + +* When importing users via `POST /api/rest/2.0/users/import` + +* When updating user preferences via `POST /api/rest/2.0/users/{user_identifier}/update` + + +When set to `true`, a user's current locale preference is overridden and the browser's language takes precedence. + +The status of the browser language setting for a given user can also be retrieved using the following API endpoints: + +* `POST /api/rest/2.0/users/search` + +* `POST /api/rest/2.0/users/activate` + +* `GET /api/rest/2.0/auth/session/user` + + +=== Custom token generation API +Note the following changes to request parameters for the `/api/rest/2.0/auth/token/custom` API endpoint: + +* The `filter_rules` parameter on the custom token authentication (`/api/rest/2.0/auth/token/custom`) page in the REST API Playground is no longer available for new configurations. Existing implementations that use `filter_rules` continue to work. However, we strongly recommend migrating to `variable_values` and ABAC via RLS for data security. + +* The `parameter_values` property is supported in the current release but will be deprecated in an upcoming version. Using `parameter_values` for row-level security will be phased out with this deprecation. Therefore, we recommend generating JWTs that pass data security attributes through formula variable attributes instead of `filter_rules` or `parameter_values` for ABAC. + +For more information, see xref:abac-migration-guide.adoc[ABAC JWT migration guide] and xref:abac_rls-variables.adoc[ABAC via RLS]. + +== Version 26.2.0.cl, February 2026 + +=== Security settings APIs +This release introduces the following Security settings APIs: + +* `POST /api/rest/2.0/system/security-settings/configure` + +Allows configuring security settings at the Org level or for all Orgs on a ThoughtSpot instance. +* `POST /api/rest/2.0/system/security-settings/search` + +Gets a list of security settings configured on a specific Org or for all Orgs on a ThoughtSpot instance. + +For more information, see xref:security-settings.adoc[Security Settings]. + +=== Connection API +ThoughtSpot administrators can now revoke OAuth refresh tokens for users who no longer require access to a data warehouse connection via the `/api/rest/2.0/connections/{connection_identifier}/revoke-refresh-tokens` API endpoint. When a token is revoked, the affected user's session for that connection is terminated, and they must re-authenticate to regain access. + +=== Connection configuration API enhancements +You can now include `same_as_parent` and `policy_process_options` attributes in your API request to `/api/rest/2.0/connection-configurations/create` and `/api/rest/2.0/connection-configurations/{configuration_identifier}/update` endpoints. + +The `same_as_parent` parameter specifies if the configuration should inherit settings from its parent. The `policy_process_options` attribute can be used to define additional policy or processing options for the connection, to allow granular control over connection behavior. + +=== Liveboard Report API enhancements +You can now download Liveboard reports in the CSV and XLSX formats through the `POST /api/rest/2.0/report/liveboard` API endpoint. Both these options are Early Access features. + +For more information, see xref:data-report-v2-api.adoc[Data and Report APIs]. + +=== Email customization API enhancements + +The `template_properties` parameter now has two additional elements for email template customization: + +* `contact_support_url` to add a customized link for contacting customer support. +* `hide_contact_support_url` to hide the option of adding a link for customer support. + +=== System configuration API enhancements +The API response from the `/api/rest/2.0/system/config` endpoint indicates whether SAML or Okta authentication is enabled on the system. + +=== User API enhancements + +* `POST /api/rest/2.0/users/import` + +The `preferred_locale` parameter allows configuring the preferred locale for users being imported via API request. +* `POST /api/rest/2.0/users/search` + +The `include_variable_values` parameter in the API request allows including variable values in the search response. The variable values can be assigned for a user via xref:abac_rls-variables.adoc[ABAC tokens] or xref:variables.adoc#_define_values_and_scope_for_variables[variable API documentation]. + +== Version 10.15.0.cl, December 2025 + +=== Spotter APIs + +This release introduces the following Spotter APIs: + +* `POST /api/rest/2.0/ai/instructions/set` + +Allows configuring natural language (NL) instructions on a data model to define how Spotter interprets queries, handles data nuances, and improves responses. +* `POST /api/rest/2.0/ai/instructions/get` + +Gets NL instructions that are currently assigned to a model. +* `POST /api/rest/2.0/ai/data-source-suggestions` + +Retrieves a list of recommended data sources based on the specified query string. + +For more information, see xref:spotter-apis.adoc[Spotter AI APIs]. + +=== Variable APIs + +You can now create formula variables using the `/api/rest/2.0/template/variables/create` API endpoint, and assign values and scope to these variables using the `/api/rest/2.0/template/variables/update-values` API endpoint. + +For more information, see xref:variables.adoc[Configure variables]. + +=== ABAC tokens with formula variable attributes +The `/api/rest/2.0/auth/token/custom` API endpoint allows creating a token request with formula variables for ABAC via RLS implementation. + +For more information, see xref:abac-user-parameters.adoc[ABAC via tokens]. + +== Version 10.14.0.cl, November 2025 + +=== New API endpoints + + + +System:: +This release introduces the following endpoints for configuring communication channel preferences. + +* `POST /api/rest/2.0/system/preferences/communication-channels/configure` [beta betaBackground]^Beta^ + +Sets a communication channel preference for all Orgs at the cluster level or at the individual Org level. +* `POST /api/rest/2.0/system/preferences/communication-channels/search` [beta betaBackground]^Beta^ + +Gets details of the communication channel preferences configured on ThoughtSpot. ++ +For more information, see xref:webhooks-comm-channel.adoc[Configure and monitor communication channels]. + +Webhook:: +The following APIs are introduced for webhook CRUD operations: +* `POST /api/rest/2.0/webhooks/create` +Creates a webhook. +* `POST /api/rest/2.0/webhooks/{webhook_identifier}/update` +Updates the properties of a webhook. +* `POST /api/rest/2.0/webhooks/search` +Gets a list of webhooks configured in ThoughtSpot or in a specific Org. +* `POST /api/rest/2.0/webhooks/delete` +Deletes the webhook. ++ +For more information, see xref:webhooks-lb-schedule.adoc[Webhooks for Liveboard schedule events]. + +Column security rules:: + +* `POST /api/rest/2.0/security/column/rules/update` + +Updates column security rules for a given Table. + +* `POST /api/rest/2.0/security/column/rules/fetch` + +Gets details of column security rules for the tables specified in the API request. + +//// + +Spotter:: +POST /api/rest/2.0/ai/agent/{conversation_identifier}/converse +//// +=== Variable API enhancements + +The variable API enhancements are listed in the following sections. For additional details, see xref:variables.adoc[Define variables]. + +==== Variable creation API + +* The variable creation endpoint `/api/rest/2.0/template/variables/create` does not support assigning values to a variable. To assign values to a variable, use the `/api/rest/2.0/template/variables/update-values` endpoint. +* The `sensitive` parameter is renamed as `is_sensitive`. + +==== Variables update APIs [tag redBackground]#BREAKING CHANGE# + +The `/api/rest/2.0/template/variables/update` endpoint is deprecated and replaced with `/api/rest/2.0/template/variables/update-values`. + +To update the properties of a specific variable, use the `/api/rest/2.0/template/variables/{identifier}/update` endpoint and to assign values to one or several variables in a single API call, use the `POST /api/rest/2.0/template/variables/update-values` endpoint. + +==== Variables search API + +* The variables search API endpoint `/api/rest/2.0/template/variables/search` now includes the `value_scope` parameter that allows you to filter the API response by the objects to which the variable is mapped. +* Filtering API response by `EDITABLE_METADATA_AND_VALUES` is no longer supported. + + +=== User API enhancements +The following APIs now support the `variable_values` parameter. The `variable_values` property can be used for user-specific customization. + +* `POST /api/rest/2.0/users/create` +* `POST /api/rest/2.0/users/search` +* `POST /api/rest/2.0/users/activate` + +=== DBT API enhancements +The `/api/rest/2.0/dbt/generate-tml` endpoint supports the `model_tables` attribute to list models and their tables. + +//// + +=== Authentication API +Support for `variable_values` property in `/api/rest/2.0/auth/session/user` API calls. + +//// + +== Version 10.13.0.cl, October 2025 + +=== New API endpoints + +Spotter:: + +* `POST /api/rest/2.0/ai/agent/conversation/create` + +Creates a new AI-driven conversation session based on a specified data source. The resulting session sets the context for subsequent queries and responses. + + + +* `POST /api/rest/2.0/ai/relevant-questions/` + +Breaks down a user-submitted query into a series of analytical sub-questions using relevant contextual metadata. + +* `POST /api/rest/2.0/ai/agent/converse/sse` + +Allows sending a follow-up message or question to an ongoing conversation session and returns the AI agent's response, including answers, tokens, and visualization details. + + +For more information, see xref:spotter-apis.adoc[Spotter AI APIs]. + +Email customization:: +`POST /api/rest/2.0/customization/email/update` + +Updates an existing email customization. For more information, see xref:customize-email-apis.adoc[Customize email template]. + +=== API enhancements +The following APIs were modified to include new parameters: + +TML export:: +The TML export API now supports the `export_with_column_aliases` parameter in `export_options` to indicate whether to export column aliases of the model. + +Email customization:: +The `/api/rest/2.0/customization/email/update` and `/api/rest/2.0/customization/email` APIs now include `company_privacy_policy_url` and `company_website_url` properties in template variables, and a new `org_identifier` parameter in the API request. + +For more information, see xref:customize-email-apis.adoc[Customize email template]. + +=== Deprecated endpoints + +Spotter:: +The `POST /api/rest/2.0/ai/analytical-questions` Spotter AI API [beta betaBackground]^Beta^ is deprecated and replaced with the new API endpoint, `POST /api/rest/2.0/ai/relevant-questions/`. + +Email customization:: +The `POST /api/rest/2.0/customization/email/{template_identifier}/delete` email customization API is deprecated and replaced with the new API endpoint, `POST /api/rest/2.0/customization/email/delete`. + + +//// +=== Deprecated endpoints +The following Spotter AI APIs [beta betaBackground]^Beta^ are deprecated and replaced with the new xref:spotter-apis.adoc[AI APIs]. + +* `POST /api/rest/2.0/ai/conversation/create` +* `POST /api/rest/2.0/ai/analytical-questions` +* `POST /api/rest/2.0/ai/conversation/{conversation_identifier}/converse` +//// + +== Version 10.12.0.cl, September 2025 + +=== New API endpoints + +The following API endpoints are now available: + +Custom calendar:: +* `POST /api/rest/2.0/calendars/create` + +Creates a custom calendar. +* `POST /api/rest/2.0/calendars/generate-csv` + +Exports a custom calendar in the CSV format. +* `POST /api/rest/2.0/calendars/search` + +Gets custom calendars for the connection ID specified in the API request. +* `POST /api/rest/2.0/calendars/{calendar_identifier}/delete` + +Deletes a custom calendar. +* `POST /api/rest/2.0/calendars/{calendar_identifier}/update` + +Updates a custom calendar. + +Connection configuration:: +* `POST /api/rest/2.0/connection-configurations/create` + +Creates an additional configuration to an existing connection to a data warehouse. +* `POST /api/rest/2.0/connection-configurations/search` + +Gets the required connection configuration objects. +* `POST /api/rest/2.0/connection-configurations/{configuration_identifier}/update` + +Updates an existing connection configuration object. +* `POST /api/rest/2.0/connection-configurations/delete` + +Deletes the connection configuration object. + +=== Enhancements to APIs + +Export API endpoint:: + +* Answer TML: + +The `POST /api/rest/2.0/metadata/tml/export` API endpoint now allows fetching TML for Answer objects that do not have an ID or name assigned. The `session_identifier` and `generation_number` parameters allow you to define the session ID and the Answer generation number in the API request. These optional attributes can be used for unsaved Answers generated from Spotter queries. + +* Table TML: + +The `POST /api/rest/2.0/metadata/tml/export` API request allows exporting column security rules for Table TML objects. This attribute will export column security rules only if the object specified in the API request has column security applied and when `export_associated` is set to `true`. + +== Version 10.11.0.cl, July 2025 + +=== Search metadata API enhancements +The search metadata (`/api/rest/2.0/metadata/search`) API includes the following enhancements: + +* The `liveboard_reponse_version` parameter. It allows you to specify the xref:rest-api-v2-metadata-search.adoc#_response_format_for_liveboards[response format for Liveboard objects]. +* The `subtypes` attribute to specify the sub-type for the `LOGICAL_TABLE` metadata type. The `LOGICAL_TABLE` type allows you to fetch objects such as Tables, Models, and Views. The `subtypes` parameter allows you to filter API response by specifying subcategories of the object type. +* The `include_only_published_objects` attribute to specify whether the search should include xref:publish-api.adoc[published objects]. + + +=== System API +The API response generated from the `GET /api/rest/2.0/system/config-overrides` requests now returns the overrides in the `config_override_info` object. + +=== TML API +The API response for the `POST /api/rest/2.0/metadata/tml/async/import` and `POST /api/rest/2.0/metadata/tml/async/status` now includes the `author_display_name` property. This property shows the display name of user that initiated the asynchronous TML import request. + +=== REST API Java SDK + +The REST API Java SDK library artifacts are now available in the `com.thoughtspot` Maven namespace. If you are using Maven Central to import the REST API SDK artifacts, update the group ID in your `pom.xml` file to `com.thoughtspot` and the artifact ID to `rest-api-sdk`. + +For more information, see xref:rest-api-java-sdk.adoc#_import_the_sdk_to_your_application_environment[REST API Java SDK]. + +== Version 10.10.0.cl, July 2025 + +=== Email template customization APIs +This release introduces the following new endpoints for email template customization: + +* `POST /api/rest/2.0/customization/email` + +Allows you to personalize the ThoughtSpot notification emails content. +* `POST /api/rest/2.0/customization/email/{template_identifier}/delete` + +Removes the customizations done for the ThoughtSpot notification emails. +* `POST /api/rest/2.0/customization/email/search` + +Allows searching the email customization configuration if configured for ThoughtSpot. +* `POST /api/rest/2.0/customization/email/validate` + +Validates the email customization configuration if configured for ThoughtSpot. + +=== Group API + +The `/api/rest/2.0/groups/search` endpoint now supports the following new options in group search API requests: + +* `include_users` + +When set to `true`, it includes user details in the group search API response. +* `include_sub_groups` + +When set to `true`, it includes sub-groups in the group search response. + +=== Schedule API +You can now specify the `personalised_view_id` of a Liveboard in API requests to the following schedule APIs: + +* `POST /api/rest/2.0/schedules/create` +To schedule a job for a personalized view of the Liveboard, specify the `personalised_view_id`. +* `POST /api/rest/2.0/schedules/{schedule_identifier}/update` +To update schedule details for a specific view of the Liveboard, specify the `personalised_view_id`. + +== Version 10.9.0.cl, June 2025 + +=== Metadata parameterization and content publishing across Orgs + +This release introduces the following new endpoints for metadata parameterization [beta betaBackground]^Beta^ and content publishing [beta betaBackground]^Beta^ across Orgs. To enable the content publishing feature and the related API operations on your instance, contact ThoughtSpot Support. + +* `POST /api/rest/2.0/metadata/parameterize` [beta betaBackground]^Beta^ + +Allows you to parameterize fields in metadata objects. +* `POST /api/rest/2.0/metadata/unparameterize` [beta betaBackground]^Beta^ + +Allows removing parameterization from fields in metadata objects +* `POST /api/rest/2.0/security/metadata/publish` [beta betaBackground]^Beta^ + +Publish metadata objects to one or several Orgs on an instance. +* `POST /api/rest/2.0/security/metadata/unpublish` [beta betaBackground]^Beta^ + +Removes published metadata objects from the Orgs specified in the API request. +* `POST /api/rest/2.0/template/variables/create` [beta betaBackground]^Beta^ + +Allows creating a template variable which can be used to parameterize fields in a metadata object. +* `POST /api/rest/2.0/template/variables/search` [beta betaBackground]^Beta^ + +Allows searching template variables +* `POST /api/rest/2.0/template/variables/{identifier}/update` [beta betaBackground]^Beta^ + +Allows updating properties of a template variable. +* `POST /api/rest/2.0/template/variables/update` [beta betaBackground]^Beta^ + +Allows you to add, remove, or replace properties of one or several template variables. +* `POST /api/rest/2.0/template/variables/{identifier}/delete` [beta betaBackground]^Beta^ + +Deletes a template variable. + +If your metadata objects are parameterized, you can use the `show_resolved_parameters` to filter the API response from `/api/rest/2.0/connection/search` and `/api/rest/2.0/metadata/search` endpoints to get only the objects with resolved parameterized values. + +=== Liveboard Report API +The Liveboard Report API now allows you to define the following properties: + +* `tab_identifiers` + +Optional parameter to specify the name or GUID of a Liveboard tab to export only the visualizations in that tab. +* `personalised_view_identifier` + +Optional parameter to specify the GUID of the Liveboard personalized view that you want to download. + +In addition to these parameters, you can also define the following properties for PNG downloads: + +* `image_resolution` +* `image_scale` +* `include_header` + +For more information, see xref:data-report-v2-api.adoc#_liveboard_report_api[Liveboard Report API]. + +=== REST API Java SDK + +The REST API Java SDK enables developers to interact programmatically with ThoughtSpot REST APIs from Java applications. It provides a client library with Java methods and classes that map to API endpoints, handle authentication, send API requests, and allow creating and modifying ThoughtSpot resources and objects. + +For information about how to install and use the SDK, see xref:rest-api-java-sdk.adoc[Java SDK for REST APIs]. + + +== Version 10.8.0.cl, April 2025 + +=== New API endpoints + +This version introduces the following endpoints: + +* `POST /api/rest/2.0/metadata/update-obj-id` + +Update object IDs for given metadata objects. + + +[NOTE] +==== +An object ID is a user-defined ID assigned to a ThoughtSpot object in addition to the system-generated GUID. +Note that the object ID generation for metadata objects is disabled by default. If this feature is enabled on your instance, you can use the `POST /api/rest/2.0/metadata/update-obj-id` to assign or update the object ID. +==== + +=== Metadata API + +* The `POST /api/rest/2.0/metadata/search` endpoint now supports the following parameters: + +** `include_discoverable_objects` + +Allows including Answers and Liveboards that are marked as discoverable by the object owner. +** `metadata_obj_id` + +Filters metadata objects by the user-defined object ID. This parameter returns data only if the user-defined object ID feature is enabled on your instance. -Breaking changes in `POST /api/rest/2.0/ai/agent/conversation/create`:: -The `metadata_context` object now requires `type` to be one of `AUTO_MODE` or `DATA_SOURCE`. The legacy `data_source` option is deprecated. +=== TML APIs + +* The `all_orgs_context` parameter in TML import APIs (`/api/rest/2.0/metadata/tml/import` and `/api/rest/2.0/metadata/tml/async/import`) is deprecated and removed from the Playground. Use `all_orgs_override` to define the Org context in your API requests. + +* The TML export API now allows exporting TML content with user feedback received for objects such as AI-generated Answers. The `export_with_associated_feedbacks` attribute is set to `false` by default. + +=== Report APIs +The Liveboard export API (`/api/rest/2.0/report/liveboard`) now allows overriding filters applied to a Liveboard. The `override_filters` array allows specifying several types of filters and updates the Liveboard data during export. + +For more information, see xref:data-report-v2-api.adoc#_override_filters[Override filters]. + +== Version 10.6.0.cl, March 2025 + +=== New metadata API endpoints + +* `POST /api/rest/2.0/metadata/headers/update` + +Updates metadata header for a given list of objects. +* `POST /api/rest/2.0/metadata/worksheets/convert` + +Converts a Worksheet object to a Model. + +=== Report APIs +[tag redBackground]#BREAKING CHANGE# + +Downloading Liveboard reports in the CSV and XLSX file format via `POST /api/rest/2.0/report/liveboard` API endpoint is not supported. The CSV and XLSX `file_format` options have been removed because they were not functioning in the expected manner. + +==== Parameters for regional settings + +The `/api/rest/2.0/report/answer` and `/api/rest/2.0/report/liveboard` now allow users to define the following `regional_settings` attributes: + +* `currency_format` +* `user_locale` +* `number_format_locale` +* `date_format_locale` + +=== Custom object ID in TML and Metadata APIs + +The following API endpoints allow you to specify a custom object ID (`obj_identifier`) in the metadata object properties: + +* `POST /api/rest/2.0/metadata/search` +* `POST /api/rest/2.0/metadata/headers/update` +* `POST /api/rest/2.0/metadata/tml/export` + + +=== TML import API + +The `/api/rest/2.0/metadata/tml/async/import` and `POST /api/rest/2.0/metadata/tml/import` endpoints allow skipping diff check when processing TMLs for imports. The `skip_diff_check` attribute is disabled by default and can be enabled to avoid importing objects that do not have any changes. + +=== API response changes + +The 200 and 201 response body from `POST /api/rest/2.0/ai/answer/create` and `POST /api/rest/2.0/ai/conversation/{conversation_identifier}/converse` API calls now includes the `display_tokens` property. + + +== Version 10.5.0.cl, December 2024 + +=== Custom access token API +The `/api/rest/2.0/auth/token/custom` API endpoint allows setting the following attributes in API requests: + +* `auto_create` + +Creates a user if username specified in the API request is not available in ThoughtSpot. By default, the `auto_create` is set to `true`. +* `REPLACE` enum for `persist_option` + +Allows replacing persisted values with new attributes defined in the token generation API request. For more information, see xref:abac-user-parameters.adoc[ABAC via tokens]. + +=== TML import APIs + +TML async import:: + +The `/api/rest/2.0/metadata/tml/async/import` supports setting the following properties via API requests: ++ +* `import_policy` + +Allows you to specify if all objects should be imported during the TML import operation. Valid values are: + +** `PARTIAL_OBJECT` (default) +** `PARTIAL` +** `VALIDATE_ONLY` +** `ALL_OR_NONE` + +* `enable_large_metadata_validation` + +Indicates if the TMLs with large and complex metadata should be validated before the import. ++ +For more information about these attributes, see xref:tml.adoc#_import_tml_objects_asynchronously[Import TML objects asynchronously]. + +TML import API:: + +The `/api/rest/2.0/metadata/tml/import` API also supports setting the `enable_large_metadata_validation` attribute for large and complex metadata objects during TML import. + +TML export API:: + +The `/api/rest/2.0/metadata/tml/export` endpoint now allows you to include additional attributes when exporting TML for an object from ThoughtSpot. The `export_options` allows you to include the following optional attributes: + +* `include_obj_id_ref` + +Specifies whether to export `user_defined_id` of the referenced object. This setting is valid only if the `UserDefinedId` property in TML is enabled. +* `include_guid` + +Specifies whether to export the GUID of the object. This setting is valid only if the `UserDefinedId` property in TML is enabled. +* `include_obj_id` + +Specifies whether to export the `user_defined_id` of the object. This setting is valid only if the `UserDefinedId` property in TML is enabled. + + +Share metadata:: + +The `email` attribute is now optional in the `POST` request body sent to the `/api/rest/2.0/security/metadata/share` API endpoint. + +Role API:: + +The `/api/rest/2.0/roles/create` API endpoint now allows setting `read_only` attribute to specify if the role is read only. A read-only role cannot be updated or deleted. + +== Version 10.4.0.cl, November 2024 + +=== New API endpoints + +Spotter AI APIs [beta betaBackground]^Beta^ :: + +* `POST /api/rest/2.0/ai/conversation/create` + +Creates a conversation session. +* `POST /api/rest/2.0/ai/conversation/{conversation_identifier}/converse` + +Generates responses for user queries and follow-up questions. +* `POST /api/rest/2.0/ai/answer/create` + +Generates an Answer from a Natural Language Search query. + +Authentication:: +The `/api/rest/2.0/auth/token/custom` API endpoint is now available to generate an authentication token with custom rules and filter conditions for a user. + ++ +ThoughtSpot recommends using the custom token API endpoint to generate tokens for the Attribute-Based Access Control (ABAC) implementation. For more information, see xref:abac_rls-variables.adoc[ABAC via RLS with variables]. + +Connections:: +The following new API endpoints are available for updating and deleting a connection object: + +* `POST /api/rest/2.0/connections/{connection_identifier}/update` +* `POST /api/rest/2.0/connections/{connection_identifier}/delete` + ++ +ThoughtSpot recommends using these APIs instead of `POST /api/rest/2.0/connection/update` and `POST /api/rest/2.0/connection/delete`. + +TML:: +The following API endpoints are available for asynchronous TML import: + +* `POST /api/rest/2.0/metadata/tml/async/import` + +Validates and imports TML objects asynchronously. Use this API endpoint when importing large metadata objects. +* `POST /api/rest/2.0/metadata/tml/async/status` + +Fetches task status for the async TML import operations. + +For more information, see xref:tml.adoc#_import_tml_objects_asynchronously[Import TML objects asynchronously]. + +=== API enhancements + +User session:: + +* The 200 API response for the `/api/rest/2.0/auth/session/user` and `/api/rest/2.0/users/search` is modified to show `access_control_properties`. + +* You can now manage account activation status for IAMv2 users using the following API endpoints: + +** `POST /api/rest/2.0/users/create` + +** `POST /api/rest/2.0/users/{user_identifier}/update` + +Report API:: + +The `POST /api/rest/2.0/report/answer` API endpoint supports downloading an Answer generated by the Spotter AI APIs: + +* `session_identifier` + +Session ID returned in API response by the `/api/rest/2.0/ai/answer/create` or `/api/rest/2.0/ai/conversation/create` endpoint. +* `generation_number` + +Number assigned to the Answer session with Spotter. ++ +If you are downloading an Answer generated by Spotter, you must specify the session ID. The `metadata_identifier` property is not required. + +=== Deprecated features + +Connection APIs:: + +The following connection API endpoints are deprecated: + +* `POST /api/rest/2.0/connection/delete` +* `POST /api/rest/2.0/connection/update` + ++ +Use `POST /api/rest/2.0/connections/{connection_identifier}/update` and `POST /api/rest/2.0/connections/{connection_identifier}/delete` APIs to update and delete a connection object respectively. + +Authentication:: + +The `user_parameters` property in `/api/rest/2.0/auth/token/full` and `/api/rest/2.0/auth/token/object` APIs is deprecated. ++ +ThoughtSpot recommends using `/api/rest/2.0/auth/token/custom` API endpoint with `filter_rules` and `parameter_values` to configure user properties for ABAC via tokens. + +== Version 10.3.0.cl, October 2024 + +=== New API endpoint + +You can now create a copy of a Liveboard or Answer object using `/api/rest/2.0/metadata/copyobject` API endpoint. + +== Version 10.1.0.cl, August 2024 + +=== New API endpoints + +* `POST /api/rest/2.0/metadata/tml/export/batch` + +Exports a batch of TML for user, user group, or Role objects. + +=== Security APIs +The `/api/rest/2.0/security/metadata/fetch-permissions` API endpoint supports the following parameters: + +* `record_offset` + +Specifies the starting record number from which the records for each metadata type will be included in the API response. +* `record_size` + +Specifies the number of records that should be included for each metadata type in the API response. +* `permission_type` + +Specifies the type of permission. Valid values are: +** `EFFECTIVE` - If user permission to the metadata objects is granted by the privileges assigned to the groups to which they belong. +** `DEFINED` - If a user or user group received access to metadata objects via object sharing by another user. + +== Version 10.0.0.cl, July 2024 + +=== Roles + +You can now assign the `CAN_MANAGE_VERSION_CONTROL` role using any of the following API endpoints: + +* `POST /api/rest/2.0/roles/create` +* `POST /api/rest/2.0/roles/{role_identifier}/update` + +The `CAN_MANAGE_VERSION_CONTROL` Role privilege is required for Git integration with ThoughtSpot. + +== Version 9.12.0.cl, May 2024 + +==== New features + +Authentication API:: + +* `/api/rest/2.0/auth/token/validate` + +Validates the authentication token of the logged-in user. + +TML API:: +The export TML API requests now support the following parameters: ++ +* `export_schema_version` + +Specifies the schema version for datasets during TML export. By default, the API request uses v1 schema for Worksheet TML export. For Models, set `export_schema_version` to `v2`. + +* `export_dependent` + +Allows exporting dependent Tables while exporting a Connection. +* `export_connection_as_dependent` + +Specifies if a Connection can be exported as a dependent object when exporting a Table, Worksheet, Answer, or Liveboard. This parameter works only when `export_associated` is set to `true` in the API request. + +==== Deprecated features + +Token authentication APIs:: + +The `jwt_user_options` object property in `/api/rest/2.0/auth/token/full` and `/api/rest/2.0/auth/token/object` is deprecated. Use the `user_parameters` property to define security entitlements to a user session. For more information, see xref:abac-user-parameters.adoc[ABAC via token][beta betaBackground]^Beta^. + +== Version 9.10.5.cl, April 2024 + +=== New features + +Authentication:: + +The `/api/rest/2.0/auth/token/full` and `/api/rest/2.0/auth/token/object` API endpoints support generating JWT token for Attribute-Based Access Control. The `user_parameters` object allows you to define security entitlements for a given user. + +For more information, see xref:abac-user-parameters.adoc[ABAC via tokens]. + +Roles:: + +The `/api/rest/2.0/roles/create` and `/api/rest/2.0/roles/{role_identifier}/update` API endpoints support assigning the following privileges to a Role for granular data access control and management: + +* `CAN_MANAGE_CUSTOM_CALENDAR` +* `CAN_CREATE_OR_EDIT_CONNECTIONS` +* `CAN_MANAGE_WORKSHEET_VIEWS_TABLES` + +DBT:: + +You can now use `file_content` to upload DBT Manifest and Catalog artifact files as a ZIP file in your API requests to the `/api/rest/2.0/dbt/dbt-connection`, `/api/rest/2.0/dbt/generate-tml`, `/api/rest/2.0/dbt/generate-sync-tml`, and `/api/rest/2.0/dbt/update-dbt-connection` endpoints. This field is required if the `import_type` parameter is set to `'ZIP_FILE'`. + +Connections:: + +* `/api/rest/2.0/connections/fetch-connection-diff-status/{connection_identifier}` + +Validates the differences in Connection metadata between Cloud Data Warehouse and ThoughtSpot. +* `/api/rest/2.0/connections/download-connection-metadata-changes/{connection_identifier}` + +Downloads the connection metadata differences identified between Cloud Data Warehouse and ThoughtSpot. + +Logs:: +The `/api/rest/2.0/logs/fetch` API endpoint allows fetching all logs in a single API request. To get all logs, set `get_all_logs` to `true`. + +Share metadata:: + +The `/api/rest/2.0/security/metadata/share` API supports the following new properties: + +* `notify_on_share` + +Sends a share notification to the email addresses specified in the API request. +* `has_lenient_discoverability` + +Sets the shared metadata object as a discoverable object. Applies to Saved Answers and Liveboards only. + +Users:: +The `trigger_activation_email` property allows you to specify if an activation email must be sent to the user's email address in the user creation request to the `/api/rest/2.0/users/create` endpoint. + +=== Deprecated features + +Version Control APIs:: + +The following parameters in `/api/rest/2.0/vcs/git/config/create` and `/api/rest/2.0/vcs/git/config/update` are deprecated from 9.10.5.cl onward: + +* `default_branch_name` + +Replaced by `commit_branch_name` +* `guid_mapping_branch_name` + +Replaced by `configuration_branch_name` + +For more information, see xref:version_control.adoc[Git integration and version control]. + +== Version 9.10.0.cl, March 2024 + +=== New API endpoints + +DBT:: + +* `POST /api/rest/2.0/dbt/dbt-connection` + +Creates a DBT connection. +* `POST /api/rest/2.0/dbt/generate-tml` + +Generates Worksheets and Tables for a given DBT connection. +* `POST /api/rest/2.0/dbt/generate-sync-tml` + +Synchronizes the existing TML of data models and Worksheets and imports them to ThoughtSpot. +* `POST /api/rest/2.0/dbt/search` + +Gets a list of DBT connection objects for a given user or Org. +* `POST /api/rest/2.0/dbt/{dbt_connection_identifier}` + +Updates a DBT connection. + +System:: + +`GET api/rest/2.0/system/banner` + +Gets cluster maintenance status and banner text. + ++ +For more information, see xref:tse-eco-mode.adoc#_cluster_status_during_upgrade[Cluster maintenance and upgrade]. + +== Version 9.8.0.cl, January 2024 + +The `deploy_policy` property in the `/api/rest/2.0/vcs/git/commits/deploy` endpoint now supports the `VALIDATE_ONLY` option, which allows you to compare and validate TML content on the destination environment against the content in the main branch before deploying commits. + +== Version 9.7.0.cl, November 2023 + +=== Version Control APIs + +This release introduces the following enhancements to the Version Control API endpoints: + +==== Git connection creation and update APIs + +The `POST /api/rest/2.0/vcs/git/config/create` and `POST /api/rest/2.0/vcs/git/config/update` API endpoints include the following enhancements: + +New parameters:: + +* `commit_branch_name` + +Allows configuring a commit branch for Git connections on your ThoughtSpot instance. ThoughtSpot recommends using `commit_branch_name` instead of `default_branch_name` in the API calls to prevent users from committing changes to the default deployment branch. +* `configuration_branch_name` + +Allows configuring a separate Git branch for storing and maintaining configuration files, such as GUID mapping and commit tracking files. If the `configuration_branch_name` property is defined, the `guid_mapping_branch_name` parameter is not required. + +Modified parameters:: +The `enable_guid_mapping` parameter is enabled by default. + +Separate branches for Orgs:: +If you are using Orgs and want to move content between these Orgs using version control APIs, ensure that you set a separate Git branch for each Org. If two Orgs are connected to the same Git `repository_url`, the `POST /api/rest/2.0/vcs/git/config/create` and `POST /api/rest/2.0/vcs/git/config/update` API endpoints do not support configuring the same branch name for these Orgs. + +Deprecation notice:: + +The `default_branch_name` and `guid_mapping_branch_name` parameters will be deprecated from version 10.0.0.cl and later releases. + +For more information, see xref:git-configuration.adoc#connectTS[Connect your ThoughtSpot environment to the Git repository]. + +==== Commit API + +The `POST /api/rest/2.0/vcs/git/branches/commit` API endpoint allows the following new attribute in the request body: + +* `delete_aware` ++ +When set to true, the system runs a check between the objects and files in the Git branch and destination environment or Org. If an object exists in the Git branch, but not the destination environment or Org, it will be deleted from the Git branch during the commit operation. + +For more information, see xref:version_control.adoc#_commit_files_and_changes[Commit files]. + +==== Deploy API + +Note the following changes: + +* The `branch_name` attribute is now mandatory in the `POST /api/rest/2.0/vcs/git/commits/deploy` API requests. Ensure that you specify the name of the Git branch from which the commits can be picked and deployed on the destination environment or Org. + +* After a successful deployment, a tracking file is generated with the `commit_id` and saved in the Git branch that is used for storing configuration files. The `commit_id` recorded in the tracking file is used for comparing changes when new commits are pushed in the subsequent API calls. + +For more information, see xref:version_control.adoc#_deploy_commits[Deploy commits]. + +=== User API + +The following new API endpoints are introduced for user account management: + +* `POST /api/rest/2.0/users/activate` + +Activates an inactive user account. + +* `POST /api/rest/2.0/users/deactivate` + +Deactivates a user account. + +=== Support for sorting of columns at runtime +The following data API endpoints now support runtime sorting of columns: + +* `POST /api/rest/2.0/searchdata` + +* `POST /api/rest/2.0/metadata/liveboard/data` + +* `POST /api/rest/2.0/metadata/answer/data` + + +For more information, see xref:runtime-sort.adoc[Runtime sorting of columns]. + +== Version 9.6.0.cl, October 2023 + +=== New API endpoints + +* `POST /api/rest/2.0/customization/custom-actions/search` + +Gets custom action objects +* `POST /api/rest/2.0/customization/custom-actions` + +Creates a custom action +* `POST /api/rest/2.0/customization/custom-actions/{custom_action_identifier}/update` + +Updates the properties of a custom action object. +* `POST /api/rest/2.0/customization/custom-actions/{custom_action_identifier}/delete` + +Deletes a custom action + +=== SDK for TypeScript + +ThoughtSpot provides TypeScript SDK to help client applications call REST APIs using TypeScript. You can download the SDK from the link:https://www.npmjs.com/package/@thoughtspot/rest-api-sdk?activeTab=readme[NPM site, window=_blank]. + +== Version 9.5.0.cl, September 2023 + +=== New API endpoints for Role-Based Access Control [beta betaBackground]^Beta^ + +* `POST /api/rest/2.0/roles/search` + +Gets details of role objects available in the ThoughtSpot system. +* `POST /api/rest/2.0/roles/create` + +Creates a role and assigns privileges +* `POST /api/rest/2.0/roles/{role_identifier}/update` + +Updates the properties of a given role +* `POST /api/rest/2.0/roles/{role_identifier}/delete` + +Removes a role object from the ThoughtSpot system + +For more information, see xref:roles.adoc[Role-based access control]. + +[NOTE] +==== +The roles APIs work only if the Role-Based Access Control (RBAC) [beta betaBackground]^Beta^ feature is enabled on your instance. The RBAC feature is turned off by default. To enable this feature, contact ThoughtSpot Support. +==== + +=== Enhancements and API modifications + +Support for runtime parameter overrides:: +The following data and report API endpoints support applying runtime parameter overrides: +* `POST /api/rest/2.0/searchdata` + +* `POST /api/rest/2.0/metadata/liveboard/data` + +* `POST /api/rest/2.0/metadata/answer/data` + +* `POST /api/rest/2.0/report/liveboard` + +* `POST /api/rest/2.0/report/answer` + +Git integration support for Orgs:: + +The Version Control API endpoints support using Orgs as disparate deployment environments. You can create separate Orgs for `dev`, `staging`, and `prod` and integrate these environments with a GitHub repo. + ++ +For more information, see xref:version_control.adoc[Git integration and version control]. + +=== Response code change [tag redBackground]#BREAKING CHANGE# + +The following endpoints now return the 204 response code instead of 200. The 204 code does not return a response body. This change may affect your current implementation, so we recommend that you update your code to avoid issues. + +* `POST /api/rest/2.0/connection/delete` +* `POST /api/rest/2.0/connection/update` +* `POST /api/rest/2.0/users/{user_identifier}/update` +* `POST /api/rest/2.0/users/{user_identifier}/delete` +* `POST /api/rest/2.0/users/change-password` +* `POST /api/rest/2.0/users/reset-password` +* `POST /api/rest/2.0/users/force-logout` +* `POST /api/rest/2.0/groups/{group_identifier}/update` +* `POST /api/rest/2.0/groups/{group_identifier}/delete` +* `POST /api/rest/2.0/metadata/delete` +* `POST /api/rest/2.0/orgs/{org_identifier}/update` +* `POST /api/rest/2.0/orgs/{org_identifier}/delete` +* `POST /api/rest/2.0/schedules/{schedule_identifier}/delete` +* `POST /api/rest/2.0/schedules/{schedule_identifier}/update` +* `POST /api/rest/2.0/security/metadata/assign` +* `POST /api/rest/2.0/security/metadata/share` +* `POST /api/rest/2.0/system/config-update` +* `POST /api/rest/2.0/tags/{tag_identifier}/update` +* `POST /api/rest/2.0/tags/{tag_identifier}/delete` +* `POST /api/rest/2.0/tags/assign` +* `POST /api/rest/2.0/tags/unassign` +* `POST /api/rest/2.0/vcs/git/config/delete` +* `POST /api/rest/2.0/auth/session/login` +* `POST /api/rest/2.0/auth/session/logout` +* `POST /api/rest/2.0/auth/token/revoke` + + +== Version 9.4.0.cl, August 2023 + +=== API endpoints to schedule and manage Liveboard jobs + +* `*POST* /api/rest/2.0/schedules/create` + +Creates a scheduled job for a Liveboard +* `*POST* /api/rest/2.0/schedules/{schedule_identifier}/update` + +Updates a scheduled job +* `*POST* /api/rest/2.0/schedules/search` + +Gets a list of Liveboard jobs configured on a ThoughtSpot instance +* `*POST* /api/rest/2.0/schedules/{schedule_identifier}/delete` + +Deletes a scheduled job. + +For more information, see link:{{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fschedules%2Fsearch-schedule[REST API v2.0 Reference]. + +=== API to fetch authentication token + +The `GET /api/rest/2.0/auth/session/token` API endpoint fetches the current authentication token used by the currently logged-in user. + +=== Version Control API enhancements + +* The following Version Control API endpoints support generating and maintaining a GUID mapping file on a Git branch connected to a ThoughtSpot instance: + +** `*POST* /api/rest/2.0/vcs/git/config/create` +** `*POST* /api/rest/2.0/vcs/git/config/update` + +=== User and group API enhancements + +* The `**POST** /api/rest/2.0/users/{user_identifier}/update` and `**POST** /api/rest/2.0/groups/{group_identifier}/update` support specifying the type of operation API request. For example, if you are removing a property of a user or group object, you can specify the `operation` type as `REMOVE` in the API request. +* The `**POST** /api/rest/2.0/users/{user_identifier}/update` allows you to define locale settings, preferences, and other properties for a user object. + +== Version 9.3.0.cl, June 2023 + +The following Version Control [beta betaBackground]^Beta^ API endpoints are now available for the lifecycle management of content on your deployment environments: + +* `*POST* /api/rest/2.0/vcs/git/config/search` +* `*POST* /api/rest/2.0/vcs/git/commits/search` +* `*POST* /api/rest/2.0/vcs/git/config/create` +* `*POST* /api/rest/2.0/vcs/git/config/update` +* `*POST* /api/rest/2.0/vcs/git/config/delete` +* `*POST* /api/rest/2.0/vcs/git/branches/commit` +* `*POST* /api/rest/2.0/vcs/git/commits/{commit_id}/revert` +* `*POST* /api/rest/2.0/vcs/git/branches/validate` +* `*POST* /api/rest/2.0/vcs/git/commits/deploy` + +For more information, see xref:version_control.adoc[Version control and Git integration]. + +== Version 9.2.0.cl, May 2023 + +New endpoints:: + +* System ++ +** `POST /api/rest/2.0/system/config-update` + +Updates system configuration ++ +** `GET /api/rest/2.0/system/config-overrides` + +Gets system configuration overrides + +* Connections ++ +** POST /api/rest/2.0/connection/create + +Creates a data connection + +** `POST /api/rest/2.0/connection/search` + +Gets a list of data connections + +** `POST /api/rest/2.0/connection/update` + +Updates a data connection + +** `POST /api/rest/2.0/connection/delete` + +Deletes a data connection + +Enhancements:: + +* Support for runtime filters and runtime sorting of columns + +The following REST API v2.0 endpoints support applying xref:runtime-filters.adoc#_rest_api_v2_0_endpoints[runtime filters] and xref:runtime-sort.adoc[sorting column data]: ++ +** `POST /api/rest/2.0/report/liveboard` + +** `POST /api/rest/2.0/report/answer` + +* Search users by their favorites ++ +The `/api/rest/2.0/users/search` API endpoint allows searching users by their favorite objects and home Liveboard setting. + +* Ability to log in to a specific Org ++ +The `/api/rest/2.0/auth/session/login` API endpoint now allows ThoughtSpot users to log in to a specific Org context. -=== REST API TypeScript SDK +== Version 9.0.0.cl, February 2023 -ThoughtSpot provides the REST API TypeScript SDK (`@thoughtspot/rest-api-sdk`) to help developers interact programmatically with ThoughtSpot REST API v2 endpoints. The SDK is available on link:https://www.npmjs.com/package/@thoughtspot/rest-api-sdk[npm, window=_blank]. +The ThoughtSpot Cloud 9.0.0.cl release introduces the REST API v2.0 endpoints and Playground. For information about REST API v2.0 endpoints and Playground, see the following articles: -For information about how to install and use the SDK, see xref:rest-api-sdk-typescript.adoc[TypeScript SDK for REST APIs]. +* xref:rest-api-v2.adoc[REST API v2.0] +* xref:rest-api-v2-getstarted.adoc[Get started with REST API v2.0] +* xref:rest-api-v2-reference.adoc[REST API v2.0 reference] +* xref:rest-api-v1v2-comparison.adoc[REST API v1 and v2.0 comparison] From 8b5ea255151b2a95f1866d8dde183c3d5027a32d Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 17 Aug 2026 10:34:24 +0530 Subject: [PATCH 040/154] docs: add Visual Embed SDK 1.52.x changelog (SCAL-317516, SCAL-314461) --- modules/ROOT/pages/api-changelog.adoc | 1886 +++++++++++++++++++++++-- 1 file changed, 1804 insertions(+), 82 deletions(-) diff --git a/modules/ROOT/pages/api-changelog.adoc b/modules/ROOT/pages/api-changelog.adoc index 44d9a9a16..afdb900bf 100644 --- a/modules/ROOT/pages/api-changelog.adoc +++ b/modules/ROOT/pages/api-changelog.adoc @@ -10,83 +10,84 @@ This page documents the changes introduced in each release of the Visual Embed S == Version 1.52.x, September 2026 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| + [width="100%" cols="1,4"] + |==== + |[tag greenBackground]#NEW FEATURE# a| -[discrete] -===== Browser history management in full application embedding + [discrete] + ===== Browser history management in full application embedding -// SOURCE: SCAL-317516 -// SOURCE: thoughtspot/visual-embed-sdk/src/types.ts (master) + // SOURCE: SCAL-317516 + // SOURCE: thoughtspot/visual-embed-sdk/src/types.ts (master) -ThoughtSpot 26.9.0.cl introduces the `overrideHistoryState` configuration parameter for `AppEmbed`. When embedding ThoughtSpot in a host application, every internal ThoughtSpot navigation event (for example, switching between Liveboards or Answers) pushes a new entry onto the browser's history stack. This causes the browser *Back* button to step through ThoughtSpot's internal navigation before returning to the host application's prior page. + ThoughtSpot 26.9.0.cl introduces the `overrideHistoryState` configuration parameter for `AppEmbed`. When embedding ThoughtSpot in a host application, every internal ThoughtSpot navigation event (for example, switching between Liveboards or Answers) pushes a new entry onto the browser's history stack. This causes the browser *Back* button to step through ThoughtSpot's internal navigation before returning to the host application's prior page. -Setting `overrideHistoryState: true` converts all ThoughtSpot internal `pushState` calls to `replaceState`, preventing ThoughtSpot navigation from polluting the host application's browser history stack. + Setting `overrideHistoryState: true` converts all ThoughtSpot internal `pushState` calls to `replaceState`, preventing ThoughtSpot navigation from polluting the host application's browser history stack. -[source,JavaScript] ----- -import { AppEmbed, init, AuthType } from '@thoughtspot/visual-embed-sdk'; + [source,JavaScript] + ---- + import { AppEmbed, init, AuthType } from '@thoughtspot/visual-embed-sdk'; -init({ - thoughtSpotHost: 'https://.thoughtspot.cloud', - authType: AuthType.TrustedAuthToken, - getAuthToken: () => fetch('/ts-token').then(r => r.json()).then(d => d.token), -}); + init({ + thoughtSpotHost: 'https://.thoughtspot.cloud', + authType: AuthType.TrustedAuthToken, + getAuthToken: () => fetch('/ts-token').then(r => r.json()).then(d => d.token), + }); -const embed = new AppEmbed('#embed-container', { - frameParams: { width: '100%', height: '100%' }, - overrideHistoryState: true, // <1> -}); + const embed = new AppEmbed('#embed-container', { + frameParams: { width: '100%', height: '100%' }, + overrideHistoryState: true, // <1> + }); -embed.render(); ----- -<1> When set to `true`, ThoughtSpot replaces rather than pushes browser history entries during internal navigation. + embed.render(); + ---- + <1> When set to `true`, ThoughtSpot replaces rather than pushes browser history entries during internal navigation. -[NOTE] -==== -`overrideHistoryState` is available on `AppEmbed` only. It is not supported on `LiveboardEmbed`, `SearchEmbed`, or `SpotterEmbed`. Validate behavior across Chrome, Firefox, and Safari before enabling in production. -==== + [NOTE] + ==== + `overrideHistoryState` is available on `AppEmbed` only. It is not supported on `LiveboardEmbed`, `SearchEmbed`, or `SpotterEmbed`. Validate behavior across Chrome, Firefox, and Safari before enabling in production. + ==== -For more information, see xref:full-app-embed.adoc[Full application embedding]. + For more information, see xref:full-app-embed.adoc[Full application embedding]. -|[tag greenBackground]#NEW FEATURE# a| + |[tag greenBackground]#NEW FEATURE# a| -[discrete] -===== Collections in left navigation panel + [discrete] + ===== Collections in left navigation panel -// SOURCE: SCAL-314461 + // SOURCE: SCAL-314461 -The `HomeLeftNavItem.Collections` enum value is now available in the Visual Embed SDK. Embed developers can include *Collections* as a selectable navigation option in the embedded left navigation panel for full application embeds. When enabled, end users of the embedded application can navigate to *Collections* from the left navigation panel. + The `HomeLeftNavItem.Collections` enum value is now available in the Visual Embed SDK. Embed developers can include *Collections* as a selectable navigation option in the embedded left navigation panel for full application embeds. When enabled, end users of the embedded application can navigate to *Collections* from the left navigation panel. -[source,JavaScript] ----- -import { AppEmbed, HomeLeftNavItem, init, AuthType } from '@thoughtspot/visual-embed-sdk'; - -init({ - thoughtSpotHost: 'https://.thoughtspot.cloud', - authType: AuthType.TrustedAuthToken, - getAuthToken: () => fetch('/ts-token').then(r => r.json()).then(d => d.token), -}); - -const embed = new AppEmbed('#embed-container', { - frameParams: { width: '100%', height: '100%' }, - leftNavOrder: [ - HomeLeftNavItem.Home, - HomeLeftNavItem.Liveboards, - HomeLeftNavItem.Answers, - HomeLeftNavItem.Collections, // <1> - ], -}); - -embed.render(); ----- -<1> Include `HomeLeftNavItem.Collections` in the `leftNavOrder` array to show Collections in the embedded left navigation panel. + [source,JavaScript] + ---- + import { AppEmbed, HomeLeftNavItem, init, AuthType } from '@thoughtspot/visual-embed-sdk'; -For more information, see xref:full-app-customize.adoc[Customize full application embedding]. + init({ + thoughtSpotHost: 'https://.thoughtspot.cloud', + authType: AuthType.TrustedAuthToken, + getAuthToken: () => fetch('/ts-token').then(r => r.json()).then(d => d.token), + }); -|==== + const embed = new AppEmbed('#embed-container', { + frameParams: { width: '100%', height: '100%' }, + leftNavOrder: [ + HomeLeftNavItem.Home, + HomeLeftNavItem.Liveboards, + HomeLeftNavItem.Answers, + HomeLeftNavItem.Collections, // <1> + ], + }); + + embed.render(); + ---- + <1> Include `HomeLeftNavItem.Collections` in the `leftNavOrder` array to show Collections in the embedded left navigation panel. + + For more information, see xref:full-app-customize.adoc[Customize full application embedding]. + + |==== + == Version 1.51.x, August 2026 [width="100%" cols="1,4"] @@ -235,46 +236,1767 @@ New events and action IDs;; * `EmbedEvent.DownloadLiveboardAsContinuousPDF` + Emits when the download action is triggered. * `HostEvent.DownloadLiveboardAsContinuousPDF` + -Triggers a download of the Liveboard as a continuous PDF. +Programmatically triggers the download action to export the PDF with a continuous Liveboard layout. * `Action.DownloadLiveboardAsContinuousPDF` + -Action ID to show or hide the continuous PDF download option. +Action ID to control the visibility of download action that exports continuous PDFs. + +Liveboard download actions:: + +The following action IDs are introduced in the SDK for the download buttons at the Liveboard level: + +* `Action.DownloadLiveboard` + +* `Action.DownloadLiveboardAsXlsx` + +* `Action.DownloadLiveboardAsCsv` + +Test email for Liveboard scheduled jobs:: + +The SDK introduces the `isSendNowLiveboardSchedulingEnabled` to enable the **Send now** option for the Liveboard scheduled jobs. This option allows Liveboard users to send a test email notification to either themselves or the intended recipients of the Liveboard scheduled alerts. + +New events and action IDs;; + +* `EmbedEvent.SendTestScheduleEmail` + +Emits when *Send now* button is clicked. +* `HostEvent.SendTestScheduleEmail` + +Programmatically triggers the Send now action to send a test email notification for a Liveboard scheduled job. +* `Action.SendTestScheduleEmail` + +Action ID to disable, show, or hide the **Send now** button on the Liveboard schedule page. + +|[tag greenBackground]#NEW FEATURE# a| + +[discrete] +===== Spotter embedding + +The SDK introduces the following action IDs to control the visibility of specific UI components in chat panel of the embedded Spotter interface: -Org-level Liveboard filter settings;; -Administrators can configure Liveboard filter settings for all users in an Org using the new org-level filter configuration option. For more information, see xref:embed-pinboard.adoc#org-filter-config[Configure Liveboard filter settings for an Org]. +* `Action.SpotterChatConnectorResources` + +For the connector resources section in the Spotter chat interface. +* `Action.SpotterChatConnectors` + +For the connectors panel section in the Spotter chat interface. +* `Action.SpotterChatModeSwitcher` + +For the mode switcher in the Spotter chat interface. |[tag greenBackground]#NEW FEATURE# a| + [discrete] -===== Search embedding -* The `SearchEmbed` now supports the `dataPanelCustomGroupsAccordionInitialState` attribute to control the initial expanded or collapsed state of custom groups in the data panel. -* New action IDs to show or hide Edit and Delete buttons for saved Answers in the Search interface: -** `Action.EditAnswer` -** `Action.DeleteAnswer` +===== Event handling +Note the following changes: + +EmbedEvent:: + +* `EmbedEvent.Subscribed` + +The SDK introduces the `EmbedEvent.Subscribed` to emit an event when a HostEvent listener is registered. You can use this event to dispatch host events during the initial load without race conditions. This is particularly useful for Spotter, where host events such as `HostEvent.ResetSpotterConversation` may be triggered immediately after load. +* `EmbedEvent.Error` + +The `EmbedEvent.Error` now fires on HostEvent payload validation failures. + +HostEvent:: +* `HostEvent.GetExportRequestForCurrentPinboard` [.version-badge.breaking]#Breaking# + +The response payload of the `GetExportRequestForCurrentPinboard` passthrough +host event has been updated to include a `type` discriminator field, making it +consistent with the shape of other host event responses. It now returns `{ data: { v2Content }, type }` instead of `{ v2Content }` directly. This enhancement introduces a breaking change for any code that reads `result.v2Content` directly. Update your integration workflows to use `result.data.v2Content`. + |[tag greenBackground]#NEW FEATURE# a| + [discrete] -===== Full application embedding -The `AppEmbed` configuration now supports `disableMultipleOrgsGlobalSearch` to disable the global search scope across multiple Orgs in embedded full application mode. +===== Personalized View selection via host event + +* `EmbedEvent.ChangePersonalizedView` + +Emits when a user selects a different Personalized View on an embedded Liveboard, or resets to the default view. For more information, see xref:EmbedEvent.adoc#_changepersonalizedview[EmbedEvent reference documentation]. + +* `HostEvent.SelectPersonalizedView` + +The SDK introduces `HostEvent.SelectPersonalizedView` to programmatically switch the active Personalized View on an embedded Liveboard from the host application. For more information, see xref:HostEvent.SelectPersonalizedView[HostEvent reference documentation]. + +⚠️Deprecated events and action IDs️:: +The following events are deprecated and replaced with new event IDs. + +* `EmbedEvent.UpdatePersonalisedView`. Use `EmbedEvent.UpdatePersonalizedView`. +* `EmbedEvent.SavePersonalisedView`. Use `EmbedEvent.SavePersonalizedView`. +* `EmbedEvent.DeletePersonalisedView`. Use `EmbedEvent.DeletePersonalizedView`. +* `HostEvent.ResetLiveboardPersonalisedView`. Use `HostEvent.ResetLiveboardPersonalizedView`. +* `Action.PersonalisedViewsDropdown`. Use `Action.PersonalizedViewsDropdown`. +* `Action.OrganiseFavourites`. Use `Action.OrganizeFavorites`. |==== + == Version 1.47.x, April 2026 +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| **Spotter chat history sidebar customization** + +The SDK introduces the `SpotterSidebarViewConfig` interface and the `spotterSidebarConfig` object with configuration controls to customize the appearance and contents of the chat history panel. Developers can use the following properties in the `spotterSidebarConfig` object to enable or disable chat history panel and customize the contents of the sidebar when enabled: + +* `enablePastConversationsSidebar` + +Controls the visibility of the past conversations sidebar panel. The chat history panel is disabled by default in embed view. When this property in `spotterSidebarConfig` is specified, it takes precedence over the standalone `enablePastConversationsSidebar` setting, which is deprecated from v1.47.0. + +* `spotterSidebarTitle` + +Allows adding custom title text for the sidebar header. + +* `spotterSidebarDefaultExpanded` + +Sets the default state of the sidebar to expanded or collapsed view. + +* `spotterChatRenameLabel` + +Allows setting a custom label for the **Rename** action in the conversation edit menu. + +* `spotterChatDeleteLabel` + +Allows setting a custom label for the **Delete** action in the conversation edit menu. + +* `spotterDeleteConversationModalTitle` + +Allows editing the title text of the chat delete confirmation modal. + +* `spotterPastConversationAlertMessage` + +Sets a custom message text for the past conversation banner alert. Defaults to the translated alert message. + +* `spotterBestPracticesLabel` + +Allows customizing the label for the best practices button in the sidebar footer. + +* `spotterDocumentationUrl` + +The best practices documentation link shown in the sidebar footer. You can customize the link by specifying the full URL. + +* `spotterConversationsBatchSize` + +Sets the number of conversations to fetch per batch when loading conversation history. Default is `30`. + +* `spotterNewChatButtonTitle` + +Allows customizing the title text for the **New chat** button in the sidebar. + +|[tag redBackground]#DEPRECATED# a| **Standalone `enablePastConversationsSidebar` attribute in Spotter embed** + +The standalone `enablePastConversationsSidebar` property on `SpotterEmbedViewConfig` and `AppViewConfig` is deprecated from SDK 1.47.0 and ThoughtSpot 26.4.0.cl. + +Use `enablePastConversationsSidebar` in the `spotterSidebarConfig` instead. When both are defined, the property in the `spotterSidebarConfig` object takes precedence. + +[source,javascript] +---- +// Deprecated +enablePastConversationsSidebar: false, + +// Recommended +spotterSidebarConfig: { + enablePastConversationsSidebar: true, + //... other config properties +} +---- + +|[tag greenBackground]#NEW FEATURE# a| **Spotter chat UI branding** + +The SDK introduces the `SpotterChatViewConfig` interface for customizing branding in Spotter tool response cards. You can pass these parameters as the `spotterChatConfig` object properties in `SpotterEmbed`, `AppEmbed`, or `LiveboardEmbed` where Spotter interface is used. + +* `hideToolResponseCardBranding` + +When set to `true`, hides the ThoughtSpot logo and icon in tool response cards. The branding label prefix is controlled separately via `toolResponseCardBrandingLabel`. Default value is `false`. + +* `toolResponseCardBrandingLabel` + +Custom label to replace the `ThoughtSpot` prefix in tool response cards. Set to an empty string (`''`) to hide the prefix entirely. + +[NOTE] +==== +These settings do not affect the external MCP tool branding. +==== + +|[tag greenBackground]#NEW FEATURE# a|**Liveboard embed enhancements** + +Personalized Liveboard view:: + +The `personalizedViewId` property allows embedding a saved personalized view of a Liveboard. A personalized view is a saved configuration that includes specific filter selections and changes applied by a user. To embed a personalized view of Liveboard, specify the GUID of the saved personalized view to load along with `liveboardId`. + +Centralized Liveboard filter setting:: + +When set to `true`, the `isCentralizedLiveboardFilterUXEnabled` enables displaying a unified modal to manage and update multiple filters at once, replacing the older individual filter interactions. This feature is disabled by default on ThoughtSpot Embedded instances. + +|[tag greenBackground]#NEW FEATURE# a|**Option to include current period in rolling date filters** + +If the current period inclusion in rolling date filters feature is enabled on your instance, the rolling date filters options such as **Last ** and **Next ** for the Liveboards and Answers in the embed view will allow you to include current period. For example, when you define a date range such as "Last 2 months", the date filter interface displays the **Include this month** checkbox. +To disable this feature, use the `isThisPeriodInDateFiltersEnabled` setting. To hide, show, or disable this option in the embed view, use the action ID, `Action.IncludeCurrentPeriod`. +|==== + + +== Version 1.46.x, March 2026 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| **Host events with page context framework** + +The Visual Embed SDK introduces the HostEvent V2 framework for improved handling and execution of host events in embedded ThoughtSpot experiences with multi-layer UI interactions. The v2 framework supports the page context feature, which tracks the top-most active layer in the user's current context. Developers can use this feature to route events based on the user's current context or set a specific target context for precise and predictable handling of host events. + +* To enable this feature, set `useHostEventsV2` to `true`. +* To retrieve the current context, use `getCurrentContext()`. +* To set a target context for a host event, use xref:ContextType.adoc[ContextType]. + +For more information, refer to the xref:events-context-aware-routing.adoc[Host events documentation]. + +|[tag redBackground]#DEPRECATED# a| **dataPanelV2** + +The `dataPanelV2` parameter is deprecated and can no longer be used to switch between the classic and new data panel experience. By default, the new data panel v2 experience is enabled on all ThoughtSpot embedded instances. + +|[tag greenBackground]#NEW FEATURE# a| **Spotter experience** +The SDK includes the following parameters, action IDs, and events to customize the Spotter embed experience. + +Chat history sidebar customization:: + +//* `SpotterSidebarViewConfig` interface with configuration parameters for customizing the visibility and appearance of the chat history sidebar. +//* `spotterSidebarConfig` properties for customizing the appearance and available options in the chat history sidebar. +* Action IDs for customizing the visibility and status of actions in the embedded Spotter interface: +** `Action.DataModelInstructions` for the data model instructions icon. +** `Action.SpotterSidebarHeader` for the chat history sidebar header +** `Action.SpotterSidebarFooter` for the chat history sidebar footer +** `Action.SpotterSidebarToggle` for the chat history toggle that expands or collapses the sidebar. +** `Action.SpotterNewChat` for the new chat icon in the chat history sidebar. +** `Action.SpotterPastChatBanner` for the banner in the chat history sidebar. +** `Action.SpotterChatMenu` for the chat menu component in the chat history sidebar. +** `Action.SpotterChatRename` for **Rename** action in the chat menu of a saved chat. +** `Action.SpotterChatDelete` for **Delete** action in the chat menu of a saved chat. +//** `Action.SpotterDocs` for best practices documentation icon in the chat history sidebar. + +Events:: +* `HostEvent.DataModelInstructions` + +Opens the Data Model instructions modal. +* `EmbedEvent.DataModelInstructions` + +Is emitted when a user clicks the Data Model instructions icon in the Spotter interface. +* `EmbedEvent.SpotterConversationRenamed` + +Is emitted when a user renames a saved chat. +* `EmbedEvent.SpotterConversationDeleted` + +Is emitted when a saved chat is deleted. +* `EmbedEvent.SpotterConversationSelected` + +Is emitted when a saved chat is selected in the chat history sidebar. + +|[tag greenBackground]#NEW FEATURE# | `enableLinkOverridesV2` + + +Use this configuration setting to override ThoughtSpot URLs on hover or when opening in a new tab. This is recommended over the earlier `linkOverride` flag for a better user experience. + +|[tag greenBackground]#NEW FEATURE# a| **Liveboard experience enhancements** + +* The `isLiveboardXLSXCSVDownloadEnabled` attribute adds XLSX and CSV to the available Liveboard download formats. +* The `isGranularXLSXCSVSchedulesEnabled` attribute allows you to include the entire Liveboard, specific visualizations, or only tables and pivot tables in the XLSX and CSV schedules. +|==== + +== Version 1.45.0, February 2026 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| **Spotter enhancements** + +You can now embed the Spotter 3 experience in your application and use features such as Auto mode for automatic data model selection, chat history, and a new chat prompt interface. + +* To enable the new chat prompt interface, set `updatedSpotterChatPrompt` to `true`. +* To use Auto mode, set the `worksheetId` to `auto_mode`. +* To enable Chat history, set `enablePastConversationsSidebar` to `true`. + +For more information, see xref:embed-spotter.adoc[Embedding Spotter] and xref:embed-ai-analytics.adoc#_feature_status_and_availability_in_embed_mode[Features available with Spotter 3 experience]. + +Events:: + +* `EmbedEvent.AddToCoaching` for the *Add to Coaching* workflow in a Spotter conversation session +* `HostEvent.AddToCoaching` to trigger the *Add to Coaching* action in a Spotter conversation session. +* `HostEvent.StartNewSpotterConversation` to trigger the action to start a new chat session with Spotter. + +[NOTE] +==== +On Spotter embed deployments running version 26.2.0.cl or later, the *Add to Coaching* feature is enabled by default. To disable or hide the *Add to Coaching* button, use the xref:Action.adoc#_inconversationtraining[InConversationTraining] action ID. +==== + +|[tag greenBackground]#NEW FEATURE# a| **Liveboard experience enhancements** + + +Styling and grouping:: + +* The `isLiveboardStylingAndGrouping` attribute, used to enable the Liveboard styling and grouping feature, is now replaced with `isLiveboardMasterpiecesEnabled`. While your existing configuration with the deprecated `isLiveboardStylingAndGrouping` attribute continues to work, we recommend switching to the new configuration setting. +* The following action IDs are now available to show, disable, or hide the grouping menu actions on a Liveboard: +** `Action.MoveToGroup` for the **Move to Group** menu action. +** `Action.MoveOutOfGroup` for the **Move out of Group** menu action. +** `Action.CreateGroup` for the *Create Group* menu action. +** `Action.UngroupLiveboardGroup` for the **Ungroup Liveboard Group** menu action. + +Filter chip masking:: +The `showMaskedFilterChip` boolean parameter is now available to control the visibility of masked filter chips on a Liveboard. When set to `true`, if a Liveboard is shared with a user who has restricted access due to column-level security, the filter chip corresponding to those inaccessible columns will be displayed as masked to that user. When set to `false`, the filter chip for inaccessible columns will not be visible to the user. ++ +For more information, see link:https://docs.thoughtspot.com/cloud/latest/security-data-object#csr-liveboard[Column security rules on Liveboards]. ++ +The `showMaskedFilterChip` setting is also available in full application embedding. + +|[tag greenBackground]#NEW FEATURE# a| **Publishing objects** + +The following action IDs are available for the data publishing menu actions in the *Data workspace* page: + +* `Action.Publish` for *Publish* +* `Action.ManagePublishing` for *Manage publishing* +* `Action.Unpublish` for *Unpublish* +* `Action.Parameterize` for *Parameterize* +|[tag greenBackground]#NEW FEATURE# a| **Error handling improvements** + +To handle errors in the embedding workflows, the SDK includes the following features: + +* `ErrorDetailsTypes` enum for categorizing error types, such as `API`, `VALIDATION_ERROR`, and `NETWORK`. +* `EmbedErrorCodes` enum with specific error codes for programmatic error handling. +* `EmbedErrorDetailsEvent` interface for structured error event handling. + +For more information, see link:https://developers.thoughtspot.com/docs/Enumeration_EmbedErrorCodes[EmbedErrorCodes] and link:https://developers.thoughtspot.com/docs/Enumeration_ErrorDetailsTypes[ErrorDetailsTypes]. +|==== + +== Version 1.44.x, January 2026 + +[width="100%" cols="1,4"] +|==== + +|[tag redBackground]#DEPRECATED# | **Use `minimumHeight` instead of `defaultHeight`** + + +The `defaultHeight` parameter is deprecated in Visual Embed SDK v1.44.2 and later. +To set the minimum height of the embed container for ThoughtSpot components such as a Liveboard, use the `minimumHeight` attribute instead. + +|[tag greenBackground]#NEW FEATURE# a| *Intercepting API calls* + +The SDK provides the following attributes to intercept API calls and handle interception via events and custom workflows: + +//* `enableApiIntercept` + +//When set to true, enables the feature on your ThoughtSpot embed. +* `interceptUrls` + +Allows configuring which API calls to intercept. +* `interceptTimeout` + +Sets the timeout duration for handling interception. +* `isOnBeforeGetVizDataInterceptEnabled` + +When set to true, it enables use of `EmbedEvent.OnBeforeGetVizDataIntercept` to emit and intercept search execution calls initiated by users and implement custom logic or workflows to allow or restrict search execution. +* `EmbedEvent.ApiIntercept` + +Emits when an API call matching the conditions defined in `interceptUrls` is detected. + +For more information, see xref:api-intercept.adoc[Intercept API calls and search requests]. +|==== + + +== Version 1.43.0, November 2025 +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| *Code-based custom actions* + +The following enumerations are available for code-based custom actions: + +* `CustomActionTarget` + +To define the target object for the custom action, such as on a Liveboard, visualization, Answer, or in Spotter. +* `CustomActionsPosition` + +To define the position of the custom action in the target object, such as primary menu, **More** options menu image:./images/icon-more-10px.png[the more options menu], or the contextual menu. +|[tag greenBackground]#NEW FEATURE# | *Attribute to set Parameter chip visibility during overrides* + +The `HostEvent.UpdateParameters` event now supports configuring the `isVisibleToUser` attribute to show or hide the Parameter chips after an override. For more information, see xref:runtime-parameters.adoc#_show_or_hide_parameter_chips_in_embedded_sessions[Show or hide Parameter chips in embedded sessions]. +|==== + +== Version 1.42.0, October 2025 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a|*Runtime overrides in Spotter embed* + +The Visual Embed SDK now supports runtime overrides in Spotter embed. + +* To apply runtime filters, use the `runtimeFilters` object +* To apply runtime Parameters, use the `runtimeParameters` object. + +|[tag greenBackground]#NEW FEATURE# a|*PNG images in Liveboard schedule notifications* + +To enable embedding PNG images of Liveboards in scheduled job notifications sent to subscribers, the SDK provides the `isPNGInScheduledEmailsEnabled` boolean parameter. When set to true, scheduled emails will include a PNG image of the Liveboard. + +The SDK also provides the following action IDs: + +* `Action.PngScreenshotInEmail` + +Adds the option to include a PNG screenshot in the notification email body when scheduling emails in ThoughtSpot. +* `Action.RemoveAttachment` + +Allows the user to remove an attachment from the email configuration in the schedule email dialog. +|[tag greenBackground]#NEW FEATURE# a|*Spotter embed* + +Action IDs:: +The following action IDs are available for Spotter embedding and are currently supported only in the `hiddenActions` array: + +* `Action.SpotterWarningsBanner` + +Action ID to control the visibility of the Spotter warnings banner in the UI. This banner displays general warnings or informational messages related to Spotter results or queries. +* `Action.SpotterWarningsOnTokens` + +Action ID to control the visibility of warning indicators on individual Spotter tokens parsed from a Spotter query. +* `Action.SpotterTokenQuickEdit` + +Action ID to enable or disable the link:https://docs.thoughtspot.com/cloud/latest/spotter-getting-started#quick-edits[quick edit functionality^] for Spotter tokens. +|==== + +== Version 1.41.0, September 2025 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a|*React component for Spotter Agent embed* + +The Visual Embed SDK now supports embedding Spotter Agent feature without a body or Spotter interface in a React app. For ease of implementation, the SDK also provides a custom React hook, `useSpotterAgent`. + +For more information, see xref:embed-ts-react-app.adoc#_embed_spotter_agent_in_your_own_app[Spotter Agent embedding in a React app]. + +|[tag greenBackground]#NEW FEATURE# a|*Event handlers for Spotter embed* + +The following event handlers are now available for Spotter embed: + +* `EmbedEvent.SpotterInit` + +Fires when Spotter embed component rendering is initialized. +* `EmbedEvent.QueryChanged` + +Fires when the Spotter query is updated by the user. +* `HostEvent.AskSpotter` + +Triggers *Ask Spotter* action for visualizations. +* `HostEvent.GetParameters` + +Triggers the action to fetch runtime Parameters applied on a visualization. +* `HostEvent.UpdateParameters` + +Triggers the action to update runtime Parameters for a Spotter-generated Answer. +* `HostEvent.GetTML` + +Triggers the action to get TML representation of a Spotter-generated Answer. + +For more information, see xref:EmbedEvent.adoc[EmbedEvent] and xref:HostEvent.adoc[HostEvent]. + +|[tag greenBackground]#NEW FEATURE# a|*Event handlers for Spotter Agent embed* + +You can now use the following host events in Spotter Agent embedding: + +- `HostEvent.DownloadAsCsv` + +Triggers the action to download a Spotter-generated Answer in CSV format. +- `HostEvent.DownloadAsPng` + +Triggers the action to download a Spotter-generated Answer in PNG format. +- `HostEvent.DownloadAsXlsx` + +Triggers the action to download a Spotter-generated Answer in XLSX format. +- `HostEvent.DownloadAsPdf` + +Triggers the action to download the PDF version of a Spotter-generated Answer. +- `HostEvent.Pin` + +Triggers the action to add a Spotter-generated Answer to a Liveboard. +- `HostEvent.Save` + +Triggers the *Save* action for a Spotter-generated Answer. + +For more information, see xref:HostEvent.adoc[HostEvent]. + +|[tag greenBackground]#NEW FEATURE# a| *Lazy loading of visualizations on an embedded Liveboard* + +You can now use the `lazyLoadingForFullHeight` parameter with the `fullHeight` to progressively load visualizations on an embedded Liveboard. When both these attributes are enabled, only the visualizations in the current viewport are loaded initially, while the other visualizations load as the user scrolls the Liveboard page. + +You can also set the margin property for lazy loading to define when the visualization should load. + +For more information, see xref:lazy-loading-fullheight.adoc[Lazy loading of visualizations in an embedded Liveboard]. + +|[tag greenBackground]#NEW FEATURE# a| *Full application embed* + + +You can now enable the persona-based left navigation panel and home page experience on your ThoughtSpot instance. This feature is disabled by default on ThoughtSpot instances and is available for Early Access. When it's enabled on your ThoughtSpot instance, you can roll out the new experience on embedding applications by configuring the xref:AppViewConfig.adoc#_discoveryexperience[`discoveryExperience`] attribute. + +When enabled, the left navigation panel organizes the application menu into persona-based contextual sections. For example, the *Insights* icon for business users, the *Data Workspace* icon for Analysts and Data engineers, and the *Develop* icon for developers. Your application users can navigate to each option using the tabs in the left navigation panel. The new interface also provides a slider to allow users to view or hide the left navigation panel. +|==== + +== Version 1.40.0, July 2025 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| *Fullscreen presentation mode controls for embedded Liveboards and visualizations* + +Developers can now control whether a visualization or Liveboard can be presented in full screen mode using the `disableFullscreenPresentation` attribute. By default, the full screen mode is disabled on embedded Liveboards and visualizations. +|[tag greenBackground]#NEW FEATURE# a| *PDF download settings* + +Developers can now control the display of *Include cover page* and *Include filter page(s)* options on the Download PDF dialog for Liveboards. The *Include cover page* and *Include filter page(s)* options are disabled by default on ThoughtSpot instances. When this feature is enabled, developers can use the `coverAndFilterOptionInPDF` attribute to show or hide these options for the Liveboard users in their embedding app. + +|[tag greenBackground]#NEW FEATURE# a| *Parameter for overriding a default primary action* + + +If Spotter is enabled on your instance, the *Spotter* button appears by default as the primary action on embedded Liveboard charts; if Spotter is not enabled, the *Explore* button is set as the primary action. If you want to replace the primary action with a different action, you can now use the `primaryAction` attribute. + +For more information, see xref:embed-actions.adoc#_override_default_primary_actions[Override default primary action]. + +|[tag greenBackground]#NEW FEATURE# a| *Full application embed experience enhancements* + + +The SDK now includes the `hideObjectSearch` property, which allows developers to hide the object search button in the navigation bar when embedding the full application. + +|[tag greenBackground]#NEW FEATURE# a| *Host events* + + +In this version, the SDK introduces the following host event handlers: + +- `HostEvent.ExitPresentMode` + +Triggers the exit action that allows users to exit the Liveboard or visualization present mode. +- `HostEvent.SpotterSearch` + +Triggers a search operation for the specified query string in Spotter embed. +- `HostEvent.PreviewSpotterData` + +Triggers the *Preview data* action that shows the data used for Spotter conversations. +- `HostEvent.ResetSpotterConversation` + +Triggers the *Reset* action to reset a Spotter conversation. +- `HostEvent.EditLastPrompt` + +Triggers the edit prompt action. +- `HostEvent.DeleteLastPrompt` + +Triggers the delete prompt action. + +For more information, see xref:HostEvent.adoc[HostEvent]. + +|[tag greenBackground]#NEW FEATURE# a|*Events support for Spotter embed* + +You can now use the following host events in Spotter embed: + +- `HostEvent.DownloadAsCsv` +- `HostEvent.DownloadAsPng` +- `HostEvent.DownloadAsXlsx` +- `HostEvent.Edit` +//- `HostEvent.GetParameters` +//- `HostEvent.GetTML` +- `HostEvent.MakeACopy` +- `HostEvent.Pin` +- `HostEvent.Save` + +For more information, see xref:HostEvent.adoc[HostEvent]. + +|[tag greenBackground]#NEW FEATURE# a| *Lazy loading with full height* + +The SDK introduces `lazyLoadingForFullHeight` parameter, which enables progressive loading of visualizations on an embedded Liveboard. +This parameter works in conjunction with the `fullHeight` attribute. When both these attributes are enabled, only the visualizations in the current viewport are loaded initially, while the other visualizations load as the user scrolls the Liveboard page. + +[NOTE] +==== +To use these attributes effectively in embedded applications, your ThoughtSpot instance must be upgraded to version 10.12.0.cl or later. +==== +|==== + + +== Version 1.39.0, July 2025 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| *Spotter embed components with new names* + +The following Spotter embed components are now deprecated and replaced with new components in the SDK and Visual Embed Playground: + +* `ConversationEmbed` + +Replaced with `SpotterEmbed` +* `ConversationViewConfig` + +Replaced with `SpotterEmbedViewConfig` +* `BodylessConversation` + +Replaced with `SpotterAgentEmbed` +* `BodylessConversationViewConfig` + +Replaced with `SpotterAgentEmbedViewConfig` + +The deprecated components with old names in the existing Spotter embed implementations will continue to function until further notice. For code samples with new component names, see xref:embed-spotter.adoc[Spotter embed documentation]. + +|[tag greenBackground]#NEW FEATURE# a| *Action ID for Spotter in-conversation training* + +For ThoughtSpot instances that have the new Spotter in-conversation training workflow enabled, the SDK provides the action ID `Action.InConversationTraining` to manage the visibility of the *Add to Coaching* button on Answers generated from Spotter prompts. + +[NOTE] +The *Add to Coaching* feature is currently in beta and is turned off by default on embed deployments. To enable this feature on your instance, contact ThoughtSpot Support. + +|[tag greenBackground]#NEW FEATURE# a|*Events support for Spotter embed* + +New embed events:: + +- `EmbedEvent.ExitPresentMode` + +Emits when a user exits the Liveboard or visualization presentation mode. +- `EmbedEvent.LastPromptDeleted` + +Emits when a query prompt in Spotter embed is deleted. +- `EmbedEvent.LastPromptEdited` + +Emits when a query prompt in Spotter embed is edited. +- `EmbedEvent.ResetSpotterConversation` + +Emits when a Spotter query is reset. +- `EmbedEvent.PreviewSpotterData` + +Emits when a user clicks the Preview data button in the Spotter conversation panel. +- `EmbedEvent.SpotterQueryTriggered` +Emits when a Spotter query is triggered. + +The following embed events are also supported in Spotter embed: + +- `EmbedEvent.AddRemoveColumns` +- `EmbedEvent.AnswerChartSwitcher` +- `EmbedEvent.AuthExpire` +- `EmbedEvent.AuthInit` +- `EmbedEvent.CopyToClipboard` +- `EmbedEvent.CustomAction` +- `EmbedEvent.Data` +- `EmbedEvent.DataSourceSelected` +- `EmbedEvent.DialogClose` +- `EmbedEvent.DialogOpen` +- `EmbedEvent.Download` +- `EmbedEvent.DownloadAsCsv` +- `EmbedEvent.DownloadAsPng` +- `EmbedEvent.DownloadAsXlsx` +- `EmbedEvent.DrillDown` +- `EmbedEvent.DrillExclude` +- `EmbedEvent.DrillInclude` +- `EmbedEvent.Edit` +- `EmbedEvent.Error` +- `EmbedEvent.Load` +- `EmbedEvent.Pin` +- `EmbedEvent.Save` +- `EmbedEvent.TableVizRendered` +- `EmbedEvent.VizPointClick` +- `EmbedEvent.VizPointDoubleClick` +- `EmbedEvent.VizPointRightClick` + +For more information, see xref:EmbedEvent.adoc[EmbedEvent]. + +|==== + +== Version 1.38.0, June 2025 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| *String IDs for text customization* + +Developers can now customize a specific occurrence of a visible text string in the ThoughtSpot UI using the `stringIDs` object in the customization interface. + +To locate the string IDs, SDK provides the `exposeTranslationIds` attribute. By setting `exposeTranslationIds` to `true` in the Playground, you can find the string ID of the UI text and use it in your customization code. + +Additionally, the SDK provides the `StringIDsUrl` attribute to allow using a JSON file with string IDs and custom strings to override the visible text in the UI. + +For more information, see xref:customize-text-strings.adoc[Customize text strings]. + +|[tag greenBackground]#NEW FEATURE# a| *Hide columns on list pages* + + +In full app embedding, you can now hide the following columns on the *Liveboards* and *Answers* listing pages using the `hiddenListColumns` array: + +* *Author* + +`hiddenListColumns: [ListPageColumns.Author]` +* *Favorite* + +`hiddenListColumns: [ListPageColumns.Favourite]` +* *Last modified* + +`hiddenListColumns: [ListPageColumns.DateSort]` +* *Tags* + +`hiddenListColumns: [ListPageColumns.Tags]` +* *Share* + +`hiddenListColumns: [ListPageColumns.Share]` + + +For more information, see xref:full-app-customize.adoc#_hide_columns_on_list_pages_new_experience[Customize full application embed]. +|==== + +== Version 1.37.0, April 2025 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| +The SDK now provides the `customVariablesForThirdPartyTools` setting to pass custom variables when integrating third-party tools and running custom scripts in your embed. Developers can define this object in the **init()** function and add variables as key-value pairs. +This feature is available only if third-party integration is enabled on your instance and the script hosting domain URL is added to the CSP allowlist. + +For more information, see xref:3rd-party-script.adoc[Integrate third-party tools and allow custom scripts]. + +|[tag greenBackground]#NEW FEATURE# a| +You can now exclude search token string from the application URL by setting `excludeSearchTokenStringFromURL` to `true` in your embed with ThoughtSpot token-based Search or Search bar. + +|[tag greenBackground]#NEW FEATURE# a| This version of the SDK supports the following embed and host events: + +Embed Events:: + +* `EmbedEvent.TableVizRendered` + +Emits when a table visualization is rendered in the ThoughtSpot embedded app. You can also use this event as a hook to trigger host events such as `HostEvent.TransformTableVizData` on the table visualization. For more information, see the link:https://developers.thoughtspot.com/docs/Enumeration_EmbedEvent#_tablevizrendered[SDK reference documentation]. + +* `EmbedEvent.CreateLiveboard` + +Emits when a Liveboard is created. + +Host Events:: + +* `HostEvent.TransformTableVizData` + +Triggers the table visualization re-render with the updated data. You can use this event in conjunction with `EmbedEvent.TableVizRendered` to apply the modifications to table visualization payload. + +* `HostEvent.Remove` + +Triggers the *Delete* action on a Liveboard. +|==== + +== Version 1.36.0, February 2025 + [width="100%" cols="1,4"] |==== |[tag greenBackground]#NEW FEATURE# a| -[discrete] -===== Spotter embedding -* The `SpotterEmbed` now includes the `isSpotterFullPageEnabled` parameter. When set to `true`, the Spotter interface occupies the full available height of the embed container. -* The `enableSpotterFileUpload` parameter enables file upload capability directly in embedded Spotter. +The following HostEvents now allow custom parameters to set object properties programmatically: + +* `HostEvent.SaveAnswer` + +Allows adding `name` and `description` text strings. When these parameters are defined, the event triggers the Save action to save the Answer with the predefined properties without opening the *Describe your Answer* modal. +* `HostEvent.Pin` + +Allows adding custom properties for visualization ID, name, and description, Liveboard ID, and Tab ID. When these parameters are defined, the event triggers an action to pin the Answer to the Liveboard specified in the code, without opening the *Pin* modal. + +For more information, see xref:events-hostEvents.adoc#hostEventParameterization[Host Events] documentation. |[tag greenBackground]#NEW FEATURE# a| -[discrete] -===== Liveboard embedding -* New action ID `Action.CopyToClipboard` to show or hide the *Copy to clipboard* option for Liveboard visualizations. -* The `LiveboardEmbed` now supports the `isFilterPanelOpen` attribute to set the initial open or closed state of the filter panel. +New configuration attributes:: + +* `disableSourceSelection` + +Disables data source selection panel for embed users when set to `true`. +* `hideSourceSelection` + +Hides data source selection panel when set to `true` +* `locale` + +Sets the xref:locale-setting.adoc[locale and regional settings] for the Spotter interface. +* `showSpotterLimitations` + +Shows functional limitations of Spotter when set to `true` +* `hideSampleQuestions` + +Hides sample questions that appear on the default Spotter page. + +Action IDs for menu customization:: +Use the following action IDs in the `disabledActions`, `visibleActions`, or `hiddenActions` array to disable, show, or hide menu actions and elements in the embedded Spotter interface: + +* `Action.PreviewDataSpotter` + +The *Preview data* button on the Spotter conversation panel. +* `Action.ResetSpotterChat` + +The *Reset* button on the Spotter conversation panel. +* `Action.SpotterFeedback` + +The feedback widget on Spotter-generated charts. +* `Action.EditPreviousPrompt` + +The edit icon on the prompt panel. +The Prompt panel appears after Spotter generates a response to a user query. +* `Action.DeletePreviousPrompt` + +The delete icon on the prompt panel. + +//// +* `Action.EditTokens` + +The option to edit tokens on a Spotter-generated chart or table. +//// +CSS variables:: + +The following new CSS variables are available for Spotter interface customization: + +* `--ts-var-spotter-input-background` +* `--ts-var-spotter-prompt-background` + +For more information about Spotter customization, see xref:embed-spotter.adoc#SpotterCSS[Customize styles]. |[tag greenBackground]#NEW FEATURE# a| -[discrete] -===== Full application embedding -The `AppEmbed` configuration now supports `hideApplicationSwitcher` to hide the application switcher control from the embedded ThoughtSpot navigation bar. -|==== + +Configuration attributes:: + +* `hideIrrelevantChipsInLiveboardTabs` + +Hides filter chips on a Liveboard when set to `true`. + +* `isLiveboardCompactHeaderEnabled` + +Enables the compact Liveboard header feature when set to `true`. + +Action IDs:: +Use the following action IDs in the `disabledActions`, `visibleActions`, or `hiddenActions` array to disable, show, or hide menu actions on an embedded Liveboard: + +* `Action.DisableChipReorder` + +ID for the action that disables filter chip reordering. +* `Action.ChangeFilterVisibilityInTab` + +|==== + +== Version 1.35.0, December 2024 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| +The SDK now provides the `isUnifiedSearchExperienceEnabled` setting to customize the Search experience on ThoughtSpot Home page for embedding application users: + +* When set to `true`, the split search experience is disabled and the Search bar on the Home page functions as Natural Language Search interface +* When set to `false`, the split search experience is enabled and object Search is set as the default Home page search experience. + +For more information, see xref:full-app-customize.adoc#_search_components[Search interface on the Home page in full application embedding]. + +|[tag greenBackground]#NEW FEATURE# a| The `overrideOrgId` parameter in the SDK provides the ability to override Org context for embedding application users. This parameter allows users authenticated to an Org to temporarily view content from another Org. Before specifying the Org ID for override, make sure the Per Org URL feature is enabled on your ThoughtSpot instance. To enable Per Org URL on your instance, contact ThoughtSpot Support. +|==== + +== Version 1.34.0, November 2024 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| You can now embed the following ThoughtSpot Spotter components in your app: + +* `SpotterEmbed` + +Embeds Spotter conversation interface in your app +* `SpotterAgentEmbed` + +Creates a conversation component without the body, which can be integrated into chatbots or other conversational apps. + +For more information, see xref:embed-spotter.adoc[Embed Spotter] and xref:spotter-in-custom-chatbot.adoc[Integrate Spotter into your chatbot]. + +|[tag greenBackground]#NEW FEATURE# a|The following parameters and enumerations are available for customizing Liveboard experience: + +* `showLiveboardVerifiedBadge` + +Shows or hides the Liveboard verified badge. Available if the Liveboard compact header feature is enabled. +* `showLiveboardReverifyBanner` + +Shows or hides the re-verify banner. Available if the Liveboard compact header feature is enabled. +* `Action.KPIAnalysisCTA` + +Action ID to show, hide, or disable the **Analyze CTA** action on a KPI chart. + +|[tag greenBackground]#NEW FEATURE# |You can now use the `HostEvent.GetIframeUrl` to get the iframe src URL from the Visual Embed Playground. If you are embedding ThoughtSpot in apps like Salesforce and Sharepoint without the SDK, use this event to generate the iframe URL. + +|[tag greenBackground]#NEW FEATURE# a|The following parameters are available for customizing Search experience: + +* `collapseDataPanel` +Minimizes the data panel view. Users can click the data panel header any time to expand the panel. +* `collapseSearchBar` +Sets the initial state of the search bar when embedding a saved Answer. + +|[tag greenBackground]#NEW FEATURE# a| The following settings are available for customizing the new home page and navigation experience in full app embedding: + +* `HomeLeftNavItem.LiveboardSchedules` + +The Liveboard schedules menu on the left navigation panel. + +Action enumerations:: + +* `Action.EditScheduleHomepage` + +To show, disable, or hide the *Edit* action on the *Liveboard schedules* page +* `Action.PauseScheduleHomepage` + +To show, disable, or hide the *Pause* action on the *Liveboard schedules* page +* `Action.ViewScheduleRunHomepage` + +To show, disable, or hide the *View run history* action on the *Liveboard schedules* page +* `Action.DeleteScheduleHomepage` + +To show, disable, or hide the *Delete* action on the *Liveboard schedules* page +* `Action.UnsubscribeScheduleHomepage` + +To show, disable, or hide the *Unsubscribe* action on the *Liveboard schedules* page +|==== + +== Version 1.33.x, October 2024 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| You can now customize the search experience for the embedded ThoughtSpot **Home** page using `homePageSearchBarMode`. By default, the **Home** page includes the Object Search bar, which allows finding popular Liveboards and Answers. + +You can set the `homePageSearchBarMode` property to one of the following options: + +** `aiAnswer` + +Displays the search bar for Natural Language Search. +** `none` +Hides the Search bar on the **Home** page. Note that it only hides the Search bar on the **Home** page and doesn't affect the Object Search bar visibility on the top navigation bar. +** `objectSearch` (default) + +Displays Object Search bar on the **Home** page. +|[tag greenBackground]#NEW FEATURE# a|The SDK now allows you to set the focus on the Search bar or outside the Search bar when rendering the embedded Search page. Use the `focusSearchBarOnRender` property to set the position of the cursor focus. +|[tag greenBackground]#NEW FEATURE# a| The SDK includes the following Event and Action enumeration members: + +Events:: + +* `EmbedEvent.OnBeforeGetVizDataIntercept` + +Developers can emit this event to intercept search execution, allow or restrict certain queries, and show an error message with custom text for restricted queries. To allow the embedded page to emit this event, you must set the `isOnBeforeGetVizDataInterceptEnabled` attribute to `true`. + +* `EmbedEvent.ParameterChanged` + +Emitted when a Parameter is changed on a saved Answer or Liveboard. + +Actions:: + +* `Action.ManageTags` + +Use this action enumeration to disable, show, or hide the **Manage tags** button on the Liveboards and Answers pages. +|==== + +== Version 1.32.x, August 2024 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| The following new action enumerations are available in this version: + + +* `Action.CreateLiveboard` for the *Create Liveboard* menu action on the Liveboards lists page. + +* `Action.SyncToTeams` for the **Sync to Teams** menu action on Liveboard visualizations. +* `Action.SyncToSlack` for the **Sync to Slack** action on Liveboard visualizations. +* `Action.AddQuerySet` for the **Add Query Set** action on the data panel (new experience) of the Search page. +* `Action.AddColumnSet` for the **Add Column Set** action on the data panel (new experience) of the Search page. +* `Action.AddDataPanelObjects` for the **Add** menu that includes sub-menu options such as Formulas, Parameters, Query set, and Column set actions. +* `Action.OrganiseFavourites` for the **Organize** action above the Favorites panel on the modular Homepage (New experience) +For more information, see xref:Action.adoc[Actions]. +|[tag greenBackground]#NEW FEATURE#| Developers can now use the `disableRedirectionLinksInNewTab` parameter to disable links and redirection of links in the embedded view. +|[tag greenBackground]#NEW FEATURE# a|You can now enable `enable2ColumnLayout` on a Liveboard to adjust the page view according to the width and resolution of users' devices. +|| +|==== + +== Version 1.31.x, July 2024 +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| Runtime filters + + +* `NOT_IN` operator for Runtime filters. +For more information, see xref:runtime-filters.adoc#runtimeFilterOp[Runtime filters]. +* `excludeRuntimeParametersfromURL` parameter to exclude or remove runtimeParameters from the URL. +|[tag greenBackground]#NEW FEATURE# |For performance optimization, developers can choose to load embedded views in a lightweight V2 shell by setting `enableV2Shell_experimental` to `true`. +|==== + +== Version 1.30.0, June 2024 +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| **CSS variables for new homepage experience** + +* `--ts-var-home-watchlist-selected-text-color` + +* `--ts-var-home-card-color` + +* `--ts-var-home-favorite-suggestion-card-text-color` + +* `--ts-var-home-favorite-suggestion-card-background` + +* `--ts-var-home-favorite-suggestion-card-icon-color` + +For more information, see xref:css-customization.adoc#_homepage_modules_new_experience_mode[CSS variables and overrides]. +|==== + +== Version 1.29.0, May 2024 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| **Ask Sage** + +With Ask Sage [beta betaBackground]^Beta^ embedded application users can ask follow-up questions on a visualization generated from a Natural Language Search query, converse with AI analyst, and refine results. To enable this feature, set `enableAskSage` to `true`. + +Action enumeration:: +To show, hide, or disable Ask Sage on a visualization, add `Action.AskAi`. For example, ++ +[source,JavaScript] +---- +hiddenActions: [Action.AskAi] +---- + +Events:: +* `HostEvent.AskSage` + +Triggers the **Ask Sage** action on a Liveboard visualization. +* `EmbedEvent.AskSageInit` + +Emits when the **Ask Sage** action is initialized. +* `HostEvent.GetParameters` + +Triggers a fetch action to get runtime Parameters. +* `HostEvent.UpdateParameters` + +Updates runtime Parameters +* `HostEvent.ResetLiveboardPersonalisedView` + +Resets a personalized Liveboard view. +* `HostEvent.UpdateCrossFilter` + +Updates cross filters applied on a Liveboard. +|==== + +== Version 1.28.x, April 2024 + +[width="100%" cols="1,4"] +|===== +|[tag greenBackground]#NEW FEATURE# a| The SDK includes the following new enumeration members in v1.28.0: + +** `Action.VerifiedLiveboard` + +Can be used to show or hide the *Verified Liveboard* banner. +|[tag greenBackground]#NEW FEATURE# a| To access the new Home page and global navigation experience in the full application embedding, you can use the `modularHomeExperience` property in the SDK. The modular homepage experience is turned off by default and is available as an Early Access feature in 9.12.5.cl release. When `modularHomeExperience` is set to `true`, you can use the following parameters in the SDK to control the application experience: + +* `hiddenhomeleftnavitems` +* `hiddenhomepagemodules` +* `hideapplicationswitcher` +* `hidehomepageleftnav` +* `hideorgswitcher` +* `reorderedhomepagemodules` +* `HomeLeftNavItem` + +For more information, see xref:full-app-customize.adoc[Customize full application embedding] and xref:AppViewConfig.adoc[AppViewConfig]. +|[tag greenBackground]#NEW FEATURE# a| The following embed event is available from the v1.28.0 onwards: + +`EmbedEvent.Rename` + +Emits when an embedded Liveboard or visualization is renamed. +|[tag greenBackground]#NEW FEATURE# a| TML actions + +The following TML menu actions are now grouped under the **TML** sub-menu of the **More** image:./images/icon-more-10px.png[the more options menu] menu on Answer page. + +* Export TML +* Edit TML +* Update TML + +To show, hide, or disable these actions in the embedded mode, use the following format: + +[source,JavaScript] +---- + // to show the TML menu and its sub-menu options +visibleActions: [Action.TML, Action.ExportTML, Action.EditTML] +---- + +[source,JavaScript] +---- + // to hide all TML actions +hiddenActions: [Action.TML] +---- + +[source,JavaScript] +---- + // to disable all TML actions +disabledActions: [Action.TML] +---- +|[tag greenBackground]#NEW FEATURE# | You can now reset authentication token and fetch a new token for new authentication requests. +For more information, see link:https://developers.thoughtspot.com/docs/Function_resetCachedAuthToken[resetCachedAuthToken]. + +|[tag greenBackground]#NEW FEATURE#| You can now override the default number, date, and currency format defined by your locale settings. To override the default settings, use the following parameters: + +* `numberFormatLocale` + +* `dateFormatLocale` + +* `currencyFormat` + +For more information, see xref:locale-setting.adoc#_set_locale_in_the_sdk[Customize locale]. + +|[tag greenBackground]#NEW FEATURE# |Tokenized fetch + +The SDK now provides a fetch wrapper that adds the authentication token to the API requests. +For more information, see link:https://developers.thoughtspot.com/docs/Function_tokenizedFetch#_tokenizedfetch[tokenizedFetch]. +|===== + +== Version 1.27.x, March 2024 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| The following action enumeration members are available from v1.27.9 and v1.27.10: + +* `Action.AIHighlights` +* `Action.AddToWatchlist` +* `Action.RemoveFromWatchlist` +* `Action.CopyKpiLink` + +For more information, see xref:Action.adoc[Action]. +| [tag greenBackground]#NEW FEATURE# a| You can now use `HostEvent.GetAnswerSession` to get Answer session data for a Search Answer or Liveboard Visualization in the embedded view. +|==== + +== Version 1.27.0, January 2024 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a|The `SageEmbed` package is now available on all clusters. You can use this SDK package to embed Natural Language Search capabilities and assist users with AI-suggested queries and AI-generated answers. This SDK package also allows you to customize the Natural Language Search experience in the embedded view. + +For a complete list of methods, functions, interface objects, and properties, see the following pages: + + +* xref:SageEmbed.adoc[SageEmbed] +* xref:SageViewConfig.adoc[SageViewConfig] + +|[tag orangeBackground]#MODIFIED# a| The `HostEvent.DrillDown` now supports the `vizId` parameter to trigger a drill-down action on a specific visualization of a Liveboard. +For more information, see xref:HostEvent.adoc#_drilldown[DrillDown]. +|[tag greenBackground]#NEW FEATURE# a| The new version of the SDK introduces the following new enumeration members: + +* Host Events +** `HostEvent.UpdateSageQuery` + +Updates the search query string for Natural Language Search operations. +* Embed Events +** `EmbedEvent.CreateConnection` + +Emitted when a user creates a new data connection on the **Data** page. +** `EmbedEvent.CreateWorksheet` + +Emitted when a user creates a new Worksheet. +|==== + +== Version 1.26.0, November 2023 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| The SDK provides `AnswerService` class to trigger the answer service with a custom action payload. +You can use this service to run GraphQL queries in the context of the Answer with a custom action trigger. For more information, see link:https://developers.thoughtspot.com/docs/Class_AnswerService[AnswerService]. Recommended ThoughtSpot application version is 9.10.0.cl. + +|[tag greenBackground]#NEW FEATURE# a|The following object properties and feature flags are introduced in the `LiveboardEmbed` and `AppEmbed` SDK packages: + +* `showLiveboardDescription` + +Shows the Liveboard description text when set to `true` +* `showLiveboardTitle` + +Shows the Liveboard title when set to `true` +* `isLiveboardHeaderSticky` + +Sets Liveboard header bar as a fixed element when set to `true` +* `hideLiveboardHeader` + +Hides the Liveboard header when set to `true` +* `hiddenTabs` + +Hides the specified tabs from the Liveboard page +* `visibleTabs` + +Displays the specified tabs on the Liveboard page + +|[tag greenBackground]#NEW FEATURE# |You can now enable the new data panel experience by setting `dataPanelV2` to `true` in the SDK when embedding ThoughtSpot Search. The new data panel experience is turned off by default on embedded ThoughtSpot instances. + +|[tag greenBackground]#NEW FEATURE# a|The new version of the SDK supports the following events: + +Embed events:: +* `EmbedEvent.hiddenTabs` +* `EmbedEvent.visibleTabs` +* `EmbedEvent.UpdatePersonalisedView` +* `EmbedEvent.SavePersonalisedView` +* `EmbedEvent.ResetLiveboard` +* `EmbedEvent.DeletePersonalisedView` +* `EmbedEvent.SageWorksheetUpdated` +* `EmbedEvent.SageEmbedQuery` ++ +For more information, see xref:EmbedEvent.adoc[EmbedEvent]. + +Host events:: + +* `HostEvent.GetTabs` +* `HostEvent.SetVisibleTabs` +* `HostEvent.SetHiddenTabs` +* `HostEvent.GetAnswerSession` +* `HostEvent.UpdateSageQuery` ++ +For more information, see xref:HostEvent.adoc[HostEvent]. + +|[tag greenBackground]#NEW FEATURE# a| The SDK introduces the following action enumeration members: + +* `Action.AddTab` + +Show, disable, or hide the **Add Tab** action on a Liveboard. +* `Action.PersonalisedViewsDropdown` + +Show, disable, or hide the Liveboard views saved by a user. +* `Action.LiveboardUsers` + +Show, disable, or hide Liveboard users. +* `Action.SageAnswerFeedback` +Show, disable, or hide the feedback widget on AI-generated Answer page. +* `Action.EditSageAnswer` +Show, disable, or hide the **Edit** action on the AI-generated Answer page. + +For more information, see xref:Action.adoc[Actions]. +|==== + +== Version 1.25.0, October 2023 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# | The SDK now supports runtime Parameter overrides on Liveboards and Answers. +For more information, see xref:runtime-parameters.adoc#_apply_parameter_overrides_using_visual_embed_sdk[Runtime Parameter overrides]. + +|[tag greenBackground]#NEW FEATURE# a| The SDK introduces the following action enumeration members: + +* `Action.RenameModalTitleDescription` +* `Action.EnableContextualChangeAnalysis` +* `Action.RequestVerification` +* `Action.AddTab` + +For more information, see xref:Action.adoc[Actions]. +|==== + +== Version 1.24.0, September 2023 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| ThoughtSpot now provides the `SageEmbed` package to embed the ThoughtSpot Search page with Sage features such as natural language search and AI-suggested search examples. This feature is in beta and not available in the Visual Embed Playground. +|[tag greenBackground]#NEW FEATURE# a| The `HostEvent.SetActiveTab` event in the upcoming version of the SDK allows you to set a tab as an active tab on a Liveboard. +|==== + +== Version 1.23.0, August 2023 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| The SDK supports the following performance optimization enhancements: + + +* Ability to pre-render a generic instance of the ThoughtSpot component using the `prerenderGeneric` attribute. The generic instance uses the default host and flags and can be rendered in the background to improve application response. +* Ability to use an iFrame from a pre-rendered iFrame pool using the `usePrerenderedIfAvailable` attribute. +|==== + +//// +|[tag greenBackground]#NEW FEATURE# a| New events for Liveboard filters + + +* `EmbedEvent.FilterChanged` + +* `HostEvent.GetFilters` + +* `HostEvent.UpdateFilters` +//// + +== Version 1.22.0, June 2023 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| The new version of the SDK introduces the `TrustedAuthTokenCookieless` `authType` property to allow Cookieless embedding. The Cookieless authentication method allows using a bearer token to identify the signed-in user instead of session cookies. + +For more information, see xref:embed-authentication.adoc#_cookieless_authentication[Cookieless authentication]. + +|[tag greenBackground]#NEW FEATURE# a|The new version of the SDK allows you to block user access to the non-embedded instance of the ThoughtSpot application. In full app embed deployments, you can use the `blockNonEmbedFullAppAccess` property in the SDK to restrict or allow your application users from accessing ThoughtSpot pages in the non-embed mode. + +For more information, see xref:security-settings.adoc#_block_access_to_non_embedded_thoughtspot_pages[Block access to non-embedded ThoughtSpot pages]. + +|==== + +//// +|[tag greenBackground]#NEW FEATURE# a| The SDK supports the following performance optimization enhancements: + + +* Ability to pre-render a generic instance of the ThoughtSpot component using the `prerenderGeneric` attribute. The generic instance uses the default host and flags and can be rendered in the background to improve application response. +* Ability to use an iFrame from a pre-rendered iFrame pool using the `usePrerenderedIfAvailable` attribute. +//// + +== Version 1.21.0, May 2023 +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a|The new version of the SDK introduces the following action enumeration members: + +* `Action.AxisMenuAggregate` +* `Action.AxisMenuConditionalFormat` +* `Action.AxisMenuEdit` +* `Action.AxisMenuFilter` +* `Action.AxisMenuGroup` +* `Action.AxisMenuNumberFormat` +* `Action.AxisMenuPosition` +* `Action.AxisMenuRemove` +* `Action.AxisMenuRename` +* `Action.AxisMenuSort` +* `Action.AxisMenuTextWrapping` +* `Action.AxisMenuTimeBucket` +* `Action.CrossFilter` +* `Action.RemoveCrossFilter` + +For more information, see xref:embed-action-ref.adoc[Action reference]. + +|[tag greenBackground]#NEW FEATURE# a| The SDK introduces the following events: + +* `HostEvent.AddColumns` +* `HostEvent.OpenFilter` +* `HostEvent.RemoveColumn` +* `HostEvent.ResetSearch` +* `EmbedEvent.CrossFilterChanged` +* `EmbedEvent.DownloadAsPng` +* `EmbedEvent.VizPointRightClick` + +For more information, see xref:embed-events.adoc[Events]. + +|[tag redBackground]#DEPRECATED# a| + +The following events are deprecated from version 1.21.0 onwards. + +* `HostEvent.Download` + +* `EmbedEvent.Download` + +You can use the `DownloadAsPng`, `DownloadAsXlsx`, `DownloadAsCsv` and `DownloadAsPdf` events for download actions. + +For more information, see xref:embed-events.adoc[Events reference]. +|[tag orangeBackground]#MODIFIED# a| + +Events:: +The SDK supports omitting or executing a search query in xref:HostEvent.adoc#_search[`HostEvent.Search`]. +Actions:: +Use the following action enumeration members instead of `Action.Download` to show, hide, or disable the *Download* menu action on an embedded Liveboard, visualization, or Answer: ++ +* `Action.DownloadAsCsv` +* `Action.DownloadAsPdf` +* `Action.DownloadAsXlsx` +* `Action.DownloadAsPng` + +To disable or hide download actions, you can use `Action.Download` in the `disabledActions` and `hiddenActions` arrays respectively. However, if you are using the `visibleActions` array to show or hide actions on a visualization or Answer, include the following download action enumerations along with `Action.Download` in the array: + + +** `Action.DownloadAsCsv` + +** `Action.DownloadAsPdf` + +** `Action.DownloadAsXlsx` + +** `Action.DownloadAsPng` + +|[tag greenBackground]#NEW FEATURE# a| The SDK includes new attributes to customize the experience for embedded app users: + +* `linkOverride` ++ +Allows overriding the *Open in new tab* link on embedded pages. + +* `contextMenuTrigger` ++ +Allows triggering contextual menu on the Liveboard visualizations and Answers from left-click to right-click. + +* `hideSearchBar` ++ +Allows hiding the Search bar on the embedded Search page. +|[tag greenBackground]#NEW FEATURE# | The SDK now allows setting the loading preference for embedded iFrames. +For performance optimization, you can set the `loading` attribute to `lazy` in the `FrameParams` property. +|==== + +== Version 1.20.0, April 2023 + +[width="100%" cols="1,4"] +|==== +|[tag redBackground]#DEPRECATED# a|The `dataSources` property in `SearchEmbed` and `SearchBarEmbed` is deprecated and replaced with the `dataSource` attribute. The SDK supports searching from a single data source only. +|[tag greenBackground]#NEW FEATURE# a|The embed SDK packages now include the `insertAsSibling` property. This attribute can be used to insert the embedded object as a sibling to the element inside the target container. +|==== + +== Version 1.19.0, February 2023 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a|The `customCSS` property in the `customizations` object supports new variables to customize the styles for dialogs, search bar, search navigation and search suggestions panels. +For more information, see xref:css-customization.adoc[Customize CSS]. +|[tag redBackground]#BREAKING CHANGE# a|The new Liveboard experience mode introduces changes to the data format of the JSON response payload triggered by callback custom actions. For example, the `reportBookData`, and `vizData` attributes are modified, and the custom action `id` now is part of the data attribute. These changes may break your current custom action event handlers. For interoperability, we recommend adding the data attribute to `payload` in your code as shown in the example here: + +[source,JavaScript] +---- +liveboardEmbed.on(EmbedEvent.CustomAction, payload => { + if (payload.id === "callback-action-id" \|\| payload.data.id === "callback-action-id") { + console.log('Custom Action event:', payload.data); + } +}) +---- + +You may also want to update the data classes in your scripts to process the JSON response payload and handle complex data. For more information, see xref:custom-actions-callback.adoc#_define_functions_and_classes_to_handle_liveboard_data[Callback custom actions]. + +|[tag greenBackground]#NEW FEATURE# a|The new version of the SDK introduces the following Host events: + +* `HostEvent.Delete` +* `HostEvent.Download` +* `HostEvent.DownloadAsCsv` +* `HostEvent.DownloadAsXlsx` +* `HostEvent.ManagePipelines` +* `HostEvent.Save` +* `HostEvent.Share` +* `HostEvent.ShowUnderlyingData` +* `HostEvent.SpotIQAnalyze` +* `HostEvent.SyncToOtherApps` +* `HostEvent.SyncToSheets` + +For more information, see xref:events-hostEvents.adoc[Host events]. + +|[tag redBackground]#DEPRECATED# a|The `noRedirect` property in the SDK is deprecated and replaced with the `inPopup` attribute. When set to `true`, the `inPopup` attribute allows the SAML SSO authentication flow in a pop-up window. + +For more information, see xref:embed-authentication.adoc#_saml_redirection[SAML Redirection]. +|==== + +== Version 1.18.0, January 2023 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a|The new version of the SDK provides the `SearchBarEmbed` JavaScript package to embed only the ThoughtSpot Search bar in your app. + + +For more information, see xref:embed-searchbar.adoc[Embed ThoughtSpot search bar]. + +|[tag greenBackground]#NEW FEATURE# a|The `customCSS` property in the `customizations` object supports new variables to customize the UI elements on Liveboard, visualization, and Answer pages. You can also use these variables to define custom styles in the CSS file. + +For more information, see xref:css-customization.adoc[Customize CSS]. +|[tag greenBackground]#NEW FEATURE# |The new version of the SDK allows fetching TML objects via `GetTML` host event. This event is triggered when a user clicks on the *Show underlying data* action on a Liveboard visualization or Answer page. + + +For more information, see xref:HostEvent.adoc#_gettml[GetTML]. + +|[tag greenBackground]#NEW FEATURE# a| The new version of the SDK introduces the following enums in the `Action` object: + +* `Action.SyncToOtherApps` + +* `Action.SyncToSheets` + +* `Action.ManagePipelines` + + +You can use these enums to show, hide, or disable *Sync to sheets*, *Sync to other apps*, and *Manage pipelines* menu actions on a Liveboard visualization or Answer. + +For more information, see xref:embed-action-ref.adoc[Actions]. +|==== + +== Version 1.17.1, December 2022 + +Bug fixes to the trusted authentication feature. + +== Version 1.17.0, November 2022 + +The new version of the SDK introduces several new features and enhancements. +[width="100%" cols="1,4"] +|==== +|[tag orangeBackground]#MODIFIED# a|The `AuthType` property is modified and supports new enums. + + +* `AuthType.SAML` is renamed as `AuthType.SAMLRedirect` + +* `AuthType.OIDC` is renamed as `AuthType.OIDCRedirect` + +* `AuthType.AuthServer` is renamed to `AuthType.TrustedAuthToken` + +This enhancement does not introduce any breaking changes to your current implementation. +|[tag greenBackground]#NEW FEATURE# a|To use your current SAML or OIDC authentication setup and redirect users to the IdP for authentication within the embedded iFrame, you can now use `AuthType.EmbeddedSSO`. + +For more information, see xref:embed-authentication.adoc[Authentication]. +|[tag greenBackground]#NEW FEATURE#| +The `customizations` object in the SDK allows you to specify a custom CSS URL. You can also use this object to define CSS variables directly in the `init` code. + +For more information, see xref:css-customization.adoc[Customize CSS]. +|==== + +== Version 1.16.0, October 2022 + +The new version of the SDK includes bug fixes and improvements to the new Liveboard experience. + +== Version 1.15.1, September 2022 +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE#| +The `prefetch` method now supports the `url` and `prefetchFeatures` parameters. You can use these parameters to call the prefetch method before `init` and prefetch static resources on application load. + +For more information, see xref:prefetch-and-cache.adoc[Prefetch static resources]. +|==== + +== Version 1.15.0, September 2022 +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE#| +For embedded instances with the new Liveboard experience, the Visual Embed SDK provides the `activeTabId` attribute, using which you can set a Liveboard tab as an active tab. + +For more information, see xref:embed-pinboard.adoc#_liveboard_tabs[Customize Liveboard tabs]. + +|[tag greenBackground]#NEW FEATURE# a|The new version of the SDK supports firing events for Liveboard menu actions from the host application. The SDK introduces the following host event enumeration members for Liveboard objects: + +* CopyLink +* CreateMonitor +* DownloadAsPdf +* Edit +* EditTML +* Explore +* ExportTML +* LiveboardInfo +* MakeACopy +* ManageMonitor +* Pin +* Present +* Remove +* Schedule +* SchedulesList +* UpdateTML + +For more information, see xref:events-hostEvents.adoc[Events reference]. +|==== + +== Version 1.14.0, August 2022 +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE#| +The Visual Embed SDK now includes the `liveboardV2` attribute in the `LiveboardEmbed` package to allow developers to enable the new Liveboard experience on their embedded ThoughtSpot instance. + +For more information, see xref:embed-pinboard.adoc[Embed a Liveboard]. +|[tag orangeBackground]#MODIFIED#|If trusted authentication is enabled, the SDK makes a `POST` API call to get a login token and log the user into ThoughtSpot. +The earlier versions of the SDK supported only `GET` API requests. For more information, see xref:embed-authentication.adoc#_configure_token_based_authentication_method_in_visual_embed_sdk[Configure token-based authentication method in Visual Embed SDK]. +|==== + +== Version 1.13.0, July 2022 +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE#| +This version of Visual Embed SDK includes the `enableSearchAssist` attribute, using which you can turn on the Search Assist feature on an embedded instance. +|[tag greenBackground]#NEW FEATURE#| The new version of SDK introduces the `AuthType.SAML` enum for SAML-based SSO authentication. Note that `AuthType.SAML` replaces the `AuthType.SSO` enum, which is deprecated in the v1.13.0 version of the SDK. + +For more information, see xref:embed-authentication.adoc#saml-sso-embed[Authentication]. +|[tag redBackground]#DEPRECATED#| The `AuthType.SSO` enum is deprecated in v1.13.0. ThoughtSpot recommends using `AuthType.SAML` for the SAML SSO authentication method. + +This change does not impact your current embed implementation with `AuthType.SSO`. +|[tag greenBackground]#NEW FEATURE#| The SDK includes the `getExportRequestForCurrentPinboard` event, which is triggered when a user tries to export a Liveboard in its current state. + +For more information, see xref:events-hostEvents.adoc[Events reference]. +|==== + +== Version 1.12.0, June 2022 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE#| +This version of Visual Embed SDK introduces the `navigate` host event, which is triggered when a user navigates to an application page without a page reload. + +For more information, see xref:events-hostEvents.adoc[Events reference]. +|[tag greenBackground]#NEW FEATURE# | The new `getThoughtSpotPostUrlParams` method fetches ThoughtSpot URL query parameters prefixed with `ts-`. +|==== + +== Version 1.11.2, June 2022 + +Bug fix for Typescript builds that affect Angular project configurations. + +== Version 1.11.1, May 2022 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE#| The SDK includes the action enum `ReportError`, using which you can turn off ThoughtSpot-specific error reporting. +|==== + +== Version 1.11.0, May 2022 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| The new version of SDK includes the following new events: + +* `ALL` +* `AnswerChartSwitcher` +* `AnswerDelete` +* `CopyAEdit` +* `CopyToClipboard` +* `Download` +* `DownloadAsPdf` +* `DownloadAsCsv` +* `DownloadAsXlsx` +* `DrillExclude` +* `DrillInclude` +* `EditTML` +* `ExportTML` +* `Monitor` +* `Pin` +* `Save` +* `SaveAsView` +* `Share` +* `ShowUnderlyingData` +* `SpotIQAnalyze` +* `UpdateTML` +* `VizPointClick` + +For more information about how to register and handle these events, see xref:embed-events.adoc[Events and app integration]. +|[tag greenBackground]#NEW FEATURE# a| The new version of SDK supports the `showAlerts` attribute, using which you can show or hide alerts and error messages in the embedded view. + +|[tag greenBackground]#NEW FEATURE# a| The `Action.CreateMonitor` enumeration is available in the SDK for embedded ThoughtSpot environments on which the *Monitor* feature is enabled. +For more information, see xref:embed-actions.adoc[Show or hide UI actions]. +|==== + +== Version 1.10.4, May 2022 +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE#|The `detectCookieAccessSlow` parameter in the SDK allows your app to check if third-party cookies are enabled on the browser. This parameter is available only for trusted and `Basic` authentication types. +|==== +== Version 1.10.3, May 2022 + +Bug fix and improvements to the `logout` method. + +== Version 1.10.2, May 2022 +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE#|Ability to configure `redirectPath` on the origin when using the SAMLRedirect `authType`. +|==== + +== Version 1.10.1, May 2022 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE#|You can now use the `logout` method to log out embed users. +|[tag orangeBackground]#MODIFIED# a| Note the following changes: + + +* You can now use the `loginFailedMessage` property on init to display the `Not logged in` message when a user login fails. You can customize this message by defining a custom text string in the `loginFailedMessage` attribute. +* The `init` method now returns an event emitter which can be used to listen to `AuthStatus` such as login failure, success, or user logout. +|==== + +== Version 1.10.0, April 2022 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| The `AddRemoveColumns` event is now available in the SDK. For more information, see xref:event-embedEvents.adoc[Events reference]. +|==== + +== Version 1.9.8, April 2022 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE#|The `pageId` attribute now allows you to set the **SpotIQ** page as the home tab of your embedded ThoughtSpot app. + +For more information, see xref:full-embed.adoc[Embed full application]. +|==== + +== Version 1.9.6 and 1.9.7, April 2022 + +Bug fixes and improvements + +== Version 1.9.5, April 2022 +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE#|The `locale` attribute is now available in embed packages. You can use this attribute to set the locale or language of your embedded application view. +For more information, see xref:locale-setting.adoc[Set locale and display language]. +|==== + +== Version 1.9.4, April 2022 + +Bug fixes and improvements to React components. + +== Version 1.9.3, March 2022 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE#| The SDK now supports the `disableLoginRedirect` attribute to improve the login experience for your application users. When enabled, this attribute prevents your app from redirecting users to the login page when their session expires. + +You can use this attribute along with `autoLogin` to automatically authenticate and re-login a user. + +This feature is applicable to token-based authentication, that is, when the `AuthType` is set as `TrustedAuthToken` in the SDK. + +For more information, see xref:embed-authentication.adoc#trusted-auth-embed[Authentication]. +|==== + +== Version 1.9.2, March 2022 +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE#| You can now trigger events on React components using the `useEmbedRef` hook. + +For more information, see xref:embed-ts-react-app.adoc[Embed ThoughtSpot in a React app]. +|==== + +== Version 1.9.1, March 2022 +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE#| The SDK now includes the `visibleVizs` attribute in the `LiveboardEmbed` package. This attribute allows you to add visualization GUIDs that you want to display when a Liveboard renders for the first time. + +For more information, see xref:embed-pinboard.adoc[Embed a Liveboard]. + +|[tag greenBackground]#NEW FEATURE# a| The following events are now available in the SDK: + + +* `LiveboardRendered` (EmbedEvent) + +For more information, see xref:event-embedEvents.adoc[Events reference]. +|==== + +== Version 1.9.0, March 2022 +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| The SDK now includes the following new enumerations for UI actions: + +* `Action.AnswerDelete` + +* `Action.AnswerChartSwitcher` + +* `Action.AddToFavorites` + +* `Action.EditDetails` + + +For more information, see xref:embed-actions.adoc#standard-actions[Show or hide UI actions]. + +|[tag greenBackground]#NEW FEATURE# a| The SDK now supports the `UpdateRuntimeFilters` host event. For more information, see xref:events-hostEvents.adoc[Events reference]. +|==== + +== Version 1.8.x, February 2022 + +[width="100%" cols="1,4"] +|==== +|[tag redBackground]#BREAKING CHANGE# | The `autoLogin` attribute is now set as `false` by default. This attribute is used in the `init` method to automatically re-login a user when a session expires. +|[tag greenBackground]#NEW FEATURE# | The `init` method now returns the `authPromise` which resolves when a user authentication is completed. +|==== + + +== Version 1.7.0, January 2022 + +[width="100%" cols="1,4"] +|==== +| +[tag greenBackground]#NEW FEATURE# |+++
OIDC AuthType
+++ + +The SDK supports the `OIDC` `authType` in `init` calls. If you want your application users to authenticate to an OpenID provider and use their SSO credentials to access the embedded ThoughtSpot content, you can enable the `OIDC` authentication type in the SDK. + +For more information, see xref:embed-authentication.adoc#oidc-auth[Authentication and security attributes]. +|[tag greenBackground]#NEW FEATURE# a|+++
Embed events
+++ + +The SDK includes the following new event: + +* `RouteChange` + +For more information, see xref:event-embedEvents.adoc[Events reference]. + +|==== + +== Version 1.6.x, November 2021 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a|+++
Visible actions
+++ + +You can now configure a set of ThoughtSpot UI actions as visible actions and display these actions in the embedded UI. If your embedded instance requires only a few actions, you can use the `visibleActions` API to show only these actions in the embedded ThoughtSpot UI. + +For more information, see xref:embed-actions.adoc[Show or hide UI actions]. + +|[tag orangeBackground]#MODIFIED# | +++
Terminology changes
+++ + +The SDK library and object parameter names are modified to rebrand pinboards as Liveboards. For a complete list of changes, see xref:terminology-update.adoc#sdk-changes[Terminology changes]. + +|[tag greenBackground]#NEW FEATURE# a|+++
Embed events
+++ + +The SDK supports the following new events: + +* `DialogOpen` +* `DialogClose` + +For more information, see xref:event-embedEvents.adoc[Events reference]. +|==== + +== Version 1.5.0, October 2021 + +[width="100%" cols="1,4"] +|==== +|| +|[tag greenBackground]#NEW FEATURE# | +++
Render embedded objects in queue
+++ + +The SDK now supports rendering embedded objects in a queue. If you have multiple embedded objects, you can enable the `queueMultiRenders` parameter to queue your embedded objects and render them one after another. This feature helps in decreasing the load on the web browsers and improving your application loading experience. By default, this attribute is set to `false`. + +|[tag greenBackground]#NEW FEATURE# a|+++
Liveboard embed
+++ + +The `pinboardEmbed` package includes the `defaultHeight` attribute that sets a minimum height for embedded objects on a pinboard page, and the corresponding visualization pages that a user can navigate to. + +For more information, see xref:embed-search.adoc[Embed a pinboard]. + +|[tag greenBackground]#NEW FEATURE# a|+++
Embed events
+++ + +The SDK EmbedEvent library includes the following new events: + +* `VizPointDoubleClick` +* `Drilldown` +* `SetVisibleVizs` + +For more information, see xref:event-embedEvents.adoc[Events reference]. + +|==== + +== Version 1.4.0, September 2021 + +[width="100%" cols="1,4"] +|==== +|| +|[tag greenBackground]#NEW FEATURE# a|+++
+++Prefetch API+++
+++ + +The `prefetch` API fetches static resources from a given URL before your application loads. Web browsers can then cache the prefetched resources locally and serve them from a user's local disk. You can use this API to load the embedded objects faster and improve your application response time. + +For more information, see xref:prefetch-and-cache.adoc[Prefetch static resources]. + +|[tag greenBackground]#NEW FEATURE# a|+++
+++In-app page navigation+++
+++ + +The `navigateToPage` method in the SDK lets you provide quick and direct access to a specific pinboard, saved Answer, or an application page. You can add a custom menu action or button in your application UI that calls the `navigateToPage` method and leads your users to the page specified in the `path` parameter. + +For more information, see xref:page-navigation.adoc[Add a custom action for in-app navigation]. + +|[tag greenBackground]#NEW FEATURE# a|+++
+++Full application embedding+++
+++ + +The `appEmbed` SDK package includes the following new attributes: + +* The `disableProfileAndHelp` attribute to show or hide the `Help (?)` and the user profile menu in the navigation bar of your embedded app. + +* The `hideObjects` attribute to hide specific objects from a user's page view. + +For more information, see xref:full-embed.adoc[Embed full application]. + +|[tag greenBackground]#NEW FEATURE# |+++
+++Search embed +++
+++ + +The `searchEmbed` package includes the `forceTable` attribute that sets tabular view as the default format for presenting search data. You can set this attribute to `true` to force search results to appear in the table view. + +For more information, see xref:embed-search.adoc[Embed ThoughtSpot search]. + +|[tag redBackground]#REMOVED# | + +The `searchQuery` parameter is no longer supported and is removed from the `searchEmbed` SDK package. +|[tag greenBackground]#NEW FEATURE# a|+++
+++Embed events +++
+++ +The SDK EmbedEvent library includes the following events: + +* `QueryChanged` +* `AuthExpire` + +For more information, see xref:embed-events.adoc[Events and app integration]. +|==== + +== Version 1.3.0, August 2021 + +[width="100%" cols="1,4"] +|==== +|| +|[tag greenBackground]#NEW FEATURE# a| +++
searchOptions
+++ + +The `searchEmbed` SDK package introduces the `searchOptions` parameter for setting search tokens. The `searchOptions` parameter includes the following attributes: + +* `searchTokenString` ++ +A TML query string to define search tokens. + +* `executeSearch` ++ +When set to `true`, it executes search and shows the search results. + +For more information, see xref:embed-search.adoc#search-query[Embed ThoughtSpot search]. + +|[tag redBackground]#DEPRECATED# a| +++
searchQuery
+++ + +The `searchQuery` parameter in the `searchEmbed` SDK package is deprecated in the Visual Embed SDK version 1.3.1. Instead, you can use the `searchOptions` parameter to define the search token string. + +For more information about `searchOptions`, see xref:embed-search.adoc#search-query[Embed ThoughtSpot search]. + +|[tag greenBackground]#NEW FEATURE# a| +++
autoLogin
+++ + +The SDK now supports logging in users automatically after a user session has expired. + +For more information, see xref:embed-authentication.adoc#embed-session-sec[Embed user authentication]. + +|[tag greenBackground]#NEW FEATURE# a| +++
shouldEncodeUrlQueryParams
+++ + +You can now convert query parameters in the ThoughtSpot generated URLs to base64-encoded format. You can enable this attribute to secure your cluster from cross-site scripting attacks. +|[tag redBackground]#BREAKING CHANGE# a| +++
Data structure changes in custom action response payloads
+++ + +* The data structure passed in the custom action response for search now shows as `payload.data.embedAnswerData` instead of `payload.data.columnsAndData`. + +* The Answer payload for custom actions includes the following metadata: + +** `reportBookmetadata` ++ +Includes visualization metadata attributes such as description, object header metadata, author details, timestamp of the Answer creation, and modification. + +** user data ++ +Includes user information such as username, GUID of the user, and email address. + +To view a sample response payload, see xref:callback-response-payload.adoc#search-data-payload[Custom action response payload]. + +|[tag greenBackground]#NEW FEATURE# a| +++
preventPinboardFilterRemoval
+++ + +The `pinboardEmbed` SDK package now includes the `preventPinboardFilterRemoval` attribute. You can use this attribute to disable the filter removal action and thus prevent users from removing the filter chips added on a pinboard page. + +For more information, see xref:embed-pinboard.adoc[Embed a pinboard] and xref:embed-a-viz.adoc[Embed a visualization]. +|[tag greenBackground]#NEW FEATURE# a| +++
suppressNoCookieAccessAlert
+++ + +You can now set custom alerts for `noCookieAccess` events. By default, the SDK triggers a `noCookieAccess` event and generates an alert when a user's browser blocks third-party cookies. The `suppressNoCookieAccessAlert` allows you to disable this alert. + +|[tag greenBackground]#NEW FEATURE# a| +++
Support for fetching callback custom action payload in batches
+++ + +The Visual Embed SDK now supports processing data in batches for callback custom action responses. +The callback custom action event in the SDK package supports defining `batchSize` and `offset` values to paginate the Answer payload and send the records in batches. + +For more information, see xref:push-data-to-external-app.adoc#large-dataset[Callback custom action workflow]. +|==== + +== Version 1.2.0, June 2021 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a|+++
SAML authentication
+++ + +The Visual Embed SDK packages now include the `noRedirect` attribute as an optional parameter for the SAMLRedirect SSO `AuthType`. If you want to display the SAML authentication workflow in a pop-up window, instead of refreshing the application web page to direct users to the SAML login page, you can set the `noRedirect` attribute to `true`. + +For more information, see the instructions for embedding xref:full-embed.adoc[ThoughtSpot pages], xref:embed-search.adoc[search], xref:embed-pinboard.adoc[pinboard], and xref:embed-a-viz.adoc[visualizations]. + +|[tag greenBackground]#NEW FEATURE# a|+++
Pinboard actions
+++ +The *More* menu image:./images/icon-more-10px.png[the more options menu] in the embedded Pinboard page now shows the following actions for pinboard and visualizations. + +Pinboard:: +* Save +* Make a copy +* Add filters +* Configure filters +* Present +* Download as PDF +* Pinboard info +* Manage schedules + + +[NOTE] +Users with edit permissions can view and access the *Save*, *Add filters*, *Configure filters*, and *Manage schedules* actions. +|[tag greenBackground]#NEW FEATURE# a|+++
Visualization actions
+++ + +Visualizations on a pinboard: + +* Pin +* Download +* Edit +* Present +* Download as CSV +* Download as XLSX +* Download as PDF + +[NOTE] +Users with edit permissions can view and access the *Edit* action. The *Download as CSV*, *Download as XLSX*, and *Download as PDF* actions are available for table visualizations. The *Download* action is available for chart visualizations. + +|==== + +== Version 1.1.0, May 2021 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a|+++
NoCookieAccess event
+++ + +When a user accesses the embedded application from a web browser that has third-party cookies disabled, the Visual Embed SDK emits the `NoCookieAccess` event to notify the developer. Cookies are disabled by default in Safari. Users can enable third-party cookies in Safari’s Preferences setting page or use another web browser. +To know how to enable this setting by default on Safari for a ThoughtSpot embedded instance, contact ThoughtSpot Support. +|==== \ No newline at end of file From c152a930a035739745ab62d84de32e16feb6216b Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 17 Aug 2026 10:34:26 +0530 Subject: [PATCH 041/154] docs: add Answer Report API GA section (SCAL-306069) --- modules/ROOT/pages/data-report-v2-api.adoc | 629 +++++++++++++++++---- 1 file changed, 524 insertions(+), 105 deletions(-) diff --git a/modules/ROOT/pages/data-report-v2-api.adoc b/modules/ROOT/pages/data-report-v2-api.adoc index 648618486..f1ed36d8e 100644 --- a/modules/ROOT/pages/data-report-v2-api.adoc +++ b/modules/ROOT/pages/data-report-v2-api.adoc @@ -204,173 +204,592 @@ curl -X POST \ -H 'Accept: application/json'\ -H 'Content-Type: application/json' \ --data-raw '{ - "metadata_identifier": "9bd202f5-d431-44bf-be0b-bb9354c7a840", - "data_format": "COMPACT", - "record_offset": 0, - "record_size": 10 + "metadata_identifier": "f605dbc7-db19-450b-8613-307118f74c3c", }' ---- + == Report APIs -ThoughtSpot provides the following REST API v2 endpoints to download data as reports: -* xref:#_liveboard_report_api[`POST /api/rest/2.0/report/liveboard`] to download a Liveboard or specific visualizations on the Liveboard as a PDF, PNG, or CSV file. -* xref:#answer-report[`POST /api/rest/2.0/report/answer`] to download Answer data as a CSV, XLSX, PDF, or PNG file. +ThoughtSpot provides the following REST API v2 endpoints to fetch data: + +* xref:_liveboard_report_api[`POST /api/rest/2.0/report/liveboard`] + +Download a Liveboard and its visualizations in PDF, PNG, CSV, or XLSX file format. +* xref:#_answer_report_api[`POST /api/rest/2.0/report/answer`] + +Download data from a saved Answer in PDF, PNG, CSV, or XLSX file format. === Liveboard Report API -The Liveboard Report API allows you to programmatically download a Liveboard or specific visualizations as a PDF, PNG, or CSV file via `POST /api/rest/2.0/report/liveboard`. -To use this API endpoint, you need at least view access to the Liveboard. If Role-Based Access Control (RBAC) is enabled on your instance, you also need the `DATADOWNLOADING` privilege or one of the granular download privileges listed below. +To download a Liveboard report via `/api/rest/2.0/report/liveboard` API, you need at least view access to the Liveboard specified in the API request. -The following report types are available: +In the `POST` request body, specify the GUID or name of the Liveboard as `metadata_identifier`. To download reports with specific visualizations, add GUIDs or names of the visualizations in the `visualization_identifiers`. -PDF:: -Downloads the entire Liveboard as a PDF file. +To download visualizations from a specific Liveboard tab, specify the name or GUID of the tab in the `tab_identifiers` parameter. -PNG:: -Downloads a single visualization on the Liveboard as a PNG file. Requires `visualization_identifiers` with a single visualization GUID. +To download a personalized view of the Liveboard, specify the view name in the `personalised_view_identifier` attribute. -CSV:: -Downloads the data from a single visualization on the Liveboard as a CSV file. Requires `visualization_identifiers` with a single visualization GUID. +[IMPORTANT] +==== +* The downloadable file returned in API response file is extensionless. You need to rename the downloaded file by typing in the relevant extension. +* If the Liveboard includes Note tiles, ensure that you do not pass the GUID of Note tiles as `visualization_identifiers` in the API request. Attempting to do so will lead to an error, and the API will return 400 error code in response. +* Attempting to override existing filter values with runtime filters while exporting a Liveboard will result in an error. +* If Role-Based Access Control (RBAC) is enabled, `DATADOWNLOADING` (Can download Data) privilege is required for Liveboard exports. +* If the granular Role-Based Access Control (RBAC) is enabled, the `CAN_DOWNLOAD_DETAILED_DATA` (Can download detailed data) privilege is required to export in the XLSX or CSV formats, and the `CAN_DOWNLOAD_VISUALS` (Can download visuals) privilege is required for PDF or PNG exports. In this case the `DATADOWNLOADING` privilege ceases to exist. +==== -==== Request parameters +==== File Formats -[width="100%" cols="2,1,4"] -[options="header"] -|===== -| Parameter | Required | Description -| `metadata_identifier` | Yes | GUID or name of the Liveboard to download. -| `file_format` | Yes | Report format. Accepted values: `PDF`, `PNG`, `CSV`, `XLSX`. -| `visualization_identifiers` | Conditional | Array of visualization GUIDs. Required when `file_format` is `PNG` or `CSV`. For PDF, optional — if not specified, all visualizations are included. -| `runtime_filter` | No | Runtime filter overrides to apply. -| `runtime_sort` | No | Runtime sort overrides to apply. -| `runtime_param_override` | No | Runtime parameter overrides to apply. -| `transient_content` | No | Liveboard data with unsaved changes. -| `pdf_options` | No | PDF-specific options: `orientation` (`PORTRAIT` or `LANDSCAPE`), `truncate_tables` (boolean), `include_logo`, `footer_text`, `include_page_number`, `cover_page`, `filter_page`. -|===== +The default `file_format` is *CSV*. + +[NOTE] +If you do not have .csv downloads enabled for your ThoughtSpot instance, select either `PDF` or `PNG` `file_format` to successfully download the report. Using any other format will cause the API to return an error. + + +For *CSV* downloads, + +* Each visualization is exported as a separate .csv file. +* If multiple visualizations are selected, the downloaded report is a single compressed .zip file containing all .CSV files. +* It does not support any additional parameters to customize the page orientation and `include_cover_page`, `include_filter_page`, logo, footer text, and page numbers. +* Charts are exported as tabular data. Downloaded reports may include columns not seen in the visualization if they were used as tokens in the underlying search query. + +===== Sample API payload for CSV downloads -==== Example [source,cURL] ---- curl -X POST \ --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/liveboard' \ - -H 'Authorization: Bearer {access-token}' \ - -H 'Accept: application/octet-stream' \ + -H 'Authorization: Bearer {access-token}'\ -H 'Content-Type: application/json' \ - --data-raw '{ - "metadata_identifier": "d084c256-e284-4fc4-b80c-111cb606449a", - "file_format": "PDF", - "pdf_options": { - "orientation": "LANDSCAPE", - "include_logo": true, - "include_page_number": true - } -}' \ - --output liveboard.pdf +--data-raw '{ +"metadata_identifier": "416052fd-ad22-4d48-be0a-e43b53109957", +"file_format": "CSV", +"tab_identifiers": [ +"bc6d6fb8-1e06-4617-b02f-51745e6933a6" +] +}' ---- -[#answer-report] -=== Answer Report API +For *XLSX* downloads, -// SOURCE: SCAL-306069 +* Visualization is exported as an Excel workbook (.xlsx). +* If multiple visualizations are selected, the downloaded report is a single Excel workbook (.xlsx) containing each visualization in their individual tab. +* A maximum of 255 tabs per .xlsx workbook are allowed. +* It does not support any additional parameters to customize the page orientation and `include_cover_page`, `include_filter_page`, logo, footer text, and page numbers. +* Charts are exported as tabular data. Downloaded reports may include columns not seen in the visualization if they were used as tokens in the underlying search query. +* New pivot tables generated in .xlsx workbooks using this API endpoint retain their complete visual formatting and structural integrity. -The `POST /api/rest/2.0/report/answer` endpoint is generally available from 26.9.0.cl. Use this endpoint to export Answer data in CSV, XLSX, PDF, or PNG format. The endpoint supports saved Answers, pinned Answers (visualizations on a Liveboard), and Spotter-generated (ad hoc) Answers. +===== Sample API payload for XLSX downloads -==== Prerequisites +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/liveboard' \ + -H 'Authorization: Bearer {access-token}'\ + -H 'Content-Type: application/json' \ +--data-raw '{ +"metadata_identifier": "416052fd-ad22-4d48-be0a-e43b53109957", +"file_format": "XLSX", +"visualization_identifiers": [ +"254c6e30-680c-41ea-aa4d-bb059f745462" +] +}' +---- -To download Answer data, the user must have at least *View* access to the Answer or Liveboard. If RBAC is enabled: +For *PDF* downloads, you can specify additional parameters to customize the page orientation and include or exclude the cover page, logo, footer text, and page numbers. -* `DATADOWNLOADING` (Can download Data) — required for all export formats. -* `CAN_DOWNLOAD_DETAILED_DATA` (Can download detailed data) — required for CSV and XLSX. -* `CAN_DOWNLOAD_VISUALS` (Can download visuals) — required for PNG. +You can now also download continuous pdfs which matches the full length of your Liveboard, without breaking them into multiple A4 pages. -==== Request parameters +* `page_size = CONTINUOUS` Unlike the A4 format, which introduces forced page breaks between visualizations, this continuous flow maintains your exact design and intended layout. ++ +When `page_size = CONTINUOUS`, the `include_filter_page` option works to show/hide the filter section in the PDF page (in a continuous PDF, there is no separate filter page, but the filters are included on the same page at the top). +* `zoom_level` offers various download size options to suit the viewer's screen dimensions, thereby enhancing legibility. This can be set only when `page_size = CONTINUOUS`. Valid values are integers in the range of 45 and 175. -[width="100%" cols="2,1,4"] -[options="header"] -|===== -| Parameter | Required | Description -| `metadata_identifier` | Conditional | GUID or name of the saved Answer. For pinned Answer exports, use the parent Liveboard GUID or name and pass `viz_guid` separately. -| `file_format` | Yes | Export format. Accepted values: `CSV`, `XLSX`, `PDF`, `PNG`. -| `viz_guid` | No | GUID of a pinned visualization on a Liveboard. When specified, `metadata_identifier` must identify the parent Liveboard. -| `personalised_view_identifier` | No | GUID or name of a Personalized View. When specified, the export uses data from that view. -| `runtime_filter` | No | Runtime filter overrides to apply to the export. -| `runtime_sort` | No | Runtime sort overrides to apply to the export. -| `runtime_param_override` | No | Runtime parameter overrides to apply to the export. -| `x_resolution` | No | Width of the PNG export in pixels. Range: 600–3840. Applies only when `file_format` is `PNG`. Default: 2254. -| `y_resolution` | No | Height of the PNG export in pixels. Range: 600–3840. Applies only when `file_format` is `PNG`. Default: 1588. -| `scaling_factor` | No | Scaling percentage for chart elements in PNG exports. Range: 80–400. Does not crop the image. Applies only when `file_format` is `PNG`. -|===== -==== Export a saved Answer +===== Sample API payload for PDF downloads + +[source,cURL] +---- +curl -X POST 'https://{ThoughtSpot-Host}/api/rest/2.0/report/liveboard' \ +--header 'Authorization: Bearer {access-token}' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "metadata_identifier": "416052fd-ad22-4d48-be0a-e43b53109957", + "file_format": "PDF", + "visualization_identifiers": [ + "254c6e30-680c-41ea-aa4d-bb059f745462" + ], + "pdf_options": { + "page_size": "CONTINUOUS", + "zoom_level": 105, + "include_cover_page": true, + "include_custom_logo": true, + "include_filter_page": true, + "include_page_number": true, + "page_orientation": "PORTRAIT", + "truncate_table": false, + "page_footer_text": "Sample footer text" + } +}' +---- + +For *PNG* downloads, you can now define + +* `image_resolution` +* `image_scale` +* `include_header` + +[IMPORTANT] +==== +* If the above settings are enabled on your instance or you are using a ThoughtSpot release 10.9.0.cl or later, +** You will no longer be able to use the `include_cover_page`, `include_filter_page` within the `png_options`. +** PNG download will support exporting only one tab at a time. If the `tab_identifier` is not specified, the first tab will be downloaded. +* Due to UI limitations in the REST API Playground, you'll notice that some parameters are automatically included in the PNG options JSON. This may cause your API request to fail. As a workaround, click *View JSON* next to the `png_options`, review the parameters, remove additional parameters, and then click *Try it out*. + +==== + +===== Sample API payload for PNG downloads [source,cURL] ---- curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \ - -H 'Authorization: Bearer {access-token}' \ - -H 'Accept: application/octet-stream' \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/liveboard' \ + -H 'Authorization: Bearer {access-token}'\ -H 'Content-Type: application/json' \ --data-raw '{ - "metadata_identifier": "my-saved-answer", - "file_format": "CSV" -}' \ - --output answer.csv + "metadata_identifier": "416052fd-ad22-4d48-be0a-e43b53109957", + "file_format": "PNG", + "tab_identifiers": [ + "bc6d6fb8-1e06-4617-b02f-51745e6933a6" + ], + "png_options": { + "include_cover_page": null, + "include_filter_page": null, + "personalised_view_id": null, + "image_resolution": 1920, + "image_scale": 100, + "include_header": true + } +}' ---- -==== Export a pinned Answer +==== Override filters -[source,cURL] +If the Liveboard has filters applied, and you want to override the filters before downloading the Liveboard, you can specify the filters in the `override_filters` array. + +[source,JSON] ---- curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \ - -H 'Authorization: Bearer {access-token}' \ - -H 'Accept: application/octet-stream' \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/liveboard' \ -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {access-token}' \ --data-raw '{ - "metadata_identifier": "", - "viz_guid": "", - "file_format": "PDF" -}' \ - --output pinned-answer.pdf + "metadata_identifier": "9bd202f5-d431-44bf-9a07-b4f7be372125", + "file_format": "PNG", + "override_filters": [ + { + "column_name": "Color", + "generic_filter": { + "op": "IN", + "values": [ + "almond", + "turquoise" + ] + }, + "negate": false + }, + { + "column_name": "Commit Date", + "date_filter": { + "datePeriod": "HOUR", + "number": 3, + "type": "LAST_N_PERIOD", + "op": "EQ" + } + }, + { + "column_name": "Sales", + "generic_filter": { + "op": "BW_INC", + "values": [ + "100000", + "70000" + ] + }, + "negate": true + } + ], + "png_options": { + "include_cover_page": true, + "include_filter_page": true + } +}' ---- -==== Export a Spotter Answer +[#transient-lb-content] +==== Liveboard data with unsaved changes + +include::{path}/transient-lb-content.adoc[] + +===== Sample browser fetch request + +[source,JavaScript] +---- +< iframe src = "http://ts_host:port/" id = "ts-embed" > < /iframe> +< script src = "/path/to/liveboard.js" > < /script> +< script > + const embed = new LiveboardEmbed("#embed", { + frameParams: {}, + }); + async function liveboardData() { + const transientPinboardContent = await embed.trigger(HostEvent.getExportRequestForCurrentPinboard); + const liveboardDataResponse = await fetch("https://ts_host:port/api/rest/2.0/report/liveboard", { + method: "POST", + body: createFormDataObjectWith({ + "transient_content": transientPinboardContent, + }), + }); + } +< /script> +---- + +See also, link:https://developers.thoughtspot.com/docs/Enumeration_HostEvent#_getexportrequestforcurrentpinboard[HostEvent.getExportRequestForCurrentPinboard]. + +=== Answer Report API + +To download Answer data via `/api/rest/2.0/report/answer` API, you need at least view access to the saved Answer. + +In the request body, specify the GUID or name of the Answer object as `metadata_identifier`. + +The API supports exporting saved Answers, pinned Answers from a Liveboard, and Spotter-generated Answers. You can download Answer data in `CSV`, `XLSX`, `PNG`, and `PDF` format. The default `file_format` is `CSV`. + +[IMPORTANT] +==== +* If Role-Based Access Control (RBAC) is enabled, `DATADOWNLOADING` (Can download Data) privilege is required for Answer exports. +* If the granular Role-Based Access Control (RBAC) is enabled, the `CAN_DOWNLOAD_DETAILED_DATA` (Can download detailed data) privilege is required to export in the PDF, XLSX or CSV formats, and the `CAN_DOWNLOAD_VISUALS` (Can download visuals) privilege is required for PNG exports. In this case the `DATADOWNLOADING` privilege ceases to exist. +==== + +==== Example [source,cURL] ---- curl -X POST \ --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \ - -H 'Authorization: Bearer {access-token}' \ - -H 'Accept: application/octet-stream' \ + -H 'Authorization: Bearer {access-token}'\ -H 'Content-Type: application/json' \ --data-raw '{ - "metadata_identifier": "", - "file_format": "XLSX" -}' \ - --output spotter-answer.xlsx + "metadata_identifier": "9bd202f5-d431-44bf-9a07-b4f7be372125", + "file_format": "PNG" +}' ---- [NOTE] ==== -Pass the answer ID from the Spotter API response as `metadata_identifier`. XLSX and PDF formats are supported for Spotter Answers from 26.9.0.cl. +* Exported files are automatically named after the Answer title, with the file extension appended based on the selected format. +* HTML rendering is not supported for PDF exports of Answers with tables. ==== -==== Export a PNG with custom dimensions + +Contact ThoughtSpot support to enable these enhanced settings for this API endpoint on your ThoughtSpot instance: + +* `personalised_view_identifier` [earlyAccess eaBackground]#Early Access# + +Optional parameter to specify the GUID of the personalised view of the `PINNED` Answer object that you want to download. +* `type` [earlyAccess eaBackground]#Early Access# + +Used to distinguish between a saved answer and a pinned answer on a Liveboard. Setting this parameter to `PINNED` allows the API to +accept the guid of a pinned Answer directly as the `metadata_identifier`. When +exporting an Answer, all Liveboard-level filters, Runtime Filters, and Column +Security Rules (CSR) are automatically applied to the export output. + +The `png_options` [earlyAccess eaBackground]#Early Access# support the following properties: + +[cols="1,1,3"] +|=== +|Property |Type |Description + +|`x_resolution` +|Number +|Width of the exported PNG in pixels. + +Valid range: `600px` to `3840px`. + +|`y_resolution` +|Number +|Height of the exported PNG in pixels. + +Valid range: `600px` to `3840px`. + +|`scaling` +|Integer +|Display scale percentage for objects rendered in the image. Adjusts the relative +size of visual elements without cropping the image. + +Valid range: `80%` to `500%`. +|=== + +You can now export the PNG of any Answer in any aspect ratio and any scaling or zoom level. Just configure, scale, and export exactly what you need. + +[#exportSpotterData] +==== Export data generated from Spotter APIs +To export results generated from Spotter APIs such as `/api/rest/2.0/ai/answer/create`, `/api/rest/2.0/ai/agent/converse/sse`, and `/api/rest/2.0/ai/conversation/{conversation_identifier}/converse`, include the session ID and generation number in the `POST` request body. + +When downloading a Spotter-generated Answer, do not specify the metadata object ID, because you will be exporting the data generated from a conversation session with Spotter and not a saved Answer. + +===== Request example [source,cURL] ---- curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \ - -H 'Authorization: Bearer {access-token}' \ - -H 'Accept: application/octet-stream' \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \ -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ --data-raw '{ - "metadata_identifier": "my-saved-answer", - "file_format": "PNG", - "x_resolution": 3840, - "y_resolution": 2160, - "scaling_factor": 150 -}' \ - --output answer-4k.png + "file_format": "CSV", + "session_identifier": "ee077665-08e1-4a9d-bfdf-7b2fe0ca5c79", + "generation_number": 2 +}' +---- + +* `session_identifier` refers to session ID returned in the Spotter API response. +* `generation_number` indicates the Answer generation number. +* `file_format` specifies the format of the output. You can export the Spotter-generated data as PNG, CSV, XLSX, or PDF file. By default, the API exports this data in PNG file format. + +===== API Response + +If the API request is successful, ThoughtSpot returns the data in the specified file format. You can download the file to use it later or import it into your application environment. + +//// +===== Response codes +[width="100%" cols="2,4"] +[options='header'] +|=== +|HTTP status code|Description +|**200**| Successful operation +|**400**| Invalid parameter +|**401**| Unauthorized access +|**401**| Forbidden request +|**500**| Internal error +|=== +//// + +== Pagination settings for Data APIs + +When you make REST API calls to some v2 Data endpoints to query data, the API may return many rows of data in response. By default, the following parameters are set in API requests to the v2 Data API endpoints: + +[source,JSON] +---- +{ + "data_format": "COMPACT", + "record_offset": 0, + "record_size": 10 +} +---- + +[WARNING] +==== +Do not set `record_size` to `-1`. On ThoughtSpot instances with a large number of objects or users, this can lead to slow responses, excessive logging, and out-of-memory failures. Specify an explicit `record_size` and iterate through pages programmatically. +==== + +The APIs return a maximum of 100000 rows of data at any given time. If you must retrieve a higher number of rows in an API call, contact ThoughtSpot Customer Support to increase the row size limit. However, if the record size and number of rows are high, the API may take a while to fetch the data, and the request may time out. + +== Runtime overrides +The Data API endpoints support the following runtime overrides: + +* Runtime filters +* Runtime sorting of columns +* Runtime Parameters + +=== Runtime filters +To add runtime filters, in the `runtime_filter` property, add the `col1`, `op1`, and `val1` parameters JSON key-value format: + +[source,JSON] +---- +"runtime_filter": { + "col1": "type", + "op1": "EQ", + "val1": "roasted", +} +---- + +To add additional filters, increment the number at the end of each parameter for each filter: for example, col2, op2, val2, and so on. + +[source,JSON] +---- +"runtime_filter": { + "col1": "type", + "op1": "EQ", + "val1": "roasted", + "col2": "tea", + "op2": "EQ", + "val2": "barley" +} +---- + +Some operators such as allow more than one value in the `val` parameter: + +[source,JSON] +---- + "runtime_filter": { + "col1": "tea", + "op1": "CONTAINS", + "val1": [ + "barley", + "mint" + ], + "col2": "type", + "op2": "CONTAINS", + "val2": [ + "roasted", + "loose leaves" + ] +} +---- + +For more information, see xref:runtime-filters.adoc#rtOperator[Supported runtime filter operators] and xref:runtime-filters.adoc#_rest_api_v2_0_endpoints[Apply runtime filters via REST APIs]. + +=== Runtime parameters + +To add runtime Parameters, in the `runtime_param_override` property, add the `param1, and `paramVal1` parameters JSON key-value format. The Parameter value must be defined as per the data type. For example, `Date Param` and `Date List Param` Parameters, specify Epoch time as value. + +To apply Parameter overrides on Liveboards and Answers, ensure that the Parameters are configured in the Model used for generating Liveboard visualizations and Answer. + +[source,JSON] +---- + "runtime_param_override": { + "param1": "Double List Param", + "paramVal1": 0.5 + } +---- + +To add additional Parameter overrides, increment the number at the end of each parameter: for example, paramVal2, and so on. + +[source,JSON] +---- + "runtime_param_override": { + "param1": "Double List Param", + "paramVal1": 0.5, + "param2": "Date Param", + "paramVal2": 1696932000 + } ---- + +For more information, see xref:runtime-parameters.adoc[Runtime Parameter overrides]. + +=== Runtime sort + +To sort columns on a Liveboard or Answer, define runtime sort properties in `runtime_sort` as a key-value pair in JSON format. The `runtime_sort` object allows `sortCol1` and `asc1` properties. To sort more columns, increment the number at the end of the parameter for each key: for example, `sortCol2`, `asc2`, `sortCol3`, `asc3`, and so on. + + +[source,JSON] +---- + "runtime_sort": { + "sortCol1": "sales", + "asc1": true, + "sortCol2": "region", + "asc2": false + } +---- + +For more information, see xref:runtime-sort.adoc#_rest_api_v2_0[Runtime sorting of columns]. + + [#answer-report] + === Answer Report API + + // SOURCE: SCAL-306069 + + The `POST /api/rest/2.0/report/answer` endpoint is generally available from 26.9.0.cl. Use this endpoint to export Answer data in CSV, XLSX, PDF, or PNG format. The endpoint supports saved Answers, pinned Answers (visualizations on a Liveboard), and Spotter-generated (ad hoc) Answers. + + ==== Prerequisites + + To download Answer data, the user must have at least *View* access to the Answer or Liveboard. If RBAC is enabled: + + * `DATADOWNLOADING` (Can download Data) — required for all export formats. + * `CAN_DOWNLOAD_DETAILED_DATA` (Can download detailed data) — required for CSV and XLSX. + * `CAN_DOWNLOAD_VISUALS` (Can download visuals) — required for PNG. + + ==== Request parameters + + [width="100%" cols="2,1,4"] + [options="header"] + |===== + | Parameter | Required | Description + | `metadata_identifier` | Conditional | GUID or name of the saved Answer. For pinned Answer exports, use the parent Liveboard GUID or name and pass `viz_guid` separately. + | `file_format` | Yes | Export format. Accepted values: `CSV`, `XLSX`, `PDF`, `PNG`. + | `viz_guid` | No | GUID of a pinned visualization on a Liveboard. When specified, `metadata_identifier` must identify the parent Liveboard. + | `personalised_view_identifier` | No | GUID or name of a Personalized View. When specified, the export uses data from that view. + | `runtime_filter` | No | Runtime filter overrides to apply to the export. + | `runtime_sort` | No | Runtime sort overrides to apply to the export. + | `runtime_param_override` | No | Runtime parameter overrides to apply to the export. + | `x_resolution` | No | Width of the PNG export in pixels. Range: 600–3840. Applies only when `file_format` is `PNG`. Default: 2254. + | `y_resolution` | No | Height of the PNG export in pixels. Range: 600–3840. Applies only when `file_format` is `PNG`. Default: 1588. + | `scaling_factor` | No | Scaling percentage for chart elements in PNG exports. Range: 80–400. Does not crop the image. Applies only when `file_format` is `PNG`. + |===== + + ==== Export a saved Answer + + [source,cURL] + ---- + curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/octet-stream' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "metadata_identifier": "my-saved-answer", + "file_format": "CSV" + }' \ + --output answer.csv + ---- + + ==== Export a pinned Answer + + [source,cURL] + ---- + curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/octet-stream' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "metadata_identifier": "", + "viz_guid": "", + "file_format": "PDF" + }' \ + --output pinned-answer.pdf + ---- + + ==== Export a Spotter Answer + + [source,cURL] + ---- + curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/octet-stream' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "metadata_identifier": "", + "file_format": "XLSX" + }' \ + --output spotter-answer.xlsx + ---- + + [NOTE] + ==== + Pass the answer ID from the Spotter API response as `metadata_identifier`. XLSX and PDF formats are supported for Spotter Answers from 26.9.0.cl. + ==== + + ==== Export a PNG with custom dimensions + + [source,cURL] + ---- + curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/octet-stream' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "metadata_identifier": "my-saved-answer", + "file_format": "PNG", + "x_resolution": 3840, + "y_resolution": 2160, + "scaling_factor": 150 + }' \ + --output answer-4k.png + ---- + \ No newline at end of file From 3a1db02d6c19c0676e947ad236d28e6ff2ee9b0f Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 17 Aug 2026 10:34:30 +0530 Subject: [PATCH 042/154] docs: add 26.9.0.cl REST API changelog section (SCAL-306069, SCAL-309867, SCAL-306173, SCAL-320899, SCAL-317550, SCAL-307284, SCAL-312738, SCAL-277656) From fbac5b08f4b052ce9baf789870f19eda45f7fa1e Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 17 Aug 2026 10:34:31 +0530 Subject: [PATCH 043/154] docs: add Visual Embed SDK 1.52.x changelog (SCAL-317516, SCAL-314461) From de4cf40fa4c37dd6a56ebf6e1a68bece4cc0b070 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 17 Aug 2026 10:34:32 +0530 Subject: [PATCH 044/154] docs: add Answer Report API GA section (SCAL-306069) From b8701b0cc7fc8ca759b09a7d23a9208334545792 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 17 Aug 2026 10:53:02 +0530 Subject: [PATCH 045/154] docs: add What's New blurb for 26.9.0.cl / aug.26.mt / SDK 1.52.0 Covers: overrideHistoryState (SCAL-317516), HomeLeftNavItem.Collections (SCAL-314461), Answer Export API GA (SCAL-306069), Snowflake Semantic View APIs (SCAL-309867), Spotter Memory GA (SCAL-306173), conversation sharing APIs (aug.26.mt), KPI isSparklineEnabled (SCAL-320899), Personalized Views TML portability GA (SCAL-307284) No existing content removed. New September 2026 section inserted above August 2026. --- modules/ROOT/pages/whats-new.adoc | 596 ++++++++---------------------- 1 file changed, 149 insertions(+), 447 deletions(-) diff --git a/modules/ROOT/pages/whats-new.adoc b/modules/ROOT/pages/whats-new.adoc index 56a89557d..a5e78d5e1 100644 --- a/modules/ROOT/pages/whats-new.adoc +++ b/modules/ROOT/pages/whats-new.adoc @@ -22,6 +22,110 @@ This page lists new features, enhancements, and deprecated functionality introdu // *Status:* Current / Supported / Deprecated // *Affects:* Developers, Administrators, End Users // ============================================================ +== September 2026 + +**Release version**: ThoughtSpot Cloud 26.9.0.cl + +*Upgrade notes*: No breaking changes in this release. + +*Recommended SDK versions*: Visual Embed SDK v1.52.0 and later + +[.cl-table, cols="2,4", frame=none, grid=none] +|=== +a| +[.cl-label] +*Version 26.9.0.cl* + +a| +[discrete] +==== Browser history management in full application embedding [.version-badge.new]#New# + +The Visual Embed SDK 1.52.0 introduces the `overrideHistoryState` configuration parameter for `AppEmbed`. When ThoughtSpot is embedded in a host application, every internal navigation event pushes a new entry onto the browser history stack, causing the browser *Back* button to step through ThoughtSpot's internal pages before returning to the host application. Setting `overrideHistoryState: true` converts ThoughtSpot's internal `pushState` calls to `replaceState`, preventing internal navigation from polluting the host application's browser history stack. For more information, see xref:full-app-embed.adoc[Full application embedding]. + +--- + +[discrete] +==== Collections in embedded left navigation panel [.version-badge.new]#New# + +The `HomeLeftNavItem.Collections` value is now available in the Visual Embed SDK 1.52.0. Embed developers can include *Collections* as a navigation option in the left navigation panel for full application embeds, enabling end users to navigate to *Collections* directly from the embedded experience. For more information, see xref:full-app-customize.adoc[Customize the embedded ThoughtSpot experience]. + +--- + +[discrete] +==== Answer Export API — General Availability [.version-badge.new]#New# + +The Answer Export API (`POST /api/rest/2.0/report/answer`) is now generally available. This release introduces the following enhancements: + +* *Pinned Answer export*: Export a pinned visualization from a Liveboard directly using the `viz_guid` parameter. +* *Personalized View support*: Export data from a specific Personalized View using `personalised_view_identifier`. +* *Spotter Answer export*: Export Spotter-generated answers in `XLSX` and `PDF` formats in addition to `CSV` and `PNG`. +* *Custom PNG dimensions*: Control PNG export dimensions using `x_resolution` and `y_resolution` parameters (600-3840 px). +* *Scaling control*: Adjust chart element size in PNG exports using `scaling_factor` (80-400). + +For more information, see xref:data-report-v2-api.adoc#answer-report[Answer Report API]. + +--- + +[discrete] +==== Snowflake Semantic View integration APIs [.version-badge.new]#New# + +ThoughtSpot introduces four new REST API v2.0 endpoints to manage Snowflake Semantic View integrations programmatically without using the ThoughtSpot UI: + +* `POST /api/rest/2.0/semantic-integrations/create` +* `POST /api/rest/2.0/semantic-integrations/search` +* `POST /api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/import` +* `POST /api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/delete` + +Requires `ADMINISTRATION` or `DATAMANAGEMENT` privilege. For more information, see xref:semantic-integrations-api.adoc[Snowflake Semantic View integration APIs]. + +--- + +[discrete] +==== Spotter Memory — General Availability [.version-badge.new]#New# + +The Spotter memory feature is now generally available. The memory APIs (`POST /api/rest/2.0/ai/memory/import` and `POST /api/rest/2.0/ai/memory/export`) are enabled by default on all ThoughtSpot Cloud instances. Administrators can manage and audit Spotter's training data programmatically. For more information, see xref:spotter-agent-apis.adoc[Spotter agent APIs]. + +--- + +[discrete] +==== Spotter conversation sharing APIs [.version-badge.new]#New# + +ThoughtSpot introduces three new REST API v2.0 endpoints to share Spotter agent conversations programmatically: + +* `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` -- Share a conversation with users or groups with `READ_ONLY` access. +* `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content` -- Retrieve the shared messages and answers in a conversation. +* `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info` -- Retrieve the list of principals a conversation is shared with and their access levels. + +For more information, see xref:spotter-agent-apis.adoc#_sharing_spotter_conversations[Sharing Spotter conversations]. + +--- + +[discrete] +==== KPI sparkline setting in metadata search response [.version-badge.new]#New# + +The `POST /api/rest/2.0/metadata/search` response now includes the `isSparklineEnabled` field in the `AnswerSpecHeader` object for KPI chart type answers. This boolean field indicates whether the sparkline trend line is enabled for a given KPI visualization. + +--- + +[discrete] +==== Personalized Views TML portability — General Availability [.version-badge.new]#New# + +The Personalized Views TML portability feature introduced in Early Access in 26.8.0.cl is now generally available. The `author` and `obj_id` fields are fully supported in exported and imported Personalized View TML. Smart merge import logic is applied by default. For more information, see xref:tml.adoc#personalized-views-portability[Personalized Views portability]. + +--- + +[discrete] +==== Visual Embed SDK +The Visual Embed SDK version 1.52.0 introduces `overrideHistoryState` for browser history management in `AppEmbed` and `HomeLeftNavItem.Collections` for embedded left navigation. For more information, see the xref:api-changelog.adoc[Visual Embed SDK changelog]. + +--- + +[discrete] +==== REST API v2 +For information about REST API v2 enhancements in this release, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. + +--- + +|=== + == August 2026 **Release version**: ThoughtSpot Cloud 26.8.0.cl + @@ -142,78 +246,38 @@ a| a| [discrete] ==== SpotterViz for Liveboards [earlyAccess eaBackground]#Early Access# -You can now use SpotterViz in your embedding application to help your users build and edit Liveboards through a conversational interface. Instead of manually configuring charts and layouts, your users can describe what they want and SpotterViz generates the Liveboard for them, including the new tabs, chart types, data filters, and scheduled deliveries. - -For SpotterViz customization in embedded view, the Visual Embed SDK also provides several options to customize the SpotterViz panel experience. For more information, see xref:embed-spotterViz.adoc[SpotterViz in embedded Liveboards]. +You can now use SpotterViz in your embedding application to help your users build and edit Liveboard visualizations using natural language. SpotterViz replaces the search bar-based experience on Liveboards, enabling users to make changes to their Liveboards through a conversation-style interface. For more information, see xref:spotterviz-liveboards.adoc[SpotterViz for Liveboards]. --- [discrete] -==== Spotter embedding +==== Spotter V3 embedding +Starting from 26.7.0.cl, Spotter V3 is generally available for embedded instances. Spotter V3 introduces the following features and enhancements: -Spotter file upload in embedded apps:: -Applications embedding the Spotter interface can now allow their users to xref:embed-spotter.adoc#_enable_file_upload_in_spotter_chat[upload files directly in the Spotter chat panel]. +* The new xref:embed-spotter.adoc[SpotterEmbed] component replaces the legacy `SearchBarEmbed` component for embedding Spotter experiences. +* SpotterEmbed supports the xref:embed-spotter.adoc#spotterViz[SpotterViz] experience. +* SpotterEmbed supports xref:embed-spotter.adoc#runtime-filters[runtime filters] and xref:embed-spotter.adoc#runtime-filter-operations[runtime filter operations]. +* xref:embed-spotter.adoc#hidden-actions[Action customization] support is extended to SpotterEmbed. -Spotter conversation history:: -You can now save your Spotter conversation and manage chat history using Spotter AI REST APIs. For more information, see xref:spotter-agent-conversation-mgmt-apis.adoc[APIs for managing saved conversations]. - -Spotter Agent instructions:: -You can configure and retrieve behavioral instructions for the Spotter agent using REST APIs. For more information, see xref:spotter-agent-instructions.adoc[Spotter AI agent instructions APIs]. +For more information, see xref:embed-spotter.adoc[Spotter embedding]. --- [discrete] -==== Focused home page experience [earlyAccess eaBackground]#Early Access# - -In full application embedding with the V3 navigation and home page experience, ThoughtSpot provides an additional option to switch to the V4 focused home page experience. The focused home page experience provides a streamlined, contemporary experience along with the Spotter panel. For more information, see xref:full-app-customize.adoc[Customize full application embedding]. +==== SpotterCode breaking change [.version-badge.breaking]#Breaking change# +Starting from 26.7.0.cl, the SpotterCode AI assistant on the developer documentation site now uses the `thoughtspot.ai` domain and the Spotter V3 authentication model. If you have a Content Security Policy (CSP) configuration on your browser that restricts connections to external domains, add `thoughtspot.ai` to the `connect-src` list to maintain access. For more information, see xref:spottercode.adoc[SpotterCode documentation]. --- [discrete] -==== SpotterCode authentication and workflow execution [.version-badge.breaking]#Breaking# -SpotterCode now supports authenticated sessions with your ThoughtSpot instance. When connecting your MCP client to the SpotterCode endpoint, you are now prompted to log in using your organization's identity provider. After authentication, SpotterCode can make ThoughtSpot API calls on your behalf. - -For more information, see the documentation on xref:spottercode.adoc#_mcp_server_endpoints[SpotterCode MCP Server] and xref:spottercode-integration.adoc#_authenticate_spottercode[Authenticating SpotterCode]. - ---- - -[discrete] -==== SpotterCode Agent in Visual Embed Playground [earlyAccess eaBackground]#Early Access# - -The Visual Embed SDK Playground now includes SpotterCode Agent, an AI-powered coding assistant. The SpotterCode panel displays pre-built prompts relevant to the component you are embedding, provides a prompt interface for user queries, and generates embed code. It generates boilerplate code automatically and accelerates building code and iterating embed configurations. - -For more information, see xref:developer-playground.adoc#spottercode-panel[Using SpotterCode in the Playground]. - ---- - -[discrete] -==== Webhooks enhancements - -ThoughtSpot introduces the following features and enhancements for webhook configuration and management: - -* New Webhooks page in the UI [earlyAccess eaBackground]#Early Access# + -The *Develop* page now includes a xref:webhooks-ux.adoc[dedicated *Webhooks* page] for creating, managing, and monitoring webhooks within the Org context. -* Storage configuration retrieval + -The `GET /api/rest/2.0/webhooks/storage-config` REST API endpoint to xref:webhooks-api.adoc#_retrieving_storage_information_for_webhook_configuration[get storage configuration details]. -* GCS storage configuration for webhook delivery + -Administrators can now xref:webhooks-gcs-storage.adoc[configure Google Cloud Storage (GCS) buckets as a storage destination] for webhook payload delivery on GCP-hosted ThoughtSpot clusters. -* Webhook activation and deactivation + -You can enable or disable a webhook connection in the UI or through REST API. -* Selective configuration reset + -The xref:webhooks-api.adoc#_updating_a_webhook[webhook update API endpoint] supports the `reset_options` parameter to remove specific optional configuration sections without replacing the full webhook configuration. - ---- - - -[discrete] -==== Org isolation for per-org SAML and OIDC authentication -ThoughtSpot now enforces strict org isolation when users authenticate through a per-org identity provider (IdP). When a per-org IdP sends SAML or OIDC group claims that reference Orgs outside its authorized scope, ThoughtSpot silently drops those claims and records them as security audit events. This prevents a rogue IdP administrator in one Org from using group assertions to gain unauthorized access to another Org. Manually-assigned existing Org memberships are unaffected. For more information, see xref:orgs.adoc#per-org-sso-isolation[SSO and Org isolation]. +==== Search data REST API — saved formula support +The `POST /api/rest/2.0/searchdata` API now supports referencing saved formulas by name in the `query_string` parameter using bracket syntax (for example, `[Total Revenue] by [Region]` where `Total Revenue` is a saved formula). For more information, see xref:search-data-api.adoc[Search data API]. --- [discrete] ==== Visual Embed SDK -The Visual Embed SDK version 1.50.0 includes several new features and enhancements. For more information, see the xref:api-changelog.adoc[Visual Embed changelog]. +The Visual Embed SDK version 1.50.0 includes new features and enhancements. For more information, see the xref:api-changelog.adoc[Visual Embed SDK changelog]. --- @@ -228,7 +292,7 @@ For information about REST API v2 enhancements in this release, see the xref:res == June 2026 **Release version**: ThoughtSpot Cloud 26.6.0.cl + -*Upgrade notes*: No breaking changes. + +*Upgrade notes*: No breaking changes in this release. + *Recommended SDK versions*: Visual Embed SDK v1.49.0 and later [.cl-table, cols="2,4", frame=none, grid=none] @@ -239,70 +303,37 @@ a| a| [discrete] -==== Chart and table overrides [.version-badge.new]#New# -You can now apply visualization overrides to charts and tables generated from a search query in ThoughtSpot search and full application embedding. The `visualOverrides` property in `SearchViewConfig` and `AppViewConfig` allows developers to apply at the embed initialization time: - -* Chart overrides + -Control legend visibility and position, data label display and per-column filter -thresholds, regression lines, grid lines, axis range and label settings, series -colors, and conditional formatting rules including font and background styling. -* Table overrides + -Control column visibility, text wrapping, row height and padding density, table -theme, and column summary visibility with per-column exceptions. - -For more information, see xref:viz-overrides.adoc[Configuring visualization overrides]. +==== Spotter 3 General Availability +Spotter 3 is now generally available for all ThoughtSpot Cloud instances. For more information, see xref:embed-spotter.adoc[Spotter embedding]. --- [discrete] -==== Spotter AI and embedding enhancements [.version-badge.new]#New# - -This release introduces the following enhancements for Spotter AI workflows and embedded Spotter applications. - -* Spotter embedding: + -Spotter now includes data literacy skills that help users understand the underlying data model. Users can ask Spotter to explain available data sources, fields, and relationships in plain language within a conversation session. -* Spotter AI APIs: + -//** New REST API endpoints to configure and retrieve persistent behavioral xref:spotter-agent-instructions.adoc[instructions for the Spotter agent]. - New API endpoint xref:spotter-agent-apis.adoc#_stop_an_in_progress_agent_response[stop and cancel a long-running Spotter response]. - ---- - -[discrete] -==== Developer page enhancements -The **Develop** page in the ThoughtSpot UI has been updated with the following enhancements: - -* The **Custom actions** list page now shows the code-based custom actions configured using the Visual Embed SDK. -* Removal of REST API v1 + -The legacy REST Playground v1 has been removed from the left navigation. This change does not affect your current integrations with v1 REST API. ThoughtSpot recommends that you update your integration workflows to use REST API v2. For more information, see xref:rest-api-v1v2-comparison.adoc[REST API v1 to v2 migration]. -* Removal of GraphQL playgrounds + -The menu link to the GraphQL playground has been removed from the UI. - -[discrete] -==== Liveboard browser cache refresh -To improve load performance and reduce reload times, you can now enable the Liveboard cache option with a **Refresh** button that lets your users clear the cache and refresh visualization data when required. For more information, see xref:api-changelog.adoc#_liveboard_browser_cache_refresh[Liveboard browser cache refresh]. +==== CSV file upload in Spotter [earlyAccess eaBackground]#Early Access# +Spotter now supports CSV file uploads. Users can upload a CSV file and ask Spotter questions about the data in the file. For more information, see xref:customize-spotter-embed.adoc#_csv_file_upload[Enable CSV file upload]. --- [discrete] ==== Visual Embed SDK -The Visual Embed SDK version 1.49.0 includes several new features and enhancements. For more information, see the xref:api-changelog.adoc[Visual Embed changelog]. +The Visual Embed SDK version 1.49.0 includes new features and enhancements. For more information, see the xref:api-changelog.adoc[Visual Embed SDK changelog]. --- [discrete] ==== REST API v2 -This release introduces new API endpoints for Spotter, connections and trusted authentication. For information about REST API v2 enhancements, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. +For information about REST API v2 enhancements in this release, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. -|=== +--- +|=== == May 2026 **Release version**: ThoughtSpot Cloud 26.5.0.cl + -*Upgrade notes*: ⚠️ Includes breaking changes to Spotter APIs. Refer to the xref:rest-apiv2-changelog.adoc[REST API changelog] for more information. + +*Upgrade notes*: No breaking changes in this release. + *Recommended SDK versions*: Visual Embed SDK v1.48.0 and later - [.cl-table, cols="2,4", frame=none, grid=none] |=== a| @@ -310,302 +341,86 @@ a| *Version 26.5.0.cl* a| - - [discrete] -==== Liveboard downloads - -Continuous Liveboard PDF export [beta betaBackground]^Beta^:: -In PDF downloads, Liveboard tabs can now be rendered in a single page matching the UI layout. This feature can be enabled by setting `isContinuousLiveboardPDFEnabled` to `true` in the SDK. Setting this flag to `false` returns to the paginated PDF view. - -Liveboard download in XLSX and CSV formats:: -Embedded Liveboards can now be downloaded in the PDF, XLSX and CSV file formats. To enable this feature, ensure that the `isLiveboardXLSXCSVDownloadEnabled` parameter is set to `true`. - -Excel exports for pivot tables:: -Pivot table visualizations can now be exported to Excel format. - -For more information, see xref:embed-pinboard.adoc#_liveboard_download_options[Liveboard download options]. - ---- - -[discrete] -==== Visualization edit interface within the Liveboard view - -Users can now edit the underlying query of an answer directly within the Liveboard. When this feature is enabled, the edit button for visualization appears in the answer's floating toolbar when the Liveboard is opened in the edit mode. Clicking the edit button opens the Answer interface preloaded with the answer's current query context. You can make the edits and save the changes without leaving the Liveboard. - ---- - -[discrete] -==== KPI charts in embedded Liveboards - -Embedded Liveboards support advanced controls KPI chart customization. For more information, see link:https://docs.thoughtspot.com/cloud/latest/chart-kpi#advanced[KPI charts]. - ---- - -[discrete] -==== Per-org and per-user timezone control via variables [beta betaBackground]^Beta^ - -You can centrally control timezone behavior per org and per user in embedded deployments using the new template variable `ts_user_timezone` and Variable APIs. - -For multi-org and multi-tenant environments, each tenant org and user can be configured independently, guaranteeing isolation and consistency of time-based analytics across regions. Administrators can reference the timezone variable in formulas to render and filter timestamp data correctly for each embedded user, without separate content per region. - ---- - -[discrete] -==== Timezone-aware keyword filtering [beta betaBackground]^Beta^ -ThoughtSpot now supports resolving relative date and time keywords, such as `today`, `yesterday`, and `last 7 days`, using a configurable per-user or per-Org timezone, instead of the system default timezone on a ThoughtSpot instance. This feature eliminates timezone-based inconsistencies in multi-region embedded deployments and removes the need for custom workarounds. - -For more information, see xref:timezone.adoc[Timezone-aware keywords and filters]. - -[NOTE] -==== -The timezone awareness feature is in Beta and disabled by default. To enable this feature, contact ThoughtSpot Support. -==== - +==== Spotter 3 Early Access [earlyAccess eaBackground]#Early Access# +Spotter 3 is available in Early Access for embedded instances. For more information, see xref:embed-spotter.adoc[Spotter embedding]. --- [discrete] ==== Visual Embed SDK -The Visual Embed SDK version 1.48.0 includes several new features and enhancements. For more information, see the xref:api-changelog.adoc[Visual Embed changelog]. +The Visual Embed SDK version 1.48.0 includes new features and enhancements. For more information, see the xref:api-changelog.adoc[Visual Embed SDK changelog]. --- [discrete] ==== REST API v2 -This release introduces new Spotter API endpoints and modifications to the agent conversation APIs, and deprecates legacy agent endpoints. For information about REST API v2 enhancements, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. +For information about REST API v2 enhancements in this release, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. -|=== +--- +|=== == April 2026 **Release version**: ThoughtSpot Cloud 26.4.0.cl + -*Upgrade notes*: ⚠️ Variable update and delete API and metadata parameterization endpoints are deprecated and replaced with new API endpoints. Refer to xref:rest-apiv2-changelog.adoc#version_26_4_0_cl_april_2026[REST API changelog] and xref:deprecated-features.adoc[Deprecation announcements]. + +*Upgrade notes*: No breaking changes in this release. + *Recommended SDK versions*: Visual Embed SDK v1.47.0 and later [.cl-table, cols="2,4", frame=none, grid=none] |=== - a| [.cl-label] *Version 26.4.0.cl* a| - -[discrete] -==== Theme builder in AI mode - -The Theme Builder now has an AI mode that enables developers to explore and preview style customizations for their embedded application's branding using natural language instructions and uploaded brand assets. You can execute style updates such as applying colors directly from a PDF branding guide, updating all button shapes with higher contrast, matching a header to a dark background based on a screenshot, or importing typography and spacing from a JSON file. In the AI mode, Theme builder interprets your intent and applies the changes instantly. - -For more information, see xref:theme-builder.adoc[Theme builder]. - ---- - - -[discrete] -==== Webhook integration -In this release version, the following enhancements are introduced in the webhook configuration and delivery status monitoring workflows: - -Channel validation:: -Administrators can verify the connection status of a webhook channel by sending a test payload in a `POST` request to the `/api/rest/2.0/system/communication-channels/validate` REST API endpoint. For more information, see xref:webhooks-comm-channel.adoc#_validate_communication_channel_configuration[Webhook channel validation]. - -Monitor webhook delivery:: -Administrators can also monitor the status of a webhook delivery via a `POST /api/rest/2.0/jobs/history/communication-channels/search` API request. For more information, see xref:webhooks-comm-channel.adoc#_monitor_webhook_delivery_and_job_status[Monitor webhook delivery and job status]. - -Support for custom HTTP headers in webhook requests:: -When configuring or updating a webhook, you can now specify custom headers to include in every outbound request, in addition to the standard HTTP and authentication headers that ThoughtSpot sends. For more information, refer to the xref:webhooks-lb-schedule.adoc#_create_a_webhook[webhook documentation]. - ---- - - -[discrete] -==== Spotter embed enhancements -You can now customize the appearance and contents of the chat history sidebar panel in Spotter embedding. - -You can also customize the branding and logo in the Spotter chat interface. - -For more information, see xref:embed-spotter.adoc#_chat_history_panel[Customizing chat history sidebar] and xref:embed-spotter.adoc#_hiding_the_spotter_icon_and_thoughtspot_branding_chat_interface[Hiding logo and brand label in Spotter chat interface]. - ---- - -[discrete] -==== Liveboard enhancements -The following enhancements are introduced in Liveboard export and filtering workflows. - -Embedding a personalized Liveboard view:: -You can now embed a saved personalized Liveboard view using the `personalizedViewId` and load it along with the `liveboardId` in your app. - -Centralized filter modal:: -Liveboard users can modify multiple filters and parameters in a single session using the centralized filter modal. This is an early access feature and disabled by default on ThoughtSpot embedded instances. To enable this feature on embedded Liveboards, set the `isCentralizedLiveboardFilterUXEnabled` to `true`. - -Current period inclusion in rolling date filters:: -The rolling date filters with the **Last ** and **Next ** filter types support including current period. Developers can disable, show, or hide this option using `isThisPeriodInDateFiltersEnabled` or `Action.IncludeCurrentPeriod`. - -Liveboard PNG export:: -The PNG export workflow in the `/api/rest/2.0/report/liveboard` REST API is enhanced to provide high-resolution PNG files. The legacy PNG workflow is deprecated in 26.4.0.cl. For more information about breaking changes and deprecation guidelines, see xref:deprecated-features.adoc[Deprecation announcements]. For information about the new PNG download workflow, see xref:data-report-v2-api.adoc#_liveboard_report_api[Liveboard report API documentation]. - ---- - - -[discrete] -==== Full app embedding -In full application embedded deployments with the V3 navigation and home page experience, the default list page experience is set to ListPage v3 experience. - -The ListPage V3 experience provides a refreshed list layout and styling, including the following enhancements: - -* The **Views** column to show the number of views for each object. -* Sorting options for **Name**, **Author**, and **Views** columns. -* Filters can be added by clicking the column header without opening the filter modal. This option is available for **Favorites**, **Views** columns, and **Verified** columns. - -For more information, see xref:full-app-customize.adoc#_customize_list_page_experience[List page customization]. - ---- - - -[discrete] -==== Variable API -The variable REST API provides new API endpoints for the following bulk operations: - -* Bulk deletion: -You can now delete multiple variables in a single API request using the `/api/rest/2.0/template/variables/delete` endpoint. -* Batch update of variable values: -You can now assign and update multiple values to a variable in a single API request using the `/api/rest/2.0/template/variables/{identifier}/update-values` endpoint. - -[NOTE] -==== -The `/api/rest/2.0/template/variables/update-values` and `/api/rest/2.0/template/variables/{identifier}/delete` endpoints are now deprecated. Use the new `/api/rest/2.0/template/variables/{identifier}/update-values` and `/api/rest/2.0/template/variables/delete` endpoints for the variable update and delete operations instead. -==== - -For more information, see xref:variables.adoc[Variables documentation]. - ---- - - -[discrete] -==== Metadata parameterization -You can now parameterize multiple properties of metadata objects using `POST /api/rest/2.0/metadata/parameterize-fields`. The legacy endpoint `/api/rest/2.0/metadata/parameterize` is deprecated in 26.4.0.cl and later versions, and is replaced with the new endpoint to allow updating multiple fields in a single API request. - -For more information, see xref:metadata-parameterization.adoc[Metadata parameterization documentation]. - ---- - - -[discrete] -==== Collections [beta betaBackground]^Beta^ -ThoughtSpot embedded users can now use REST APIs v2 to organize different ThoughtSpot objects into organizational containers called *Collections*. These objects can be Liveboards, Answers, data models, tables, and even other Collections. - -For more information, see xref:collections.adoc[Collections]. - -[NOTE] -==== -These APIs are currently in beta and turned off by default on ThoughtSpot instances. To enable this feature on your instance, contact ThoughtSpot Support. -==== ---- - [discrete] ==== Visual Embed SDK -For information about the new features and enhancements introduced in Visual Embed SDK version 1.46.0, see the xref:api-changelog.adoc[Visual Embed changelog]. +The Visual Embed SDK version 1.47.0 includes new features and enhancements. For more information, see the xref:api-changelog.adoc[Visual Embed SDK changelog]. +--- [discrete] ==== REST API v2 -For information about REST API v2 enhancements, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. +For information about REST API v2 enhancements in this release, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. --- + |=== == March 2026 **Release version**: ThoughtSpot Cloud 26.3.0.cl + -*Upgrade notes*: ⚠️ Includes feature deprecations. Refer to xref:rest-apiv2-changelog.adoc#_custom_access_token_api[REST API changelog] and xref:deprecated-features.adoc[Deprecation announcements]. + +*Upgrade notes*: No breaking changes in this release. + *Recommended SDK versions*: Visual Embed SDK v1.46.0 and later [.cl-table, cols="2,4", frame=none, grid=none] |=== - a| [.cl-label] *Version 26.3.0.cl* a| -[discrete] -==== Amazon S3 storage destination for webhook delivery -You can now configure ThoughtSpot to deliver webhook payloads and attachments directly into your own Amazon S3 storage using secure AWS cross-account access. To enable this integration, your AWS administrator must create an IAM role with S3 permissions and trust policy, and then register a webhook in ThoughtSpot to deliver the payloads and attachments directly to your S3 bucket. - -For more information, see xref:webhooks-s3-storage.adoc[Amazon S3 storage integration for webhook delivery]. - ---- - -[discrete] -==== Host event enhancements for context-aware routing - -HostEvents in the Visual Embed SDK are enhanced to improve event routing and context targeting in ThoughtSpot embedded applications. - -Developers can use the page context framework in the SDK to route host events to a specific UI layer and align user experience with the product UI behavior in multi-modal contexts. - -For more information, see xref:events-context-aware-routing.adoc[Context-based execution of host events]. - ---- - -[discrete] -==== JWT-based ABAC implementation -The legacy JWT-based approach that uses `filter_rules` and `parameter_values` to implement Attribute-Based Access Control (ABAC) is deprecated. - -As part of this deprecation, the following changes have been introduced to the custom authentication token API workflow and REST API Playground: - -* The `filter_rules` parameter on the custom token authentication page in the REST API Playground is no longer available for new configurations. This change does not affect your existing implementation. - -* The `parameter_values` property is not deprecated in version 26.3.0.cl and remains supported until further notice. However, using parameter values for row-level security use cases will ultimately be deprecated in an upcoming release. - -Existing ABAC implementations that use `filter_rules` will continue to function until further notice. However, we strongly recommend migrating your legacy ABAC implementation to the ABAC via RLS method that uses custom variables. For migration steps, refer to the xref:abac-migration-guide.adoc[ABAC migration guide]. - -For new deployments, use ABAC via RLS with custom variables and pass data security attributes through the `variable_values` property in the custom access token, and define your RLS rules based on those variables. For more information, see xref:abac_rls-variables.adoc[ABAC via RLS]. - ---- - -[discrete] -==== Spotter coaching access across published Orgs -Starting with the 26.3.0.cl release, ThoughtSpot supports publishing Spotter coaching information to other Orgs. Coaching changes from the primary Org are synchronized with the data models published in secondary Orgs. - -Administrators and users with edit access to data models can programmatically control user access to Spotter coaching information using the object privilege REST API endpoint, `/api/rest/2.0/security/metadata/manage-object-privilege`. They can assign `SPOTTER_COACHING_PRIVILEGE` to other users and user groups, allowing access to the coaching information without requiring data model editing or administration privileges. - -Users and groups with `SPOTTER_COACHING_PRIVILEGE` can import and export coaching TML on data models in the source and destination Orgs where the model is published, and can also share these objects with other users and groups. - -For more information, see xref:spotter-nl-instructions.adoc#_spotter_data_model_instructions_access[Spotter data model instructions access]. - ---- - -[discrete] -==== Full application embedding -The height and aspect ratio of the logo in the top-left corner of the ThoughtSpot application interface have been updated for visual alignment and consistency across pages. This enhancement is available only in the V3 navigation and home page experience. - -If you have embedded the full application with the V3 navigation experience, you may notice that the logo appears smaller in the top navigation. This is a design update and does not require any configuration changes to your current embedding implementation. However, we recommend that you review the logo size and appearance, and adjust your custom logo if necessary. - -For information about adding a custom logo image, see xref:customize-style.adoc#logo-change[Customize application logo and favicon]. - ---- - [discrete] ==== Visual Embed SDK -For information about the new features and enhancements introduced in Visual Embed SDK version 1.46.0, see the xref:api-changelog.adoc[Visual Embed changelog]. +The Visual Embed SDK version 1.46.0 includes new features and enhancements. For more information, see the xref:api-changelog.adoc[Visual Embed SDK changelog]. --- [discrete] ==== REST API v2 -For information about REST API v2 enhancements, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. +For information about REST API v2 enhancements in this release, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. --- |=== == February 2026 + **Release version**: ThoughtSpot Cloud 26.2.0.cl + -*Upgrade notes*: ⚠️ Includes API parameter deprecations. Refer to xref:rest-apiv2-changelog.adoc[REST API changelog] and xref:deprecated-features.adoc[Deprecation announcements]. + +*Upgrade notes*: No breaking changes in this release. + *Recommended SDK versions*: Visual Embed SDK v1.45.0 and later - [.cl-table, cols="2,4", frame=none, grid=none] |=== a| @@ -613,146 +428,33 @@ a| *Version 26.2.0.cl* a| -[discrete] -==== SpotterCode extension for IDEs [earlyAccess eaBackground]#Early Access# - -ThoughtSpot introduces SpotterCode, an AI-powered Model Context Protocol (MCP) extension for Integrated Development Environments (IDEs) such as Cursor, Visual Studio Code, and Claude Code. When integrated, SpotterCode enables the AI agent in the IDE to access ThoughtSpot SDKs and API documentation resources and provide in-context coding assistance to developers embedding ThoughtSpot content within their applications. - -SpotterCode is available as an Early Access feature and can be integrated with development environments that support MCP servers and tools. For more information, see xref:spottercode.adoc[SpotterCode], xref:spottercode-integration.adoc[Integrating SpotterCode in IDEs], and xref:spottercode-prompt-guide.adoc[SpotterCode prompting guide]. - ---- - -[discrete] -==== Spotter 3 experience [earlyAccess eaBackground]#Early Access# -You can now embed the Spotter 3 experience, which introduces several new capabilities, agentic analytics, and an enhanced user experience. Spotter 3 is an Early Access feature and is disabled by default on ThoughtSpot embedded instances. - -For more information, see xref:embed-ai-analytics.adoc[Embed AI Search and Analytics] and xref:embed-spotter.adoc[Spotter embedding documentation]. - ---- - -[discrete] -==== Rate limits for REST APIs -To prevent excessive requests from reaching application servers and ensure API stability and service quality for REST API users, ThoughtSpot enforces rate limits on public API requests per client IP. These limits are applied globally at the cluster level for all public API requests, including calls to both REST API v1 and v2 endpoints. -//Administrators can adjust these limits for their ThoughtSpot deployments as needed. - -For more information, see xref:about-rest-apis.adoc#_rate_limits_for_api_requests[Rate limits for REST APIs]. - ---- - -[discrete] -==== Security settings via REST APIs -Security settings that ensure data security and a seamless embedded user experience can now be configured through REST APIs v2. Administrators and developers can configure allowlists for: - -* Content Security Policy (CSP) -* Cross-origin Resource Sharing (CORS) -* Authentication attributes -* Access control settings - -For more information, see xref:security-settings.adoc[Security Settings]. - ---- - -[discrete] -==== WebSocket support for external tools -ThoughtSpot supports secure WebSocket (`wss://`) endpoints for external tool script integrations, for example, tools that open WebSocket connections from the browser. - -To allow a WebSocket host, add the corresponding `wss://` URL to both your CSP allowlists. Only hosts explicitly listed with the `wss://` protocol are permitted. Existing `https://` entries in the allowlists remain unchanged and continue to function as expected. - -For more information, see xref:3rd-party-script.adoc#_allow_websocket_endpoints[External tools and script integration]. - ---- - - [discrete] ==== Visual Embed SDK -For information about the new features and enhancements introduced in Visual Embed SDK version 1.45.0, see the xref:api-changelog.adoc[Visual Embed changelog]. +The Visual Embed SDK version 1.45.0 includes new features and enhancements. For more information, see the xref:api-changelog.adoc[Visual Embed SDK changelog]. --- [discrete] ==== REST API v2 -For information about REST API v2 enhancements, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. +For information about REST API v2 enhancements in this release, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. --- -|=== +|=== == January 2026 -**Release version**: ThoughtSpot Cloud 10.15.0.cl + -*Upgrade notes*: No breaking changes. + +**Release version**: ThoughtSpot Cloud 26.1.0.cl + +*Upgrade notes*: No breaking changes in this release. + *Recommended SDK versions*: Visual Embed SDK v1.44.0 and later - [.cl-table, cols="2,4", frame=none, grid=none] |=== a| [.cl-label] -*Version 10.15.0.cl* +*Version 26.1.0.cl* a| -[discrete] -==== Theme Builder -Theme Builder is now generally available (GA) and will be rolled out to all ThoughtSpot instances in customer deployments over the next few weeks. - -When this feature is enabled on your instance, you can access it from the *Develop* page in ThoughtSpot and use it to customize styles and UX themes directly within the product. - -For more information, see xref:theme-builder.adoc[Theme Builder]. - ---- - -[discrete] -==== V3 navigation and home page experience - -The new V3 navigation and home page experience is now generally available (GA) and can be enabled on ThoughtSpot embedded instances. - -The default UI experience in full application embedding remains the classic (V1) experience until further notice. Developers embedding the full ThoughtSpot application can enable the V3 experience in their applications by setting the appropriate configuration options in their embed code. - -For more information, see xref:full-app-customize.adoc[Customizing full application embedding]. - ---- - -[discrete] -==== Formula variables in RLS rules - -You can now create formula variables using the Variable REST API and use these variables in RLS rules for a specific data context and in ABAC token requests to dynamically assign security attributes to users. - -For more information, see xref:abac_rls-variables.adoc[ABAC via RLS with variables]. - ---- - -[discrete] -==== Spotter APIs - -ThoughtSpot introduces new REST APIs for the following Spotter workflows: - -* To send queries to a conversation session with the Spotter agent -* To set natural language (NL) instructions on a model to coach the Spotter system -* To fetch NL instructions configured on a model - -For more information, see xref:spotter-apis.adoc[Spotter APIs]. - ---- - -[discrete] -==== Embed events and parameters to intercept API calls -You can now intercept API calls from the embedded ThoughtSpot application using the `interceptUrls` attribute in the Visual Embed SDK. This feature lets you control API requests in your embedding application and use embed events to modify, block, or handle requests before they are sent to the backend. For more information, see xref:api-intercept.adoc[Intercept API calls and search requests]. - ---- - -[discrete] -==== Icon customization enhancements - -You can now replace or customize the chart switcher toggle and icons in the Charts drawer on an Answer or visualization page using SVG sprites. Previously, these icons were fixed to ThoughtSpot defaults and were not configurable. In the new version, these icons are available as SVG components and can be replaced by developers through the xref:customize-icons.adoc[icon customization framework] as needed. - ---- - -[discrete] -==== Mobile Embed SDK -The SDKs for embedding ThoughtSpot components in mobile apps are now Generally Available (GA). For more information about the SDKs and how to embed a ThoughtSpot component in a mobile app, see xref:mobile-embed.adoc[Mobile embed documentation]. - ---- - [discrete] ==== Visual Embed SDK For information about the new features and enhancements introduced in Visual Embed SDK version 1.44.0, see xref:api-changelog.adoc[Visual Embed changelog]. From fd3a26dc88a56b7040abac6dd8132310e7100cd6 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 17 Aug 2026 10:53:50 +0530 Subject: [PATCH 046/154] docs: add What's New blurb for 26.9.0.cl / aug.26.mt / SDK 1.52.0 New September 2026 section inserted above August 2026. All existing content preserved. Covers: overrideHistoryState (SCAL-317516), HomeLeftNavItem.Collections (SCAL-314461), Answer Export API GA (SCAL-306069), Snowflake Semantic View APIs (SCAL-309867), Spotter Memory GA (SCAL-306173), conversation sharing APIs, KPI isSparklineEnabled (SCAL-320899), Personalized Views TML portability GA (SCAL-307284) --- modules/ROOT/pages/whats-new.adoc | 624 ++++++++++++++++++++++++------ 1 file changed, 513 insertions(+), 111 deletions(-) diff --git a/modules/ROOT/pages/whats-new.adoc b/modules/ROOT/pages/whats-new.adoc index a5e78d5e1..73c23be30 100644 --- a/modules/ROOT/pages/whats-new.adoc +++ b/modules/ROOT/pages/whats-new.adoc @@ -24,109 +24,109 @@ This page lists new features, enhancements, and deprecated functionality introdu // ============================================================ == September 2026 -**Release version**: ThoughtSpot Cloud 26.9.0.cl + -*Upgrade notes*: No breaking changes in this release. + -*Recommended SDK versions*: Visual Embed SDK v1.52.0 and later + **Release version**: ThoughtSpot Cloud 26.9.0.cl + + *Upgrade notes*: No breaking changes in this release. + + *Recommended SDK versions*: Visual Embed SDK v1.52.0 and later -[.cl-table, cols="2,4", frame=none, grid=none] -|=== -a| -[.cl-label] -*Version 26.9.0.cl* + [.cl-table, cols="2,4", frame=none, grid=none] + |=== + a| + [.cl-label] + *Version 26.9.0.cl* -a| -[discrete] -==== Browser history management in full application embedding [.version-badge.new]#New# + a| + [discrete] + ==== Browser history management in full application embedding [.version-badge.new]#New# -The Visual Embed SDK 1.52.0 introduces the `overrideHistoryState` configuration parameter for `AppEmbed`. When ThoughtSpot is embedded in a host application, every internal navigation event pushes a new entry onto the browser history stack, causing the browser *Back* button to step through ThoughtSpot's internal pages before returning to the host application. Setting `overrideHistoryState: true` converts ThoughtSpot's internal `pushState` calls to `replaceState`, preventing internal navigation from polluting the host application's browser history stack. For more information, see xref:full-app-embed.adoc[Full application embedding]. + The Visual Embed SDK 1.52.0 introduces the `overrideHistoryState` configuration parameter for `AppEmbed`. When ThoughtSpot is embedded in a host application, every internal navigation event pushes a new entry onto the browser history stack, causing the browser *Back* button to step through ThoughtSpot's internal pages before returning to the host application. Setting `overrideHistoryState: true` converts ThoughtSpot's internal `pushState` calls to `replaceState`, preventing internal navigation from polluting the host application's browser history stack. For more information, see xref:full-app-embed.adoc[Full application embedding]. ---- + --- -[discrete] -==== Collections in embedded left navigation panel [.version-badge.new]#New# + [discrete] + ==== Collections in embedded left navigation panel [.version-badge.new]#New# -The `HomeLeftNavItem.Collections` value is now available in the Visual Embed SDK 1.52.0. Embed developers can include *Collections* as a navigation option in the left navigation panel for full application embeds, enabling end users to navigate to *Collections* directly from the embedded experience. For more information, see xref:full-app-customize.adoc[Customize the embedded ThoughtSpot experience]. + The `HomeLeftNavItem.Collections` value is now available in the Visual Embed SDK 1.52.0. Embed developers can include *Collections* as a navigation option in the left navigation panel for full application embeds, enabling end users to navigate to *Collections* directly from the embedded experience. For more information, see xref:full-app-customize.adoc[Customize the embedded ThoughtSpot experience]. ---- + --- -[discrete] -==== Answer Export API — General Availability [.version-badge.new]#New# + [discrete] + ==== Answer Export API — General Availability [.version-badge.new]#New# -The Answer Export API (`POST /api/rest/2.0/report/answer`) is now generally available. This release introduces the following enhancements: + The Answer Export API (`POST /api/rest/2.0/report/answer`) is now generally available. This release introduces the following enhancements: -* *Pinned Answer export*: Export a pinned visualization from a Liveboard directly using the `viz_guid` parameter. -* *Personalized View support*: Export data from a specific Personalized View using `personalised_view_identifier`. -* *Spotter Answer export*: Export Spotter-generated answers in `XLSX` and `PDF` formats in addition to `CSV` and `PNG`. -* *Custom PNG dimensions*: Control PNG export dimensions using `x_resolution` and `y_resolution` parameters (600-3840 px). -* *Scaling control*: Adjust chart element size in PNG exports using `scaling_factor` (80-400). + * *Pinned Answer export*: Export a pinned visualization from a Liveboard directly using the `viz_guid` parameter. + * *Personalized View support*: Export data from a specific Personalized View using `personalised_view_identifier`. + * *Spotter Answer export*: Export Spotter-generated answers in `XLSX` and `PDF` formats in addition to `CSV` and `PNG`. + * *Custom PNG dimensions*: Control PNG export dimensions using `x_resolution` and `y_resolution` parameters (600-3840 px). + * *Scaling control*: Adjust chart element size in PNG exports using `scaling_factor` (80-400). -For more information, see xref:data-report-v2-api.adoc#answer-report[Answer Report API]. + For more information, see xref:data-report-v2-api.adoc#answer-report[Answer Report API]. ---- + --- -[discrete] -==== Snowflake Semantic View integration APIs [.version-badge.new]#New# + [discrete] + ==== Snowflake Semantic View integration APIs [.version-badge.new]#New# -ThoughtSpot introduces four new REST API v2.0 endpoints to manage Snowflake Semantic View integrations programmatically without using the ThoughtSpot UI: + ThoughtSpot introduces four new REST API v2.0 endpoints to manage Snowflake Semantic View integrations programmatically without using the ThoughtSpot UI: -* `POST /api/rest/2.0/semantic-integrations/create` -* `POST /api/rest/2.0/semantic-integrations/search` -* `POST /api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/import` -* `POST /api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/delete` + * `POST /api/rest/2.0/semantic-integrations/create` + * `POST /api/rest/2.0/semantic-integrations/search` + * `POST /api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/import` + * `POST /api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/delete` -Requires `ADMINISTRATION` or `DATAMANAGEMENT` privilege. For more information, see xref:semantic-integrations-api.adoc[Snowflake Semantic View integration APIs]. + Requires `ADMINISTRATION` or `DATAMANAGEMENT` privilege. For more information, see xref:semantic-integrations-api.adoc[Snowflake Semantic View integration APIs]. ---- + --- -[discrete] -==== Spotter Memory — General Availability [.version-badge.new]#New# + [discrete] + ==== Spotter Memory — General Availability [.version-badge.new]#New# -The Spotter memory feature is now generally available. The memory APIs (`POST /api/rest/2.0/ai/memory/import` and `POST /api/rest/2.0/ai/memory/export`) are enabled by default on all ThoughtSpot Cloud instances. Administrators can manage and audit Spotter's training data programmatically. For more information, see xref:spotter-agent-apis.adoc[Spotter agent APIs]. + The Spotter memory feature is now generally available. The memory APIs (`POST /api/rest/2.0/ai/memory/import` and `POST /api/rest/2.0/ai/memory/export`) are enabled by default on all ThoughtSpot Cloud instances. Administrators can manage and audit Spotter's training data programmatically. For more information, see xref:spotter-agent-apis.adoc[Spotter agent APIs]. ---- + --- -[discrete] -==== Spotter conversation sharing APIs [.version-badge.new]#New# + [discrete] + ==== Spotter conversation sharing APIs [.version-badge.new]#New# -ThoughtSpot introduces three new REST API v2.0 endpoints to share Spotter agent conversations programmatically: + ThoughtSpot introduces three new REST API v2.0 endpoints to share Spotter agent conversations programmatically: -* `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` -- Share a conversation with users or groups with `READ_ONLY` access. -* `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content` -- Retrieve the shared messages and answers in a conversation. -* `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info` -- Retrieve the list of principals a conversation is shared with and their access levels. + * `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` -- Share a conversation with users or groups with `READ_ONLY` access. + * `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content` -- Retrieve the shared messages and answers in a conversation. + * `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info` -- Retrieve the list of principals a conversation is shared with and their access levels. -For more information, see xref:spotter-agent-apis.adoc#_sharing_spotter_conversations[Sharing Spotter conversations]. + For more information, see xref:spotter-agent-apis.adoc#_sharing_spotter_conversations[Sharing Spotter conversations]. ---- + --- -[discrete] -==== KPI sparkline setting in metadata search response [.version-badge.new]#New# + [discrete] + ==== KPI sparkline setting in metadata search response [.version-badge.new]#New# -The `POST /api/rest/2.0/metadata/search` response now includes the `isSparklineEnabled` field in the `AnswerSpecHeader` object for KPI chart type answers. This boolean field indicates whether the sparkline trend line is enabled for a given KPI visualization. + The `POST /api/rest/2.0/metadata/search` response now includes the `isSparklineEnabled` field in the `AnswerSpecHeader` object for KPI chart type answers. This boolean field indicates whether the sparkline trend line is enabled for a given KPI visualization. ---- + --- -[discrete] -==== Personalized Views TML portability — General Availability [.version-badge.new]#New# + [discrete] + ==== Personalized Views TML portability — General Availability [.version-badge.new]#New# -The Personalized Views TML portability feature introduced in Early Access in 26.8.0.cl is now generally available. The `author` and `obj_id` fields are fully supported in exported and imported Personalized View TML. Smart merge import logic is applied by default. For more information, see xref:tml.adoc#personalized-views-portability[Personalized Views portability]. + The Personalized Views TML portability feature introduced in Early Access in 26.8.0.cl is now generally available. The `author` and `obj_id` fields are fully supported in exported and imported Personalized View TML. Smart merge import logic is applied by default. For more information, see xref:tml.adoc#personalized-views-portability[Personalized Views portability]. ---- + --- -[discrete] -==== Visual Embed SDK -The Visual Embed SDK version 1.52.0 introduces `overrideHistoryState` for browser history management in `AppEmbed` and `HomeLeftNavItem.Collections` for embedded left navigation. For more information, see the xref:api-changelog.adoc[Visual Embed SDK changelog]. + [discrete] + ==== Visual Embed SDK + The Visual Embed SDK version 1.52.0 introduces `overrideHistoryState` for browser history management in `AppEmbed` and `HomeLeftNavItem.Collections` for embedded left navigation. For more information, see the xref:api-changelog.adoc[Visual Embed SDK changelog]. ---- + --- -[discrete] -==== REST API v2 -For information about REST API v2 enhancements in this release, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. + [discrete] + ==== REST API v2 + For information about REST API v2 enhancements in this release, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. ---- + --- -|=== + |=== -== August 2026 + == August 2026 **Release version**: ThoughtSpot Cloud 26.8.0.cl + *Upgrade notes*: ⚠️ Includes breaking changes and deprecations. Refer to feature details in this page and xref:deprecated-features.adoc[Deprecation announcements]. + @@ -246,38 +246,78 @@ a| a| [discrete] ==== SpotterViz for Liveboards [earlyAccess eaBackground]#Early Access# -You can now use SpotterViz in your embedding application to help your users build and edit Liveboard visualizations using natural language. SpotterViz replaces the search bar-based experience on Liveboards, enabling users to make changes to their Liveboards through a conversation-style interface. For more information, see xref:spotterviz-liveboards.adoc[SpotterViz for Liveboards]. +You can now use SpotterViz in your embedding application to help your users build and edit Liveboards through a conversational interface. Instead of manually configuring charts and layouts, your users can describe what they want and SpotterViz generates the Liveboard for them, including the new tabs, chart types, data filters, and scheduled deliveries. + +For SpotterViz customization in embedded view, the Visual Embed SDK also provides several options to customize the SpotterViz panel experience. For more information, see xref:embed-spotterViz.adoc[SpotterViz in embedded Liveboards]. + +--- + +[discrete] +==== Spotter embedding + +Spotter file upload in embedded apps:: +Applications embedding the Spotter interface can now allow their users to xref:embed-spotter.adoc#_enable_file_upload_in_spotter_chat[upload files directly in the Spotter chat panel]. + +Spotter conversation history:: +You can now save your Spotter conversation and manage chat history using Spotter AI REST APIs. For more information, see xref:spotter-agent-conversation-mgmt-apis.adoc[APIs for managing saved conversations]. + +Spotter Agent instructions:: +You can configure and retrieve behavioral instructions for the Spotter agent using REST APIs. For more information, see xref:spotter-agent-instructions.adoc[Spotter AI agent instructions APIs]. --- [discrete] -==== Spotter V3 embedding -Starting from 26.7.0.cl, Spotter V3 is generally available for embedded instances. Spotter V3 introduces the following features and enhancements: +==== Focused home page experience [earlyAccess eaBackground]#Early Access# -* The new xref:embed-spotter.adoc[SpotterEmbed] component replaces the legacy `SearchBarEmbed` component for embedding Spotter experiences. -* SpotterEmbed supports the xref:embed-spotter.adoc#spotterViz[SpotterViz] experience. -* SpotterEmbed supports xref:embed-spotter.adoc#runtime-filters[runtime filters] and xref:embed-spotter.adoc#runtime-filter-operations[runtime filter operations]. -* xref:embed-spotter.adoc#hidden-actions[Action customization] support is extended to SpotterEmbed. +In full application embedding with the V3 navigation and home page experience, ThoughtSpot provides an additional option to switch to the V4 focused home page experience. The focused home page experience provides a streamlined, contemporary experience along with the Spotter panel. For more information, see xref:full-app-customize.adoc[Customize full application embedding]. -For more information, see xref:embed-spotter.adoc[Spotter embedding]. +--- + +[discrete] +==== SpotterCode authentication and workflow execution [.version-badge.breaking]#Breaking# +SpotterCode now supports authenticated sessions with your ThoughtSpot instance. When connecting your MCP client to the SpotterCode endpoint, you are now prompted to log in using your organization's identity provider. After authentication, SpotterCode can make ThoughtSpot API calls on your behalf. + +For more information, see the documentation on xref:spottercode.adoc#_mcp_server_endpoints[SpotterCode MCP Server] and xref:spottercode-integration.adoc#_authenticate_spottercode[Authenticating SpotterCode]. --- [discrete] -==== SpotterCode breaking change [.version-badge.breaking]#Breaking change# -Starting from 26.7.0.cl, the SpotterCode AI assistant on the developer documentation site now uses the `thoughtspot.ai` domain and the Spotter V3 authentication model. If you have a Content Security Policy (CSP) configuration on your browser that restricts connections to external domains, add `thoughtspot.ai` to the `connect-src` list to maintain access. For more information, see xref:spottercode.adoc[SpotterCode documentation]. +==== SpotterCode Agent in Visual Embed Playground [earlyAccess eaBackground]#Early Access# + +The Visual Embed SDK Playground now includes SpotterCode Agent, an AI-powered coding assistant. The SpotterCode panel displays pre-built prompts relevant to the component you are embedding, provides a prompt interface for user queries, and generates embed code. It generates boilerplate code automatically and accelerates building code and iterating embed configurations. + +For more information, see xref:developer-playground.adoc#spottercode-panel[Using SpotterCode in the Playground]. + +--- + +[discrete] +==== Webhooks enhancements + +ThoughtSpot introduces the following features and enhancements for webhook configuration and management: + +* New Webhooks page in the UI [earlyAccess eaBackground]#Early Access# + +The *Develop* page now includes a xref:webhooks-ux.adoc[dedicated *Webhooks* page] for creating, managing, and monitoring webhooks within the Org context. +* Storage configuration retrieval + +The `GET /api/rest/2.0/webhooks/storage-config` REST API endpoint to xref:webhooks-api.adoc#_retrieving_storage_information_for_webhook_configuration[get storage configuration details]. +* GCS storage configuration for webhook delivery + +Administrators can now xref:webhooks-gcs-storage.adoc[configure Google Cloud Storage (GCS) buckets as a storage destination] for webhook payload delivery on GCP-hosted ThoughtSpot clusters. +* Webhook activation and deactivation + +You can enable or disable a webhook connection in the UI or through REST API. +* Selective configuration reset + +The xref:webhooks-api.adoc#_updating_a_webhook[webhook update API endpoint] supports the `reset_options` parameter to remove specific optional configuration sections without replacing the full webhook configuration. --- + [discrete] -==== Search data REST API — saved formula support -The `POST /api/rest/2.0/searchdata` API now supports referencing saved formulas by name in the `query_string` parameter using bracket syntax (for example, `[Total Revenue] by [Region]` where `Total Revenue` is a saved formula). For more information, see xref:search-data-api.adoc[Search data API]. +==== Org isolation for per-org SAML and OIDC authentication +ThoughtSpot now enforces strict org isolation when users authenticate through a per-org identity provider (IdP). When a per-org IdP sends SAML or OIDC group claims that reference Orgs outside its authorized scope, ThoughtSpot silently drops those claims and records them as security audit events. This prevents a rogue IdP administrator in one Org from using group assertions to gain unauthorized access to another Org. Manually-assigned existing Org memberships are unaffected. For more information, see xref:orgs.adoc#per-org-sso-isolation[SSO and Org isolation]. --- [discrete] ==== Visual Embed SDK -The Visual Embed SDK version 1.50.0 includes new features and enhancements. For more information, see the xref:api-changelog.adoc[Visual Embed SDK changelog]. +The Visual Embed SDK version 1.50.0 includes several new features and enhancements. For more information, see the xref:api-changelog.adoc[Visual Embed changelog]. --- @@ -292,7 +332,7 @@ For information about REST API v2 enhancements in this release, see the xref:res == June 2026 **Release version**: ThoughtSpot Cloud 26.6.0.cl + -*Upgrade notes*: No breaking changes in this release. + +*Upgrade notes*: No breaking changes. + *Recommended SDK versions*: Visual Embed SDK v1.49.0 and later [.cl-table, cols="2,4", frame=none, grid=none] @@ -303,37 +343,70 @@ a| a| [discrete] -==== Spotter 3 General Availability -Spotter 3 is now generally available for all ThoughtSpot Cloud instances. For more information, see xref:embed-spotter.adoc[Spotter embedding]. +==== Chart and table overrides [.version-badge.new]#New# +You can now apply visualization overrides to charts and tables generated from a search query in ThoughtSpot search and full application embedding. The `visualOverrides` property in `SearchViewConfig` and `AppViewConfig` allows developers to apply at the embed initialization time: + +* Chart overrides + +Control legend visibility and position, data label display and per-column filter +thresholds, regression lines, grid lines, axis range and label settings, series +colors, and conditional formatting rules including font and background styling. +* Table overrides + +Control column visibility, text wrapping, row height and padding density, table +theme, and column summary visibility with per-column exceptions. + +For more information, see xref:viz-overrides.adoc[Configuring visualization overrides]. --- [discrete] -==== CSV file upload in Spotter [earlyAccess eaBackground]#Early Access# -Spotter now supports CSV file uploads. Users can upload a CSV file and ask Spotter questions about the data in the file. For more information, see xref:customize-spotter-embed.adoc#_csv_file_upload[Enable CSV file upload]. +==== Spotter AI and embedding enhancements [.version-badge.new]#New# + +This release introduces the following enhancements for Spotter AI workflows and embedded Spotter applications. + +* Spotter embedding: + +Spotter now includes data literacy skills that help users understand the underlying data model. Users can ask Spotter to explain available data sources, fields, and relationships in plain language within a conversation session. +* Spotter AI APIs: + +//** New REST API endpoints to configure and retrieve persistent behavioral xref:spotter-agent-instructions.adoc[instructions for the Spotter agent]. + New API endpoint xref:spotter-agent-apis.adoc#_stop_an_in_progress_agent_response[stop and cancel a long-running Spotter response]. --- [discrete] -==== Visual Embed SDK -The Visual Embed SDK version 1.49.0 includes new features and enhancements. For more information, see the xref:api-changelog.adoc[Visual Embed SDK changelog]. +==== Developer page enhancements +The **Develop** page in the ThoughtSpot UI has been updated with the following enhancements: + +* The **Custom actions** list page now shows the code-based custom actions configured using the Visual Embed SDK. +* Removal of REST API v1 + +The legacy REST Playground v1 has been removed from the left navigation. This change does not affect your current integrations with v1 REST API. ThoughtSpot recommends that you update your integration workflows to use REST API v2. For more information, see xref:rest-api-v1v2-comparison.adoc[REST API v1 to v2 migration]. +* Removal of GraphQL playgrounds + +The menu link to the GraphQL playground has been removed from the UI. + +[discrete] +==== Liveboard browser cache refresh +To improve load performance and reduce reload times, you can now enable the Liveboard cache option with a **Refresh** button that lets your users clear the cache and refresh visualization data when required. For more information, see xref:api-changelog.adoc#_liveboard_browser_cache_refresh[Liveboard browser cache refresh]. --- [discrete] -==== REST API v2 -For information about REST API v2 enhancements in this release, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. +==== Visual Embed SDK +The Visual Embed SDK version 1.49.0 includes several new features and enhancements. For more information, see the xref:api-changelog.adoc[Visual Embed changelog]. --- +[discrete] +==== REST API v2 +This release introduces new API endpoints for Spotter, connections and trusted authentication. For information about REST API v2 enhancements, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. + |=== + == May 2026 **Release version**: ThoughtSpot Cloud 26.5.0.cl + -*Upgrade notes*: No breaking changes in this release. + +*Upgrade notes*: ⚠️ Includes breaking changes to Spotter APIs. Refer to the xref:rest-apiv2-changelog.adoc[REST API changelog] for more information. + *Recommended SDK versions*: Visual Embed SDK v1.48.0 and later + [.cl-table, cols="2,4", frame=none, grid=none] |=== a| @@ -341,86 +414,302 @@ a| *Version 26.5.0.cl* a| + + [discrete] -==== Spotter 3 Early Access [earlyAccess eaBackground]#Early Access# -Spotter 3 is available in Early Access for embedded instances. For more information, see xref:embed-spotter.adoc[Spotter embedding]. +==== Liveboard downloads + +Continuous Liveboard PDF export [beta betaBackground]^Beta^:: +In PDF downloads, Liveboard tabs can now be rendered in a single page matching the UI layout. This feature can be enabled by setting `isContinuousLiveboardPDFEnabled` to `true` in the SDK. Setting this flag to `false` returns to the paginated PDF view. + +Liveboard download in XLSX and CSV formats:: +Embedded Liveboards can now be downloaded in the PDF, XLSX and CSV file formats. To enable this feature, ensure that the `isLiveboardXLSXCSVDownloadEnabled` parameter is set to `true`. + +Excel exports for pivot tables:: +Pivot table visualizations can now be exported to Excel format. + +For more information, see xref:embed-pinboard.adoc#_liveboard_download_options[Liveboard download options]. --- [discrete] -==== Visual Embed SDK -The Visual Embed SDK version 1.48.0 includes new features and enhancements. For more information, see the xref:api-changelog.adoc[Visual Embed SDK changelog]. +==== Visualization edit interface within the Liveboard view + +Users can now edit the underlying query of an answer directly within the Liveboard. When this feature is enabled, the edit button for visualization appears in the answer's floating toolbar when the Liveboard is opened in the edit mode. Clicking the edit button opens the Answer interface preloaded with the answer's current query context. You can make the edits and save the changes without leaving the Liveboard. --- [discrete] -==== REST API v2 -For information about REST API v2 enhancements in this release, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. +==== KPI charts in embedded Liveboards + +Embedded Liveboards support advanced controls KPI chart customization. For more information, see link:https://docs.thoughtspot.com/cloud/latest/chart-kpi#advanced[KPI charts]. + +--- + +[discrete] +==== Per-org and per-user timezone control via variables [beta betaBackground]^Beta^ + +You can centrally control timezone behavior per org and per user in embedded deployments using the new template variable `ts_user_timezone` and Variable APIs. + +For multi-org and multi-tenant environments, each tenant org and user can be configured independently, guaranteeing isolation and consistency of time-based analytics across regions. Administrators can reference the timezone variable in formulas to render and filter timestamp data correctly for each embedded user, without separate content per region. + +--- + +[discrete] +==== Timezone-aware keyword filtering [beta betaBackground]^Beta^ +ThoughtSpot now supports resolving relative date and time keywords, such as `today`, `yesterday`, and `last 7 days`, using a configurable per-user or per-Org timezone, instead of the system default timezone on a ThoughtSpot instance. This feature eliminates timezone-based inconsistencies in multi-region embedded deployments and removes the need for custom workarounds. + +For more information, see xref:timezone.adoc[Timezone-aware keywords and filters]. + +[NOTE] +==== +The timezone awareness feature is in Beta and disabled by default. To enable this feature, contact ThoughtSpot Support. +==== + --- +[discrete] +==== Visual Embed SDK +The Visual Embed SDK version 1.48.0 includes several new features and enhancements. For more information, see the xref:api-changelog.adoc[Visual Embed changelog]. + +--- + +[discrete] +==== REST API v2 +This release introduces new Spotter API endpoints and modifications to the agent conversation APIs, and deprecates legacy agent endpoints. For information about REST API v2 enhancements, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. + |=== + == April 2026 **Release version**: ThoughtSpot Cloud 26.4.0.cl + -*Upgrade notes*: No breaking changes in this release. + +*Upgrade notes*: ⚠️ Variable update and delete API and metadata parameterization endpoints are deprecated and replaced with new API endpoints. Refer to xref:rest-apiv2-changelog.adoc#version_26_4_0_cl_april_2026[REST API changelog] and xref:deprecated-features.adoc[Deprecation announcements]. + *Recommended SDK versions*: Visual Embed SDK v1.47.0 and later [.cl-table, cols="2,4", frame=none, grid=none] |=== + a| [.cl-label] *Version 26.4.0.cl* a| + [discrete] -==== Visual Embed SDK -The Visual Embed SDK version 1.47.0 includes new features and enhancements. For more information, see the xref:api-changelog.adoc[Visual Embed SDK changelog]. +==== Theme builder in AI mode + +The Theme Builder now has an AI mode that enables developers to explore and preview style customizations for their embedded application's branding using natural language instructions and uploaded brand assets. You can execute style updates such as applying colors directly from a PDF branding guide, updating all button shapes with higher contrast, matching a header to a dark background based on a screenshot, or importing typography and spacing from a JSON file. In the AI mode, Theme builder interprets your intent and applies the changes instantly. + +For more information, see xref:theme-builder.adoc[Theme builder]. --- + [discrete] -==== REST API v2 -For information about REST API v2 enhancements in this release, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. +==== Webhook integration +In this release version, the following enhancements are introduced in the webhook configuration and delivery status monitoring workflows: + +Channel validation:: +Administrators can verify the connection status of a webhook channel by sending a test payload in a `POST` request to the `/api/rest/2.0/system/communication-channels/validate` REST API endpoint. For more information, see xref:webhooks-comm-channel.adoc#_validate_communication_channel_configuration[Webhook channel validation]. + +Monitor webhook delivery:: +Administrators can also monitor the status of a webhook delivery via a `POST /api/rest/2.0/jobs/history/communication-channels/search` API request. For more information, see xref:webhooks-comm-channel.adoc#_monitor_webhook_delivery_and_job_status[Monitor webhook delivery and job status]. + +Support for custom HTTP headers in webhook requests:: +When configuring or updating a webhook, you can now specify custom headers to include in every outbound request, in addition to the standard HTTP and authentication headers that ThoughtSpot sends. For more information, refer to the xref:webhooks-lb-schedule.adoc#_create_a_webhook[webhook documentation]. + +--- + + +[discrete] +==== Spotter embed enhancements +You can now customize the appearance and contents of the chat history sidebar panel in Spotter embedding. + +You can also customize the branding and logo in the Spotter chat interface. + +For more information, see xref:embed-spotter.adoc#_chat_history_panel[Customizing chat history sidebar] and xref:embed-spotter.adoc#_hiding_the_spotter_icon_and_thoughtspot_branding_chat_interface[Hiding logo and brand label in Spotter chat interface]. + +--- + +[discrete] +==== Liveboard enhancements +The following enhancements are introduced in Liveboard export and filtering workflows. + +Embedding a personalized Liveboard view:: +You can now embed a saved personalized Liveboard view using the `personalizedViewId` and load it along with the `liveboardId` in your app. + +Centralized filter modal:: +Liveboard users can modify multiple filters and parameters in a single session using the centralized filter modal. This is an early access feature and disabled by default on ThoughtSpot embedded instances. To enable this feature on embedded Liveboards, set the `isCentralizedLiveboardFilterUXEnabled` to `true`. + +Current period inclusion in rolling date filters:: +The rolling date filters with the **Last ** and **Next ** filter types support including current period. Developers can disable, show, or hide this option using `isThisPeriodInDateFiltersEnabled` or `Action.IncludeCurrentPeriod`. + +Liveboard PNG export:: +The PNG export workflow in the `/api/rest/2.0/report/liveboard` REST API is enhanced to provide high-resolution PNG files. The legacy PNG workflow is deprecated in 26.4.0.cl. For more information about breaking changes and deprecation guidelines, see xref:deprecated-features.adoc[Deprecation announcements]. For information about the new PNG download workflow, see xref:data-report-v2-api.adoc#_liveboard_report_api[Liveboard report API documentation]. + +--- + + +[discrete] +==== Full app embedding +In full application embedded deployments with the V3 navigation and home page experience, the default list page experience is set to ListPage v3 experience. + +The ListPage V3 experience provides a refreshed list layout and styling, including the following enhancements: + +* The **Views** column to show the number of views for each object. +* Sorting options for **Name**, **Author**, and **Views** columns. +* Filters can be added by clicking the column header without opening the filter modal. This option is available for **Favorites**, **Views** columns, and **Verified** columns. + +For more information, see xref:full-app-customize.adoc#_customize_list_page_experience[List page customization]. + +--- + +[discrete] +==== Variable API +The variable REST API provides new API endpoints for the following bulk operations: + +* Bulk deletion: +You can now delete multiple variables in a single API request using the `/api/rest/2.0/template/variables/delete` endpoint. +* Batch update of variable values: +You can now assign and update multiple values to a variable in a single API request using the `/api/rest/2.0/template/variables/{identifier}/update-values` endpoint. + +[NOTE] +==== +The `/api/rest/2.0/template/variables/update-values` and `/api/rest/2.0/template/variables/{identifier}/delete` endpoints are now deprecated. Use the new `/api/rest/2.0/template/variables/{identifier}/update-values` and `/api/rest/2.0/template/variables/delete` endpoints for the variable update and delete operations instead. +==== + +For more information, see xref:variables.adoc[Variables documentation]. + +--- + + +[discrete] +==== Metadata parameterization +You can now parameterize multiple properties of metadata objects using `POST /api/rest/2.0/metadata/parameterize-fields`. The legacy endpoint `/api/rest/2.0/metadata/parameterize` is deprecated in 26.4.0.cl and later versions, and is replaced with the new endpoint to allow updating multiple fields in a single API request. + +For more information, see xref:metadata-parameterization.adoc[Metadata parameterization documentation]. + +--- + + +[discrete] +==== Collections [beta betaBackground]^Beta^ +ThoughtSpot embedded users can now use REST APIs v2 to organize different ThoughtSpot objects into organizational containers called *Collections*. These objects can be Liveboards, Answers, data models, tables, and even other Collections. + +For more information, see xref:collections.adoc[Collections]. + +[NOTE] +==== +These APIs are currently in beta and turned off by default on ThoughtSpot instances. To enable this feature on your instance, contact ThoughtSpot Support. +==== --- +[discrete] +==== Visual Embed SDK +For information about the new features and enhancements introduced in Visual Embed SDK version 1.46.0, see the xref:api-changelog.adoc[Visual Embed changelog]. + + +[discrete] +==== REST API v2 +For information about REST API v2 enhancements, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. + +--- |=== == March 2026 **Release version**: ThoughtSpot Cloud 26.3.0.cl + -*Upgrade notes*: No breaking changes in this release. + +*Upgrade notes*: ⚠️ Includes feature deprecations. Refer to xref:rest-apiv2-changelog.adoc#_custom_access_token_api[REST API changelog] and xref:deprecated-features.adoc[Deprecation announcements]. + *Recommended SDK versions*: Visual Embed SDK v1.46.0 and later [.cl-table, cols="2,4", frame=none, grid=none] |=== + a| [.cl-label] *Version 26.3.0.cl* a| +[discrete] +==== Amazon S3 storage destination for webhook delivery +You can now configure ThoughtSpot to deliver webhook payloads and attachments directly into your own Amazon S3 storage using secure AWS cross-account access. To enable this integration, your AWS administrator must create an IAM role with S3 permissions and trust policy, and then register a webhook in ThoughtSpot to deliver the payloads and attachments directly to your S3 bucket. + +For more information, see xref:webhooks-s3-storage.adoc[Amazon S3 storage integration for webhook delivery]. + +--- + +[discrete] +==== Host event enhancements for context-aware routing + +HostEvents in the Visual Embed SDK are enhanced to improve event routing and context targeting in ThoughtSpot embedded applications. + +Developers can use the page context framework in the SDK to route host events to a specific UI layer and align user experience with the product UI behavior in multi-modal contexts. + +For more information, see xref:events-context-aware-routing.adoc[Context-based execution of host events]. + +--- + +[discrete] +==== JWT-based ABAC implementation +The legacy JWT-based approach that uses `filter_rules` and `parameter_values` to implement Attribute-Based Access Control (ABAC) is deprecated. + +As part of this deprecation, the following changes have been introduced to the custom authentication token API workflow and REST API Playground: + +* The `filter_rules` parameter on the custom token authentication page in the REST API Playground is no longer available for new configurations. This change does not affect your existing implementation. + +* The `parameter_values` property is not deprecated in version 26.3.0.cl and remains supported until further notice. However, using parameter values for row-level security use cases will ultimately be deprecated in an upcoming release. + +Existing ABAC implementations that use `filter_rules` will continue to function until further notice. However, we strongly recommend migrating your legacy ABAC implementation to the ABAC via RLS method that uses custom variables. For migration steps, refer to the xref:abac-migration-guide.adoc[ABAC migration guide]. + +For new deployments, use ABAC via RLS with custom variables and pass data security attributes through the `variable_values` property in the custom access token, and define your RLS rules based on those variables. For more information, see xref:abac_rls-variables.adoc[ABAC via RLS]. + +--- + +[discrete] +==== Spotter coaching access across published Orgs +Starting with the 26.3.0.cl release, ThoughtSpot supports publishing Spotter coaching information to other Orgs. Coaching changes from the primary Org are synchronized with the data models published in secondary Orgs. + +Administrators and users with edit access to data models can programmatically control user access to Spotter coaching information using the object privilege REST API endpoint, `/api/rest/2.0/security/metadata/manage-object-privilege`. They can assign `SPOTTER_COACHING_PRIVILEGE` to other users and user groups, allowing access to the coaching information without requiring data model editing or administration privileges. + +Users and groups with `SPOTTER_COACHING_PRIVILEGE` can import and export coaching TML on data models in the source and destination Orgs where the model is published, and can also share these objects with other users and groups. + +For more information, see xref:spotter-nl-instructions.adoc#_spotter_data_model_instructions_access[Spotter data model instructions access]. + +--- + +[discrete] +==== Full application embedding +The height and aspect ratio of the logo in the top-left corner of the ThoughtSpot application interface have been updated for visual alignment and consistency across pages. This enhancement is available only in the V3 navigation and home page experience. + +If you have embedded the full application with the V3 navigation experience, you may notice that the logo appears smaller in the top navigation. This is a design update and does not require any configuration changes to your current embedding implementation. However, we recommend that you review the logo size and appearance, and adjust your custom logo if necessary. + +For information about adding a custom logo image, see xref:customize-style.adoc#logo-change[Customize application logo and favicon]. + +--- + [discrete] ==== Visual Embed SDK -The Visual Embed SDK version 1.46.0 includes new features and enhancements. For more information, see the xref:api-changelog.adoc[Visual Embed SDK changelog]. +For information about the new features and enhancements introduced in Visual Embed SDK version 1.46.0, see the xref:api-changelog.adoc[Visual Embed changelog]. --- [discrete] ==== REST API v2 -For information about REST API v2 enhancements in this release, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. +For information about REST API v2 enhancements, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. --- |=== == February 2026 - **Release version**: ThoughtSpot Cloud 26.2.0.cl + -*Upgrade notes*: No breaking changes in this release. + +*Upgrade notes*: ⚠️ Includes API parameter deprecations. Refer to xref:rest-apiv2-changelog.adoc[REST API changelog] and xref:deprecated-features.adoc[Deprecation announcements]. + *Recommended SDK versions*: Visual Embed SDK v1.45.0 and later + [.cl-table, cols="2,4", frame=none, grid=none] |=== a| @@ -428,33 +717,146 @@ a| *Version 26.2.0.cl* a| +[discrete] +==== SpotterCode extension for IDEs [earlyAccess eaBackground]#Early Access# + +ThoughtSpot introduces SpotterCode, an AI-powered Model Context Protocol (MCP) extension for Integrated Development Environments (IDEs) such as Cursor, Visual Studio Code, and Claude Code. When integrated, SpotterCode enables the AI agent in the IDE to access ThoughtSpot SDKs and API documentation resources and provide in-context coding assistance to developers embedding ThoughtSpot content within their applications. + +SpotterCode is available as an Early Access feature and can be integrated with development environments that support MCP servers and tools. For more information, see xref:spottercode.adoc[SpotterCode], xref:spottercode-integration.adoc[Integrating SpotterCode in IDEs], and xref:spottercode-prompt-guide.adoc[SpotterCode prompting guide]. + +--- + +[discrete] +==== Spotter 3 experience [earlyAccess eaBackground]#Early Access# +You can now embed the Spotter 3 experience, which introduces several new capabilities, agentic analytics, and an enhanced user experience. Spotter 3 is an Early Access feature and is disabled by default on ThoughtSpot embedded instances. + +For more information, see xref:embed-ai-analytics.adoc[Embed AI Search and Analytics] and xref:embed-spotter.adoc[Spotter embedding documentation]. + +--- + +[discrete] +==== Rate limits for REST APIs +To prevent excessive requests from reaching application servers and ensure API stability and service quality for REST API users, ThoughtSpot enforces rate limits on public API requests per client IP. These limits are applied globally at the cluster level for all public API requests, including calls to both REST API v1 and v2 endpoints. +//Administrators can adjust these limits for their ThoughtSpot deployments as needed. + +For more information, see xref:about-rest-apis.adoc#_rate_limits_for_api_requests[Rate limits for REST APIs]. + +--- + +[discrete] +==== Security settings via REST APIs +Security settings that ensure data security and a seamless embedded user experience can now be configured through REST APIs v2. Administrators and developers can configure allowlists for: + +* Content Security Policy (CSP) +* Cross-origin Resource Sharing (CORS) +* Authentication attributes +* Access control settings + +For more information, see xref:security-settings.adoc[Security Settings]. + +--- + +[discrete] +==== WebSocket support for external tools +ThoughtSpot supports secure WebSocket (`wss://`) endpoints for external tool script integrations, for example, tools that open WebSocket connections from the browser. + +To allow a WebSocket host, add the corresponding `wss://` URL to both your CSP allowlists. Only hosts explicitly listed with the `wss://` protocol are permitted. Existing `https://` entries in the allowlists remain unchanged and continue to function as expected. + +For more information, see xref:3rd-party-script.adoc#_allow_websocket_endpoints[External tools and script integration]. + +--- + + [discrete] ==== Visual Embed SDK -The Visual Embed SDK version 1.45.0 includes new features and enhancements. For more information, see the xref:api-changelog.adoc[Visual Embed SDK changelog]. +For information about the new features and enhancements introduced in Visual Embed SDK version 1.45.0, see the xref:api-changelog.adoc[Visual Embed changelog]. --- [discrete] ==== REST API v2 -For information about REST API v2 enhancements in this release, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. +For information about REST API v2 enhancements, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. --- - |=== + == January 2026 -**Release version**: ThoughtSpot Cloud 26.1.0.cl + -*Upgrade notes*: No breaking changes in this release. + +**Release version**: ThoughtSpot Cloud 10.15.0.cl + +*Upgrade notes*: No breaking changes. + *Recommended SDK versions*: Visual Embed SDK v1.44.0 and later + [.cl-table, cols="2,4", frame=none, grid=none] |=== a| [.cl-label] -*Version 26.1.0.cl* +*Version 10.15.0.cl* a| +[discrete] +==== Theme Builder +Theme Builder is now generally available (GA) and will be rolled out to all ThoughtSpot instances in customer deployments over the next few weeks. + +When this feature is enabled on your instance, you can access it from the *Develop* page in ThoughtSpot and use it to customize styles and UX themes directly within the product. + +For more information, see xref:theme-builder.adoc[Theme Builder]. + +--- + +[discrete] +==== V3 navigation and home page experience + +The new V3 navigation and home page experience is now generally available (GA) and can be enabled on ThoughtSpot embedded instances. + +The default UI experience in full application embedding remains the classic (V1) experience until further notice. Developers embedding the full ThoughtSpot application can enable the V3 experience in their applications by setting the appropriate configuration options in their embed code. + +For more information, see xref:full-app-customize.adoc[Customizing full application embedding]. + +--- + +[discrete] +==== Formula variables in RLS rules + +You can now create formula variables using the Variable REST API and use these variables in RLS rules for a specific data context and in ABAC token requests to dynamically assign security attributes to users. + +For more information, see xref:abac_rls-variables.adoc[ABAC via RLS with variables]. + +--- + +[discrete] +==== Spotter APIs + +ThoughtSpot introduces new REST APIs for the following Spotter workflows: + +* To send queries to a conversation session with the Spotter agent +* To set natural language (NL) instructions on a model to coach the Spotter system +* To fetch NL instructions configured on a model + +For more information, see xref:spotter-apis.adoc[Spotter APIs]. + +--- + +[discrete] +==== Embed events and parameters to intercept API calls +You can now intercept API calls from the embedded ThoughtSpot application using the `interceptUrls` attribute in the Visual Embed SDK. This feature lets you control API requests in your embedding application and use embed events to modify, block, or handle requests before they are sent to the backend. For more information, see xref:api-intercept.adoc[Intercept API calls and search requests]. + +--- + +[discrete] +==== Icon customization enhancements + +You can now replace or customize the chart switcher toggle and icons in the Charts drawer on an Answer or visualization page using SVG sprites. Previously, these icons were fixed to ThoughtSpot defaults and were not configurable. In the new version, these icons are available as SVG components and can be replaced by developers through the xref:customize-icons.adoc[icon customization framework] as needed. + +--- + +[discrete] +==== Mobile Embed SDK +The SDKs for embedding ThoughtSpot components in mobile apps are now Generally Available (GA). For more information about the SDKs and how to embed a ThoughtSpot component in a mobile app, see xref:mobile-embed.adoc[Mobile embed documentation]. + +--- + [discrete] ==== Visual Embed SDK For information about the new features and enhancements introduced in Visual Embed SDK version 1.44.0, see xref:api-changelog.adoc[Visual Embed changelog]. From 6db40941d616eec6e8ed443aee0b078bf39df0b6 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 17 Aug 2026 10:53:51 +0530 Subject: [PATCH 047/154] docs: add What's New blurb for 26.9.0.cl / aug.26.mt / SDK 1.52.0 New September 2026 section inserted above August 2026. All existing content preserved. Covers: overrideHistoryState (SCAL-317516), HomeLeftNavItem.Collections (SCAL-314461), Answer Export API GA (SCAL-306069), Snowflake Semantic View APIs (SCAL-309867), Spotter Memory GA (SCAL-306173), conversation sharing APIs, KPI isSparklineEnabled (SCAL-320899), Personalized Views TML portability GA (SCAL-307284) From 4ec9f6d8ddb26cc3a9218b873e2772defcce9f05 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 17 Aug 2026 10:54:16 +0530 Subject: [PATCH 048/154] docs: fix indentation in September 2026 What's New section --- modules/ROOT/pages/whats-new.adoc | 132 +++++++++++++++--------------- 1 file changed, 66 insertions(+), 66 deletions(-) diff --git a/modules/ROOT/pages/whats-new.adoc b/modules/ROOT/pages/whats-new.adoc index 73c23be30..1688c82dc 100644 --- a/modules/ROOT/pages/whats-new.adoc +++ b/modules/ROOT/pages/whats-new.adoc @@ -24,109 +24,109 @@ This page lists new features, enhancements, and deprecated functionality introdu // ============================================================ == September 2026 - **Release version**: ThoughtSpot Cloud 26.9.0.cl + - *Upgrade notes*: No breaking changes in this release. + - *Recommended SDK versions*: Visual Embed SDK v1.52.0 and later +**Release version**: ThoughtSpot Cloud 26.9.0.cl + +*Upgrade notes*: No breaking changes in this release. + +*Recommended SDK versions*: Visual Embed SDK v1.52.0 and later - [.cl-table, cols="2,4", frame=none, grid=none] - |=== - a| - [.cl-label] - *Version 26.9.0.cl* +[.cl-table, cols="2,4", frame=none, grid=none] +|=== +a| +[.cl-label] +*Version 26.9.0.cl* - a| - [discrete] - ==== Browser history management in full application embedding [.version-badge.new]#New# +a| +[discrete] +==== Browser history management in full application embedding [.version-badge.new]#New# - The Visual Embed SDK 1.52.0 introduces the `overrideHistoryState` configuration parameter for `AppEmbed`. When ThoughtSpot is embedded in a host application, every internal navigation event pushes a new entry onto the browser history stack, causing the browser *Back* button to step through ThoughtSpot's internal pages before returning to the host application. Setting `overrideHistoryState: true` converts ThoughtSpot's internal `pushState` calls to `replaceState`, preventing internal navigation from polluting the host application's browser history stack. For more information, see xref:full-app-embed.adoc[Full application embedding]. +The Visual Embed SDK 1.52.0 introduces the `overrideHistoryState` configuration parameter for `AppEmbed`. When ThoughtSpot is embedded in a host application, every internal navigation event pushes a new entry onto the browser history stack, causing the browser *Back* button to step through ThoughtSpot's internal pages before returning to the host application. Setting `overrideHistoryState: true` converts ThoughtSpot's internal `pushState` calls to `replaceState`, preventing internal navigation from polluting the host application's browser history stack. For more information, see xref:full-app-embed.adoc[Full application embedding]. - --- +--- - [discrete] - ==== Collections in embedded left navigation panel [.version-badge.new]#New# +[discrete] +==== Collections in embedded left navigation panel [.version-badge.new]#New# - The `HomeLeftNavItem.Collections` value is now available in the Visual Embed SDK 1.52.0. Embed developers can include *Collections* as a navigation option in the left navigation panel for full application embeds, enabling end users to navigate to *Collections* directly from the embedded experience. For more information, see xref:full-app-customize.adoc[Customize the embedded ThoughtSpot experience]. +The `HomeLeftNavItem.Collections` value is now available in the Visual Embed SDK 1.52.0. Embed developers can include *Collections* as a navigation option in the left navigation panel for full application embeds, enabling end users to navigate to *Collections* directly from the embedded experience. For more information, see xref:full-app-customize.adoc[Customize the embedded ThoughtSpot experience]. - --- +--- - [discrete] - ==== Answer Export API — General Availability [.version-badge.new]#New# +[discrete] +==== Answer Export API — General Availability [.version-badge.new]#New# - The Answer Export API (`POST /api/rest/2.0/report/answer`) is now generally available. This release introduces the following enhancements: +The Answer Export API (`POST /api/rest/2.0/report/answer`) is now generally available. This release introduces the following enhancements: - * *Pinned Answer export*: Export a pinned visualization from a Liveboard directly using the `viz_guid` parameter. - * *Personalized View support*: Export data from a specific Personalized View using `personalised_view_identifier`. - * *Spotter Answer export*: Export Spotter-generated answers in `XLSX` and `PDF` formats in addition to `CSV` and `PNG`. - * *Custom PNG dimensions*: Control PNG export dimensions using `x_resolution` and `y_resolution` parameters (600-3840 px). - * *Scaling control*: Adjust chart element size in PNG exports using `scaling_factor` (80-400). +* *Pinned Answer export*: Export a pinned visualization from a Liveboard directly using the `viz_guid` parameter. +* *Personalized View support*: Export data from a specific Personalized View using `personalised_view_identifier`. +* *Spotter Answer export*: Export Spotter-generated answers in `XLSX` and `PDF` formats in addition to `CSV` and `PNG`. +* *Custom PNG dimensions*: Control PNG export dimensions using `x_resolution` and `y_resolution` parameters (600-3840 px). +* *Scaling control*: Adjust chart element size in PNG exports using `scaling_factor` (80-400). - For more information, see xref:data-report-v2-api.adoc#answer-report[Answer Report API]. +For more information, see xref:data-report-v2-api.adoc#answer-report[Answer Report API]. - --- +--- - [discrete] - ==== Snowflake Semantic View integration APIs [.version-badge.new]#New# +[discrete] +==== Snowflake Semantic View integration APIs [.version-badge.new]#New# - ThoughtSpot introduces four new REST API v2.0 endpoints to manage Snowflake Semantic View integrations programmatically without using the ThoughtSpot UI: +ThoughtSpot introduces four new REST API v2.0 endpoints to manage Snowflake Semantic View integrations programmatically without using the ThoughtSpot UI: - * `POST /api/rest/2.0/semantic-integrations/create` - * `POST /api/rest/2.0/semantic-integrations/search` - * `POST /api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/import` - * `POST /api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/delete` +* `POST /api/rest/2.0/semantic-integrations/create` +* `POST /api/rest/2.0/semantic-integrations/search` +* `POST /api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/import` +* `POST /api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/delete` - Requires `ADMINISTRATION` or `DATAMANAGEMENT` privilege. For more information, see xref:semantic-integrations-api.adoc[Snowflake Semantic View integration APIs]. +Requires `ADMINISTRATION` or `DATAMANAGEMENT` privilege. For more information, see xref:semantic-integrations-api.adoc[Snowflake Semantic View integration APIs]. - --- +--- - [discrete] - ==== Spotter Memory — General Availability [.version-badge.new]#New# +[discrete] +==== Spotter Memory — General Availability [.version-badge.new]#New# - The Spotter memory feature is now generally available. The memory APIs (`POST /api/rest/2.0/ai/memory/import` and `POST /api/rest/2.0/ai/memory/export`) are enabled by default on all ThoughtSpot Cloud instances. Administrators can manage and audit Spotter's training data programmatically. For more information, see xref:spotter-agent-apis.adoc[Spotter agent APIs]. +The Spotter memory feature is now generally available. The memory APIs (`POST /api/rest/2.0/ai/memory/import` and `POST /api/rest/2.0/ai/memory/export`) are enabled by default on all ThoughtSpot Cloud instances. Administrators can manage and audit Spotter's training data programmatically. For more information, see xref:spotter-agent-apis.adoc[Spotter agent APIs]. - --- +--- - [discrete] - ==== Spotter conversation sharing APIs [.version-badge.new]#New# +[discrete] +==== Spotter conversation sharing APIs [.version-badge.new]#New# - ThoughtSpot introduces three new REST API v2.0 endpoints to share Spotter agent conversations programmatically: +ThoughtSpot introduces three new REST API v2.0 endpoints to share Spotter agent conversations programmatically: - * `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` -- Share a conversation with users or groups with `READ_ONLY` access. - * `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content` -- Retrieve the shared messages and answers in a conversation. - * `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info` -- Retrieve the list of principals a conversation is shared with and their access levels. +* `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` -- Share a conversation with users or groups with `READ_ONLY` access. +* `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content` -- Retrieve the shared messages and answers in a conversation. +* `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info` -- Retrieve the list of principals a conversation is shared with and their access levels. - For more information, see xref:spotter-agent-apis.adoc#_sharing_spotter_conversations[Sharing Spotter conversations]. +For more information, see xref:spotter-agent-apis.adoc#_sharing_spotter_conversations[Sharing Spotter conversations]. - --- +--- - [discrete] - ==== KPI sparkline setting in metadata search response [.version-badge.new]#New# +[discrete] +==== KPI sparkline setting in metadata search response [.version-badge.new]#New# - The `POST /api/rest/2.0/metadata/search` response now includes the `isSparklineEnabled` field in the `AnswerSpecHeader` object for KPI chart type answers. This boolean field indicates whether the sparkline trend line is enabled for a given KPI visualization. +The `POST /api/rest/2.0/metadata/search` response now includes the `isSparklineEnabled` field in the `AnswerSpecHeader` object for KPI chart type answers. This boolean field indicates whether the sparkline trend line is enabled for a given KPI visualization. - --- +--- - [discrete] - ==== Personalized Views TML portability — General Availability [.version-badge.new]#New# +[discrete] +==== Personalized Views TML portability — General Availability [.version-badge.new]#New# - The Personalized Views TML portability feature introduced in Early Access in 26.8.0.cl is now generally available. The `author` and `obj_id` fields are fully supported in exported and imported Personalized View TML. Smart merge import logic is applied by default. For more information, see xref:tml.adoc#personalized-views-portability[Personalized Views portability]. +The Personalized Views TML portability feature introduced in Early Access in 26.8.0.cl is now generally available. The `author` and `obj_id` fields are fully supported in exported and imported Personalized View TML. Smart merge import logic is applied by default. For more information, see xref:tml.adoc#personalized-views-portability[Personalized Views portability]. - --- +--- - [discrete] - ==== Visual Embed SDK - The Visual Embed SDK version 1.52.0 introduces `overrideHistoryState` for browser history management in `AppEmbed` and `HomeLeftNavItem.Collections` for embedded left navigation. For more information, see the xref:api-changelog.adoc[Visual Embed SDK changelog]. +[discrete] +==== Visual Embed SDK +The Visual Embed SDK version 1.52.0 introduces `overrideHistoryState` for browser history management in `AppEmbed` and `HomeLeftNavItem.Collections` for embedded left navigation. For more information, see the xref:api-changelog.adoc[Visual Embed SDK changelog]. - --- +--- - [discrete] - ==== REST API v2 - For information about REST API v2 enhancements in this release, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. +[discrete] +==== REST API v2 +For information about REST API v2 enhancements in this release, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. - --- +--- - |=== +|=== - == August 2026 +== August 2026 **Release version**: ThoughtSpot Cloud 26.8.0.cl + *Upgrade notes*: ⚠️ Includes breaking changes and deprecations. Refer to feature details in this page and xref:deprecated-features.adoc[Deprecation announcements]. + From 18bb058de6404238c3059a5dadec44f0ffbacc8a Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 17 Aug 2026 10:54:18 +0530 Subject: [PATCH 049/154] docs: fix indentation in September 2026 What's New section From de530e85db2fe5bd3b0765dc98b35ec146979fc8 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Mon, 17 Aug 2026 10:55:11 +0530 Subject: [PATCH 050/154] formatting fixes --- modules/ROOT/pages/api-changelog.adoc | 126 +++++++++++++------------- 1 file changed, 64 insertions(+), 62 deletions(-) diff --git a/modules/ROOT/pages/api-changelog.adoc b/modules/ROOT/pages/api-changelog.adoc index afdb900bf..110feaf28 100644 --- a/modules/ROOT/pages/api-changelog.adoc +++ b/modules/ROOT/pages/api-changelog.adoc @@ -10,84 +10,86 @@ This page documents the changes introduced in each release of the Visual Embed S == Version 1.52.x, September 2026 - [width="100%" cols="1,4"] - |==== - |[tag greenBackground]#NEW FEATURE# a| - - [discrete] - ===== Browser history management in full application embedding - - // SOURCE: SCAL-317516 - // SOURCE: thoughtspot/visual-embed-sdk/src/types.ts (master) - - ThoughtSpot 26.9.0.cl introduces the `overrideHistoryState` configuration parameter for `AppEmbed`. When embedding ThoughtSpot in a host application, every internal ThoughtSpot navigation event (for example, switching between Liveboards or Answers) pushes a new entry onto the browser's history stack. This causes the browser *Back* button to step through ThoughtSpot's internal navigation before returning to the host application's prior page. - - Setting `overrideHistoryState: true` converts all ThoughtSpot internal `pushState` calls to `replaceState`, preventing ThoughtSpot navigation from polluting the host application's browser history stack. +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| - [source,JavaScript] - ---- - import { AppEmbed, init, AuthType } from '@thoughtspot/visual-embed-sdk'; +[discrete] +===== Browser history management in full application embedding - init({ - thoughtSpotHost: 'https://.thoughtspot.cloud', - authType: AuthType.TrustedAuthToken, - getAuthToken: () => fetch('/ts-token').then(r => r.json()).then(d => d.token), - }); +// SOURCE: SCAL-317516 +// SOURCE: thoughtspot/visual-embed-sdk/src/types.ts (master) - const embed = new AppEmbed('#embed-container', { - frameParams: { width: '100%', height: '100%' }, - overrideHistoryState: true, // <1> - }); +ThoughtSpot 26.9.0.cl introduces the `overrideHistoryState` configuration parameter for `AppEmbed`. When embedding ThoughtSpot in a host application, every internal ThoughtSpot navigation event (for example, switching between Liveboards or Answers) pushes a new entry onto the browser's history stack. This causes the browser *Back* button to step through ThoughtSpot's internal navigation before returning to the host application's prior page. - embed.render(); - ---- - <1> When set to `true`, ThoughtSpot replaces rather than pushes browser history entries during internal navigation. +Setting `overrideHistoryState: true` converts all ThoughtSpot internal `pushState` calls to `replaceState`, preventing ThoughtSpot navigation from polluting the host application's browser history stack. - [NOTE] - ==== - `overrideHistoryState` is available on `AppEmbed` only. It is not supported on `LiveboardEmbed`, `SearchEmbed`, or `SpotterEmbed`. Validate behavior across Chrome, Firefox, and Safari before enabling in production. - ==== +//// +[source,JavaScript] +---- +import { AppEmbed, init, AuthType } from '@thoughtspot/visual-embed-sdk'; - For more information, see xref:full-app-embed.adoc[Full application embedding]. +init({ + thoughtSpotHost: 'https://.thoughtspot.cloud', + authType: AuthType.TrustedAuthToken, + getAuthToken: () => fetch('/ts-token').then(r => r.json()).then(d => d.token), +}); - |[tag greenBackground]#NEW FEATURE# a| +const embed = new AppEmbed('#embed-container', { + frameParams: { width: '100%', height: '100%' }, + overrideHistoryState: true, // <1> +}); - [discrete] - ===== Collections in left navigation panel +embed.render(); +---- +<1> When set to `true`, ThoughtSpot replaces rather than pushes browser history entries during internal navigation. +//// - // SOURCE: SCAL-314461 +[NOTE] +==== +`overrideHistoryState` is available on `AppEmbed` only. It is not supported on `LiveboardEmbed`, `SearchEmbed`, or `SpotterEmbed`. Validate behavior across Chrome, Firefox, and Safari before enabling in production. +==== - The `HomeLeftNavItem.Collections` enum value is now available in the Visual Embed SDK. Embed developers can include *Collections* as a selectable navigation option in the embedded left navigation panel for full application embeds. When enabled, end users of the embedded application can navigate to *Collections* from the left navigation panel. +For more information, see xref:full-app-embed.adoc[Full application embedding]. - [source,JavaScript] - ---- - import { AppEmbed, HomeLeftNavItem, init, AuthType } from '@thoughtspot/visual-embed-sdk'; +|[tag greenBackground]#NEW FEATURE# a| - init({ - thoughtSpotHost: 'https://.thoughtspot.cloud', - authType: AuthType.TrustedAuthToken, - getAuthToken: () => fetch('/ts-token').then(r => r.json()).then(d => d.token), - }); +[discrete] +===== Collections in left navigation panel - const embed = new AppEmbed('#embed-container', { - frameParams: { width: '100%', height: '100%' }, - leftNavOrder: [ - HomeLeftNavItem.Home, - HomeLeftNavItem.Liveboards, - HomeLeftNavItem.Answers, - HomeLeftNavItem.Collections, // <1> - ], - }); +// SOURCE: SCAL-314461 - embed.render(); - ---- - <1> Include `HomeLeftNavItem.Collections` in the `leftNavOrder` array to show Collections in the embedded left navigation panel. +The `HomeLeftNavItem.Collections` enum value is now available in the Visual Embed SDK. Embed developers can include *Collections* as a selectable navigation option in the embedded left navigation panel for full application embeds. When enabled, end users of the embedded application can navigate to *Collections* from the left navigation panel. +//// +[source,JavaScript] +---- +import { AppEmbed, HomeLeftNavItem, init, AuthType } from '@thoughtspot/visual-embed-sdk'; + +init({ + thoughtSpotHost: 'https://.thoughtspot.cloud', + authType: AuthType.TrustedAuthToken, + getAuthToken: () => fetch('/ts-token').then(r => r.json()).then(d => d.token), +}); + +const embed = new AppEmbed('#embed-container', { + frameParams: { width: '100%', height: '100%' }, + leftNavOrder: [ + HomeLeftNavItem.Home, + HomeLeftNavItem.Liveboards, + HomeLeftNavItem.Answers, + HomeLeftNavItem.Collections, // <1> + ], +}); + +embed.render(); +---- +<1> Include `HomeLeftNavItem.Collections` in the `leftNavOrder` array to show Collections in the embedded left navigation panel. +//// +For more information, see xref:full-app-customize.adoc[Customize full application embedding]. - For more information, see xref:full-app-customize.adoc[Customize full application embedding]. +|==== - |==== - == Version 1.51.x, August 2026 [width="100%" cols="1,4"] @@ -1999,4 +2001,4 @@ Users with edit permissions can view and access the *Edit* action. The *Download When a user accesses the embedded application from a web browser that has third-party cookies disabled, the Visual Embed SDK emits the `NoCookieAccess` event to notify the developer. Cookies are disabled by default in Safari. Users can enable third-party cookies in Safari’s Preferences setting page or use another web browser. To know how to enable this setting by default on Safari for a ThoughtSpot embedded instance, contact ThoughtSpot Support. -|==== \ No newline at end of file +|==== From 3949c7b83b4c2c455ce80c95c21373a0951d7696 Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Mon, 17 Aug 2026 13:23:30 +0530 Subject: [PATCH 051/154] objectid --- .../ROOT/pages/intro-thoughtspot-objects.adoc | 92 ++++++++++++++++++- 1 file changed, 91 insertions(+), 1 deletion(-) diff --git a/modules/ROOT/pages/intro-thoughtspot-objects.adoc b/modules/ROOT/pages/intro-thoughtspot-objects.adoc index 3096ec818..155eeef77 100644 --- a/modules/ROOT/pages/intro-thoughtspot-objects.adoc +++ b/modules/ROOT/pages/intro-thoughtspot-objects.adoc @@ -16,7 +16,7 @@ The following figure illustrates the object model hierarchy in ThoughtSpot withi image::./images/object_model_hierarchy.png[Object Model Hierarchy] -== Object identifiers +== #Object identifiers# Every object in ThoughtSpot has a globally unique ID (GUID), visible in URLs and in REST API responses as the `id` or `metadata_id` property. GUIDs are unique within a ThoughtSpot instance and thus cannot repeat in different Orgs. Objects have an additional `obj_id` property that is *user-settable* and *unique per Org*. It appears as `metadata_obj_id` in responses from the `/metadata/search` REST API. @@ -25,6 +25,96 @@ Each Org can have one object with a particular `obj_id`. The combination of `org `obj_id` allows you to export TML that can be imported into any Org on any instance, letting ThoughtSpot determine the object's GUID automatically without requiring any additional effort on your part. +=== Supported object types + +Currently, `obj_id` is supported for the following object types: + +// SOURCE: PRD doc section "Requirements"; SCAL-317366 description + +* Answers +* Data Model +* Logical Tables +* Liveboards +* Visualizations +* Collections +* Personalized Views + +=== obj_id format and constraints + +// SOURCE: PRD doc section "Identity Constraints and Object-ID Specification"; SCAL-314582 +`obj_id` values must meet the following requirements: + +[cols="2,3", options="header"] +|=== +|Constraint | Requirement + +|Allowed characters | Lowercase alphanumeric, dots, and hyphens: `[a-z0-9.-]` +|Casing | Strictly lowercase +|Maximum length | 64 characters +|GUID exclusion | Must not match a standard GUID format to prevent ambiguity +|=== + +*Valid examples:* `sales.pipeline.v1`, `finance-ledger-prod`, `ingestion-worker-01` + +=== obj_id resolution + +// SOURCE: PRD doc section "Deterministic Keying and Distributed Consistency"; SCAL-317366 +When you pass an identifier to a REST API endpoint that accepts an `object_identifier`, ThoughtSpot resolves it in the following order: + +. `obj_id` (user-defined identifier) +. GUID +. Name + +This precedence means you can use `obj_id` anywhere a GUID or name is accepted in the REST API v2.0 endpoints that support the `object_identifier` field. Backward compatibility with existing GUID-based and name-based integrations is fully maintained. + +[NOTE] +==== +`obj_id` resolution is scoped to the Org. An `obj_id` value is unique within a single Org. The `org_id` + `obj_id` combination uniquely identifies an object across the entire ThoughtSpot instance. +==== + +=== Setting and updating obj_id + +You can set or update `obj_id` values using the following REST API endpoints: + +* `POST /api/rest/2.0/metadata/update-obj-id` + +Updates the `obj_id` for one or more metadata objects. Accepts the object's GUID (`metadata_identifier`) or its current `obj_id` (`current_obj_id`). + +// SOURCE: deploy-with-tml-apis.adoc; SCAL-317366 +[,json] +---- +{ + "metadata": [ + { + "metadata_identifier": "c1e4043a-4524-4fcb-a20f-9e7aff4dc972", + "new_obj_id": "sales-pipeline-v1" + } + ] +} +---- + +Or, using the current `obj_id`: + +[,json] +---- +{ + "metadata": [ + { + "current_obj_id": "sales-pipeline-v1-c1e4043a", + "new_obj_id": "sales-pipeline-v1" + } + ] +} +---- + +The request accepts an array, so you can update `obj_id` for multiple objects in a single API call. + +[NOTE] +==== +Objects are assigned an automatic `obj_id` after the first change to the object once the feature is enabled on your instance. The auto-generated format appends the first segment of the GUID: for example, `RetailSalesRAD-KPIs-c1e4043a`. If the `metadata_obj_id` property in the `/metadata/search` response is `null`, the object has not been updated since the feature was enabled. +==== + +For information about using `obj_id` in CI/CD workflows, see xref:deploy-with-tml-apis.adoc[Deploy with TML APIs] and xref:development-and-deployment.adoc[Development and deployment]. + == Data modeling You must create a data model with at least one link:https://docs.thoughtspot.com/cloud/latest/connections[connection, window=_blank] and one link:https://docs.thoughtspot.com/cloud/latest/connect-data[Table, window=_blank] before you can use link:https://docs.thoughtspot.com/cloud/latest/search-data[Search data, window=_blank] to create content. Most often, there will be multiple *Tables* with a variety of link:https://docs.thoughtspot.com/cloud/latest/tables-join[joins, window=_blank] defined in ThoughtSpot, and a link:https://docs.thoughtspot.com/cloud/latest/models[Model, window=_blank] that brings those tables together into a presentable analytics model for end users. From a14f67ba93cd55a44b42e6f794d803b505232fdf Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Mon, 17 Aug 2026 16:16:46 +0530 Subject: [PATCH 052/154] lang corrections --- .../ROOT/pages/intro-thoughtspot-objects.adoc | 22 +++++++++---------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/modules/ROOT/pages/intro-thoughtspot-objects.adoc b/modules/ROOT/pages/intro-thoughtspot-objects.adoc index 155eeef77..b88e78e56 100644 --- a/modules/ROOT/pages/intro-thoughtspot-objects.adoc +++ b/modules/ROOT/pages/intro-thoughtspot-objects.adoc @@ -6,9 +6,9 @@ :page-pageid: thoughtspot-objects :page-description: -ThoughtSpot is a business intelligence and data analytics platform that helps you explore, analyze, and share real-time business analytics and interactive insights. Besides being an interactive data analytics platform, ThoughtSpot provides robust, guided search functionality that business users can use to search data instantly. ThoughtSpot is different from other BI tools because ThoughtSpot Search is the core of the ThoughtSpot system. +ThoughtSpot is a business intelligence and data analytics platform for exploring, analyzing, and sharing real-time business analytics and interactive insights. Besides being an interactive data analytics platform, ThoughtSpot provides robust, guided search functionality that business users can use to search data instantly. ThoughtSpot is different from other BI tools because ThoughtSpot Search is the core of the ThoughtSpot system. -Before you look at the rest of the developer documentation, please review this page to understand how ThoughtSpot works relative to other tools you may be familiar with. +Review this page to understand how ThoughtSpot's architecture differs from other BI tools before proceeding with the developer documentation. == Object model hierarchy @@ -23,7 +23,7 @@ Objects have an additional `obj_id` property that is *user-settable* and *unique Each Org can have one object with a particular `obj_id`. The combination of `org_id` + `obj_id` is unique per instance, so it is equivalent to the object's GUID. -`obj_id` allows you to export TML that can be imported into any Org on any instance, letting ThoughtSpot determine the object's GUID automatically without requiring any additional effort on your part. +`obj_id` enables TML export and import across Orgs and instances, allowing ThoughtSpot to automatically determine the object's GUID without manual GUID mapping. === Supported object types @@ -59,13 +59,13 @@ Currently, `obj_id` is supported for the following object types: === obj_id resolution // SOURCE: PRD doc section "Deterministic Keying and Distributed Consistency"; SCAL-317366 -When you pass an identifier to a REST API endpoint that accepts an `object_identifier`, ThoughtSpot resolves it in the following order: +When an identifier is passed to a REST API endpoint that accepts an `object_identifier`, ThoughtSpot resolves it in the following order: . `obj_id` (user-defined identifier) . GUID . Name -This precedence means you can use `obj_id` anywhere a GUID or name is accepted in the REST API v2.0 endpoints that support the `object_identifier` field. Backward compatibility with existing GUID-based and name-based integrations is fully maintained. +This resolution order enables `obj_id` to be used anywhere a GUID or name is accepted in the REST API v2.0 endpoints that support the `object_identifier` field. Backward compatibility with existing GUID-based and name-based integrations is fully maintained. [NOTE] ==== @@ -74,7 +74,7 @@ This precedence means you can use `obj_id` anywhere a GUID or name is accepted i === Setting and updating obj_id -You can set or update `obj_id` values using the following REST API endpoints: +`obj_id` values can be set or updated using the following REST API endpoints: * `POST /api/rest/2.0/metadata/update-obj-id` + Updates the `obj_id` for one or more metadata objects. Accepts the object's GUID (`metadata_identifier`) or its current `obj_id` (`current_obj_id`). @@ -106,7 +106,7 @@ Or, using the current `obj_id`: } ---- -The request accepts an array, so you can update `obj_id` for multiple objects in a single API call. +The request accepts an array, allowing multiple objects to be updated in a single API call. [NOTE] ==== @@ -116,7 +116,7 @@ Objects are assigned an automatic `obj_id` after the first change to the object For information about using `obj_id` in CI/CD workflows, see xref:deploy-with-tml-apis.adoc[Deploy with TML APIs] and xref:development-and-deployment.adoc[Development and deployment]. == Data modeling -You must create a data model with at least one link:https://docs.thoughtspot.com/cloud/latest/connections[connection, window=_blank] and one link:https://docs.thoughtspot.com/cloud/latest/connect-data[Table, window=_blank] before you can use link:https://docs.thoughtspot.com/cloud/latest/search-data[Search data, window=_blank] to create content. +A data model requires at least one link:https://docs.thoughtspot.com/cloud/latest/connections[connection, window=_blank] and one link:https://docs.thoughtspot.com/cloud/latest/connect-data[Table, window=_blank] to use link:https://docs.thoughtspot.com/cloud/latest/search-data[Search data, window=_blank] to create content. Most often, there will be multiple *Tables* with a variety of link:https://docs.thoughtspot.com/cloud/latest/tables-join[joins, window=_blank] defined in ThoughtSpot, and a link:https://docs.thoughtspot.com/cloud/latest/models[Model, window=_blank] that brings those tables together into a presentable analytics model for end users. Data engineers with the *Can manage data* privilege can add connections either link:https://docs.thoughtspot.com/cloud/latest/connections[in the UI, window=_blank] or via xref:connections.adoc[REST API]. Connections are owned and accessible only to their creator, who then imports *Tables* from the connection. Once imported, tables can be shared with other ThoughtSpot groups and users. @@ -141,7 +141,7 @@ ThoughtSpot Search data creates a table or chart view based on the query in the Search data serves the role of report builder or widget designer, while *Liveboards* serve the role of dashboards in other tools. A single search can be saved as a link:https://docs.thoughtspot.com/cloud/latest/answers[*Answer*, window=_blank] object, or the search result can be pinned to a Liveboard. -A link:https://docs.thoughtspot.com/cloud/latest/liveboard[Liveboard, window=_blank] is a collection of many visualizations presented in a defined layout. You do not create the visualizations on a Liveboard directly; they are created from search data results and then pinned to a Liveboard. You can create a new Liveboard from the *Liveboards* page and then add a visualization from the search data result, or you can create a new Liveboard when pinning an Answer retrieved from search data. +A link:https://docs.thoughtspot.com/cloud/latest/liveboard[Liveboard, window=_blank] is a collection of visualizations in a defined layout. Visualizations are created from search data results and pinned to a Liveboard; they cannot be created directly within the Liveboard. New Liveboards can be created from the *Liveboards* page and visualizations from search data results added to them, or new Liveboards can be created when pinning an Answer retrieved from search data. === Content creation workflow @@ -151,9 +151,9 @@ To create content: 2. Save the search result as an *Answer* or pin it to a Liveboard as a visualization. === Visualizations on a Liveboard -You can add any number of visualizations from search results to a Liveboard object. Pinned visualizations exist only within the Liveboard and are independent of objects saved as *Answers*. +Any number of visualizations from search results can be added to a Liveboard object. Pinned visualizations exist only within the Liveboard and are independent of objects saved as *Answers*. -Each time you pin a search result, a separate new visualization is created on the Liveboard. +Each time a search result is pinned, a separate new visualization is created on the Liveboard. To edit a visualization on a Liveboard: From 7355110b663befbef5b7fa6341d04f88ead3ad40 Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Tue, 18 Aug 2026 12:02:46 +0530 Subject: [PATCH 053/154] split the data report apis --- .../pages/common/nav-in-product-help.adoc | 3 +- modules/ROOT/pages/common/nav-rest-api.adoc | 3 +- modules/ROOT/pages/data-apis-v2.adoc | 334 ++++++++++++++++ modules/ROOT/pages/deprecated-features.adoc | 2 +- ...report-v2-api.adoc => report-apis-v2.adoc} | 374 ++---------------- modules/ROOT/pages/rest-apiv2-changelog.adoc | 10 +- modules/ROOT/pages/spotter-agent-apis.adoc | 4 +- modules/ROOT/pages/whats-new.adoc | 2 +- src/components/SecondaryHeader/index.tsx | 2 +- src/configs/doc-configs.js | 2 +- 10 files changed, 377 insertions(+), 359 deletions(-) create mode 100644 modules/ROOT/pages/data-apis-v2.adoc rename modules/ROOT/pages/{data-report-v2-api.adoc => report-apis-v2.adoc} (53%) diff --git a/modules/ROOT/pages/common/nav-in-product-help.adoc b/modules/ROOT/pages/common/nav-in-product-help.adoc index 73d3dedd9..2d9f1a12c 100644 --- a/modules/ROOT/pages/common/nav-in-product-help.adoc +++ b/modules/ROOT/pages/common/nav-in-product-help.adoc @@ -221,7 +221,8 @@ REST APIs *** link:{{navprefix}}/rest-apiv2-users-search[Search users] *** link:{{navprefix}}/rest-apiv2-groups-search[Search groups] *** link:{{navprefix}}/rest-apiv2-metadata-search[Search metadata] -** link:{{navprefix}}/fetch-data-and-report-apis[Data and Report APIs] +** link:{{navprefix}}/fetch-data-and-report-apis[Data APIs] +** link:{{navprefix}}/report-apis[Report APIs] ** link:{{navprefix}}/spotter-api[Spotter APIs] *** link:{{navprefix}}/spotter-agent-apis[AI APIs (Spotter Agent and Spotter 3)] *** link:{{navprefix}}/spotter-agent-instructions[Spotter AI agent instructions] diff --git a/modules/ROOT/pages/common/nav-rest-api.adoc b/modules/ROOT/pages/common/nav-rest-api.adoc index 3ab94642e..fa8b242f4 100644 --- a/modules/ROOT/pages/common/nav-rest-api.adoc +++ b/modules/ROOT/pages/common/nav-rest-api.adoc @@ -19,7 +19,8 @@ REST APIs *** link:{{navprefix}}/rest-apiv2-users-search[Search users] *** link:{{navprefix}}/rest-apiv2-groups-search[Search groups] *** link:{{navprefix}}/rest-apiv2-metadata-search[Search metadata] -** link:{{navprefix}}/fetch-data-and-report-apis[Data and Report APIs] +** link:{{navprefix}}/fetch-data-and-report-apis[Data APIs] +** link:{{navprefix}}/report-apis[Report APIs] ** link:{{navprefix}}/runtime-sort[Runtime sorting] ** link:{{navprefix}}/spotter-api[Spotter APIs] *** link:{{navprefix}}/spotter-agent-apis[AI APIs (Spotter Agent and Spotter 3)] diff --git a/modules/ROOT/pages/data-apis-v2.adoc b/modules/ROOT/pages/data-apis-v2.adoc new file mode 100644 index 000000000..bf259489d --- /dev/null +++ b/modules/ROOT/pages/data-apis-v2.adoc @@ -0,0 +1,334 @@ += Data APIs +:toc: true +:toclevels: 3 + +:page-title: data-apis +:page-pageid: fetch-data-and-report-apis +:page-description: Data APIs + +ThoughtSpot provides the following REST API v2 endpoints to fetch data: + +* xref:#_search_data_api[`POST /api/rest/2.0/searchdata`] to search data from a given data source. +* xref:#_fetch_liveboard_data_api[`POST /api/rest/2.0/metadata/liveboard/data`] to get data from a Liveboard. +* xref:#_fetch_answer_data_api[`POST /api/rest/2.0/metadata/answer/data`] to get data from a saved Answer. + +If Role-Based Access Control (RBAC) is enabled, the `DATADOWNLOADING` (Can download Data) privilege is required to use these APIs. Alternatively, if the granular data download RBAC privileges are enabled for your ThoughtSpot instance, the `CAN_DOWNLOAD_DETAILED_DATA` (Can download detailed data) is required. + +[NOTE] +To download a Liveboard or Answer as a PDF, PNG, CSV, or XLSX file instead of retrieving its data as JSON, see xref:report-apis-v2.adoc[Report APIs]. + +== Search data API + +The `/api/rest/2.0/searchdata` endpoint requires you to specify the data source object ID and a query string for a successful API call. You can also define additional parameters such as `runtime_filter`, `runtime_sort`, and `runtime_param_override` to apply runtime overrides on the data set. + +=== Data source +To search data via API call, you require at least view access to the data source object. The data source object can be a Model, View, or Table. + +You can specify the data source object GUID in the `logical_table_identifier`. The search data endpoint doesn't support searching data from multiple Models, Views, or Tables in a single API request. + +To find the GUID of the Model, View, or Table, use one of the following methods: + +Get data object GUID via API:: + +Send an API request to the `/api/rest/2.0/metadata/search` endpoint with the following parameters in the metadata array: + + ++ +.**Example** +[source,JSON] +---- + "metadata": [ + { + "identifier": "my_model", + "type": "LOGICAL_TABLE" + } + ] +---- + ++ +If you don't know the exact name of the data source object, specify the metadata `type` as `LOGICAL_TABLE` in your API request, and then copy the GUID of the data object from the API response. + +Find the GUID of the data object via UI:: +. Log in to your ThoughtSpot application instance: +. Navigate to **Data workspace**. ++ +---- +https:///#/data/tables/ +---- ++ +. On the **Data workspace** > **Data objects** page, select the data object. For example, if the data source object is a Model, click **Models** and then open the Model. +. In the address bar of the web browser, note the GUID of the data source object. For example, in the following address string, the GUID is `9d93a6b8-ca3a-4146-a1a1-e908b71b963f`: ++ +---- +https:///#/data/tables/9d93a6b8-ca3a-4146-a1a1-e908b71b963f +---- + +. Copy the GUID. + +=== Search query + +include::{path}/search-query-string.adoc[] + +.**Example** +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/searchdata' \ + -H 'Authorization: Bearer {access-token} + -H 'Accept: application/json'\ + -H 'Content-Type: application/json' \ + --data-raw '{ + "query_string": "[sales][store]", + "logical_table_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", +}' +---- + +//// +=== Using tokens generated from Spotter APIs as raw data + +For every natural language query and follow-up question, Spotter APIs such as `/api/rest/2.0/ai/answer/create`, `/api/rest/2.0/ai/agent/converse/sse`, return tokens in the API response. You can use these tokens as raw data to generate an Answer from ThoughtSpot via search data API. + +==== Request example + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/searchdata' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "query_string": "by [city], [product], [item type] = [item type].'\''jackets'\'', [region] = [region].'\''west'\'', sort by sum [sales] descending", + "logical_table_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", + "data_format": "COMPACT", + "record_offset": 0, + "record_size": 10 +}' +---- + +==== API response + +If the API request is successful, ThoughtSpot returns the Answer data for the query string sent in the API request. +//// + +== Fetch Liveboard Data API +To get data from a Liveboard object and its visualizations via `POST /api/rest/2.0/metadata/liveboard/data` endpoint, your user account must have at least view access to the Liveboard specified in the API request. + +The API request body must include the name or GUID of the Liveboard to fetch data. To get specific visualizations from a given Liveboard, add the names or GUIDs of the visualizations in the `visualization_identifiers` array. + +=== Liveboard data request example +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/metadata/liveboard/data' \ + -H 'Authorization: Bearer {access-token}'\ + -H 'Accept: application/json'\ + -H 'Content-Type: application/json' \ + --data-raw '{ + "metadata_identifier": "d084c256-e284-4fc4-b80c-111cb606449a", + "data_format": "COMPACT", + "visualization_identifiers": [ + "a9655c18-9855-4a73-9e7b-ff4fb6da334b", + "bf4c9814-82c1-4ec4-b879-57eae2134cb4", + "8c46d2b6-94c7-4ba7-a628-6e74e297f973", + "f6ef5d1f-cddb-4547-8b66-af4d5f4da5ad" + ] +}' +---- + +[#transient-lb-content] +=== Liveboard data with unsaved changes + +include::{path}/transient-lb-content.adoc[] + +.**Sample browser fetch request** + +[source,TypeScript] +---- +const embedRef = useEmbedRef(); + const handleFilterChanged: MessageCallback = () => { + embedRef.current + .trigger(HostEvent.getExportRequestForCurrentPinboard) + .then((transientPinboardContent) => { + console.log(transientPinboardContent.data); + + const payload = { + metadata_identifier: "abc", + data_format: "COMPACT", + record_offset: 0, + record_size: 10, + transient_content: JSON.stringify(transientPinboardContent.data), + }; + + fetch( + `https://{ThoughtSpot-Host}/api/rest/2.0/metadata/liveboard/data`, + { + method: "POST", + headers: { + Authorization: + "Bearer xxx", + Accept: "application/json", + "Content-Type": "application/json", + }, + body: JSON.stringify(payload), + } + ) + .then((response) => response.json()) + .then(console.log) + .catch(console.log); + }); + }; + + return ( + + ); +---- + +See also, link:https://developers.thoughtspot.com/docs/Enumeration_HostEvent#_getexportrequestforcurrentpinboard[HostEvent.getExportRequestForCurrentPinboard]. + +To download a Liveboard with unsaved changes as a file, see xref:report-apis-v2.adoc#transient-lb-content-report[Liveboard data with unsaved changes] in the Report APIs documentation. + + +== Fetch Answer Data API + +To get data from a saved Answer object via `/api/rest/2.0/metadata/answer/data`, you need at least view access to the saved Answer. + +The API request body must include the name or GUID of the saved Answer. + +=== Answer data request example +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/metadata/answer/data' \ + -H 'Authorization: Bearer {access-token}'\ + -H 'Accept: application/json'\ + -H 'Content-Type: application/json' \ + --data-raw '{ + "metadata_identifier": "f605dbc7-db19-450b-8613-307118f74c3c", +}' +---- + +[#pagination] +== Pagination settings for Data APIs + +When you make REST API calls to some v2 Data endpoints to query data, the API may return many rows of data in response. By default, the following parameters are set in API requests to the v2 Data API endpoints: + +[source,JSON] +---- +{ + "data_format": "COMPACT", + "record_offset": 0, + "record_size": 10 +} +---- + +[WARNING] +==== +Do not set `record_size` to `-1`. On ThoughtSpot instances with a large number of objects or users, this can lead to slow responses, excessive logging, and out-of-memory failures. Specify an explicit `record_size` and iterate through pages programmatically. +==== + +The APIs return a maximum of 100000 rows of data at any given time. If you must retrieve a higher number of rows in an API call, contact ThoughtSpot Customer Support to increase the row size limit. However, if the record size and number of rows are high, the API may take a while to fetch the data, and the request may time out. + +== Runtime overrides +The Data API endpoints and the xref:report-apis-v2.adoc[Report API endpoints] support the following runtime overrides: + +* Runtime filters +* Runtime sorting of columns +* Runtime Parameters + +=== Runtime filters +To add runtime filters, in the `runtime_filter` property, add the `col1`, `op1`, and `val1` parameters JSON key-value format: + +[source,JSON] +---- +"runtime_filter": { + "col1": "type", + "op1": "EQ", + "val1": "roasted", +} +---- + +To add additional filters, increment the number at the end of each parameter for each filter: for example, col2, op2, val2, and so on. + +[source,JSON] +---- +"runtime_filter": { + "col1": "type", + "op1": "EQ", + "val1": "roasted", + "col2": "tea", + "op2": "EQ", + "val2": "barley" +} +---- + +Some operators such as allow more than one value in the `val` parameter: + +[source,JSON] +---- + "runtime_filter": { + "col1": "tea", + "op1": "CONTAINS", + "val1": [ + "barley", + "mint" + ], + "col2": "type", + "op2": "CONTAINS", + "val2": [ + "roasted", + "loose leaves" + ] +} +---- + +For more information, see xref:runtime-filters.adoc#rtOperator[Supported runtime filter operators] and xref:runtime-filters.adoc#_rest_api_v2_0_endpoints[Apply runtime filters via REST APIs]. + +=== Runtime parameters + +To add runtime Parameters, in the `runtime_param_override` property, add the `param1, and `paramVal1` parameters JSON key-value format. The Parameter value must be defined as per the data type. For example, `Date Param` and `Date List Param` Parameters, specify Epoch time as value. + +To apply Parameter overrides on Liveboards and Answers, ensure that the Parameters are configured in the Model used for generating Liveboard visualizations and Answer. + +[source,JSON] +---- + "runtime_param_override": { + "param1": "Double List Param", + "paramVal1": 0.5 + } +---- + +To add additional Parameter overrides, increment the number at the end of each parameter: for example, paramVal2, and so on. + +[source,JSON] +---- + "runtime_param_override": { + "param1": "Double List Param", + "paramVal1": 0.5, + "param2": "Date Param", + "paramVal2": 1696932000 + } +---- + +For more information, see xref:runtime-parameters.adoc[Runtime Parameter overrides]. + +=== Runtime sort + +To sort columns on a Liveboard or Answer, define runtime sort properties in `runtime_sort` as a key-value pair in JSON format. The `runtime_sort` object allows `sortCol1` and `asc1` properties. To sort more columns, increment the number at the end of the parameter for each key: for example, `sortCol2`, `asc2`, `sortCol3`, `asc3`, and so on. + + +[source,JSON] +---- + "runtime_sort": { + "sortCol1": "sales", + "asc1": true, + "sortCol2": "region", + "asc2": false + } +---- + +For more information, see xref:runtime-sort.adoc#_rest_api_v2_0[Runtime sorting of columns]. diff --git a/modules/ROOT/pages/deprecated-features.adoc b/modules/ROOT/pages/deprecated-features.adoc index d90d833e3..39857dbe9 100644 --- a/modules/ROOT/pages/deprecated-features.adoc +++ b/modules/ROOT/pages/deprecated-features.adoc @@ -147,7 +147,7 @@ Impact on your instance:: * For new users, API calls to the `POST /api/rest/2.0/report/liveboard` endpoint for PNG exports with `include_cover_page` and `include_filter_page` will result in an error. Use the new PNG export options. //If you still have to use these options for your ThoughtSpot instance contact ThoughtSpot support to revert to these legacy settings. -For more information on PNG export, see xref:data-report-v2-api.adoc#_liveboard_report_api[Liveboard Report API]. +For more information on PNG export, see xref:report-apis-v2.adoc#_liveboard_report_api[Liveboard Report API]. Recommended action:: * We recommend transitioning to the new flow for PNG exports, as the `include_cover_page` and `include_filter_page` attributes will be removed in a future release. diff --git a/modules/ROOT/pages/data-report-v2-api.adoc b/modules/ROOT/pages/report-apis-v2.adoc similarity index 53% rename from modules/ROOT/pages/data-report-v2-api.adoc rename to modules/ROOT/pages/report-apis-v2.adoc index a73d16087..74c50cb30 100644 --- a/modules/ROOT/pages/data-report-v2-api.adoc +++ b/modules/ROOT/pages/report-apis-v2.adoc @@ -1,224 +1,22 @@ -= Data and Report APIs += Report APIs :toc: true :toclevels: 3 -:page-title: data-apis -:page-pageid: fetch-data-and-report-apis -:page-description: Data and Report APIs +:page-title: report-apis +:page-pageid: report-apis +:page-description: Report APIs -== Data APIs -ThoughtSpot provides the following REST API v2 endpoints to fetch data: +ThoughtSpot provides the following REST API v2 endpoints to download or export data as a file: -* xref:#_search_data_api[`POST /api/rest/2.0/searchdata`] to search data from a given data source. -* xref:#_fetch_liveboard_api[`POST /api/rest/2.0/metadata/liveboard/data`] to get data from a Liveboard. -* xref:#_fetch_answer_data_api[`POST /api/rest/2.0/metadata/answer/data`] to get data from a saved Answer. - -If Role-Based Access Control (RBAC) is enabled, the `DATADOWNLOADING` (Can download Data) privilege is required to use these APIs. Alternatively, if the granular data download RBAC privileges are enabled for your ThoughtSpot instance, the `CAN_DOWNLOAD_DETAILED_DATA` (Can download detailed data) is required. - -=== Search data API - -The `/api/rest/2.0/searchdata` endpoint requires you to specify the data source object ID and a query string for a successful API call. You can also define additional parameters such as `runtime_filter`, `runtime_sort`, and `runtime_param_override` to apply runtime overrides on the data set. - -==== Data source -To search data via API call, you require at least view access to the data source object. The data source object can be a Model, View, or Table. - -You can specify the data source object GUID in the `logical_table_identifier`. The search data endpoint doesn't support searching data from multiple Models, Views, or Tables in a single API request. - -To find the GUID of the Model, View, or Table, use one of the following methods: - -Get data object GUID via API:: - -Send an API request to the `/api/rest/2.0/metadata/search` endpoint with the following parameters in the metadata array: + - -+ -.**Example** -[source,JSON] ----- - "metadata": [ - { - "identifier": "my_model", - "type": "LOGICAL_TABLE" - } - ] ----- - -+ -If you don't know the exact name of the data source object, specify the metadata `type` as `LOGICAL_TABLE` in your API request, and then copy the GUID of the data object from the API response. - -Find the GUID of the data object via UI:: -. Log in to your ThoughtSpot application instance: -. Navigate to **Data workspace**. -+ ----- -https:///#/data/tables/ ----- -+ -. On the **Data workspace** > **Data objects** page, select the data object. For example, if the data source object is a Model, click **Models** and then open the Model. -. In the address bar of the web browser, note the GUID of the data source object. For example, in the following address string, the GUID is `9d93a6b8-ca3a-4146-a1a1-e908b71b963f`: -+ ----- -https:///#/data/tables/9d93a6b8-ca3a-4146-a1a1-e908b71b963f ----- - -. Copy the GUID. - -==== Search query - -include::{path}/search-query-string.adoc[] - -.**Example** -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/searchdata' \ - -H 'Authorization: Bearer {access-token} - -H 'Accept: application/json'\ - -H 'Content-Type: application/json' \ - --data-raw '{ - "query_string": "[sales][store]", - "logical_table_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", -}' ----- - -//// -==== Using tokens generated from Spotter APIs as raw data - -For every natural language query and follow-up question, Spotter APIs such as `/api/rest/2.0/ai/answer/create`, `/api/rest/2.0/ai/agent/converse/sse`, return tokens in the API response. You can use these tokens as raw data to generate an Answer from ThoughtSpot via search data API. - -===== Request example - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/searchdata' \ - -H 'Accept: application/json' \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {AUTH_TOKEN}' \ - --data-raw '{ - "query_string": "by [city], [product], [item type] = [item type].'\''jackets'\'', [region] = [region].'\''west'\'', sort by sum [sales] descending", - "logical_table_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", - "data_format": "COMPACT", - "record_offset": 0, - "record_size": 10 -}' ----- - -===== API response - -If the API request is successful, ThoughtSpot returns the Answer data for the query string sent in the API request. -//// - -=== Fetch Liveboard Data API -To get data from a Liveboard object and its visualizations via `POST /api/rest/2.0/metadata/liveboard/data` endpoint, your user account must have at least view access to the Liveboard specified in the API request. - -The API request body must include the name or GUID of the Liveboard to fetch data. To get specific visualizations from a given Liveboard, add the names or GUIDs of the visualizations in the `visualization_identifiers` array. - -==== Example -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/metadata/liveboard/data' \ - -H 'Authorization: Bearer {access-token}'\ - -H 'Accept: application/json'\ - -H 'Content-Type: application/json' \ - --data-raw '{ - "metadata_identifier": "d084c256-e284-4fc4-b80c-111cb606449a", - "data_format": "COMPACT", - "visualization_identifiers": [ - "a9655c18-9855-4a73-9e7b-ff4fb6da334b", - "bf4c9814-82c1-4ec4-b879-57eae2134cb4", - "8c46d2b6-94c7-4ba7-a628-6e74e297f973", - "f6ef5d1f-cddb-4547-8b66-af4d5f4da5ad" - ] -}' ----- - -[#transient-lb-content] -==== Liveboard data with unsaved changes - -include::{path}/transient-lb-content.adoc[] - -.**Sample browser fetch request** - -[source,TypeScript] ----- -const embedRef = useEmbedRef(); - const handleFilterChanged: MessageCallback = () => { - embedRef.current - .trigger(HostEvent.getExportRequestForCurrentPinboard) - .then((transientPinboardContent) => { - console.log(transientPinboardContent.data); - - const payload = { - metadata_identifier: "abc", - data_format: "COMPACT", - record_offset: 0, - record_size: 10, - transient_content: JSON.stringify(transientPinboardContent.data), - }; - - fetch( - `https://{ThoughtSpot-Host}/api/rest/2.0/metadata/liveboard/data`, - { - method: "POST", - headers: { - Authorization: - "Bearer xxx", - Accept: "application/json", - "Content-Type": "application/json", - }, - body: JSON.stringify(payload), - } - ) - .then((response) => response.json()) - .then(console.log) - .catch(console.log); - }); - }; - - return ( - - ); ----- - -See also, link:https://developers.thoughtspot.com/docs/Enumeration_HostEvent#_getexportrequestforcurrentpinboard[HostEvent.getExportRequestForCurrentPinboard]. - - -=== Fetch Answer Data API - -To get data from a saved Answer object via `/api/rest/2.0/metadata/answer/data`, you need at least view access to the saved Answer. - -The API request body must include the name or GUID of the saved Answer. - -==== Example -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/metadata/answer/data' \ - -H 'Authorization: Bearer {access-token}'\ - -H 'Accept: application/json'\ - -H 'Content-Type: application/json' \ - --data-raw '{ - "metadata_identifier": "f605dbc7-db19-450b-8613-307118f74c3c", -}' ----- - - -== Report APIs - -ThoughtSpot provides the following REST API v2 endpoints to fetch data: - -* xref:_liveboard_report_api[`POST /api/rest/2.0/report/liveboard`] + +* xref:#_liveboard_report_api[`POST /api/rest/2.0/report/liveboard`] + Download a Liveboard and its visualizations in PDF, PNG, CSV, or XLSX file format. * xref:#_answer_report_api[`POST /api/rest/2.0/report/answer`] + Download data from a saved Answer in PDF, PNG, CSV, or XLSX file format. -=== Liveboard Report API +[NOTE] +To retrieve data as JSON instead of downloading a file, see xref:data-apis-v2.adoc[Data APIs]. + +== Liveboard Report API To download a Liveboard report via `/api/rest/2.0/report/liveboard` API, you need at least view access to the Liveboard specified in the API request. @@ -237,7 +35,7 @@ To download a personalized view of the Liveboard, specify the view name in the ` * If the granular Role-Based Access Control (RBAC) is enabled, the `CAN_DOWNLOAD_DETAILED_DATA` (Can download detailed data) privilege is required to export in the XLSX or CSV formats, and the `CAN_DOWNLOAD_VISUALS` (Can download visuals) privilege is required for PDF or PNG exports. In this case the `DATADOWNLOADING` privilege ceases to exist. ==== -==== File Formats +=== File Formats The default `file_format` is *CSV*. @@ -252,7 +50,7 @@ For *CSV* downloads, * It does not support any additional parameters to customize the page orientation and `include_cover_page`, `include_filter_page`, logo, footer text, and page numbers. * Charts are exported as tabular data. Downloaded reports may include columns not seen in the visualization if they were used as tokens in the underlying search query. -===== Sample API payload for CSV downloads +==== Sample API payload for CSV downloads [source,cURL] ---- @@ -278,7 +76,7 @@ For *XLSX* downloads, * Charts are exported as tabular data. Downloaded reports may include columns not seen in the visualization if they were used as tokens in the underlying search query. * New pivot tables generated in .xlsx workbooks using this API endpoint retain their complete visual formatting and structural integrity. -===== Sample API payload for XLSX downloads +==== Sample API payload for XLSX downloads [source,cURL] ---- @@ -305,7 +103,7 @@ When `page_size = CONTINUOUS`, the `include_filter_page` option works to show/hi * `zoom_level` offers various download size options to suit the viewer's screen dimensions, thereby enhancing legibility. This can be set only when `page_size = CONTINUOUS`. Valid values are integers in the range of 45 and 175. -===== Sample API payload for PDF downloads +==== Sample API payload for PDF downloads [source,cURL] ---- @@ -347,7 +145,7 @@ For *PNG* downloads, you can now define ==== -===== Sample API payload for PNG downloads +==== Sample API payload for PNG downloads [source,cURL] ---- @@ -372,7 +170,7 @@ curl -X POST \ }' ---- -==== Override filters +=== Override filters If the Liveboard has filters applied, and you want to override the filters before downloading the Liveboard, you can specify the filters in the `override_filters` array. @@ -425,12 +223,12 @@ curl -X POST \ }' ---- -[#transient-lb-content] -==== Liveboard data with unsaved changes +[#transient-lb-content-report] +=== Liveboard data with unsaved changes include::{path}/transient-lb-content.adoc[] -===== Sample browser fetch request +==== Sample browser fetch request [source,JavaScript] ---- @@ -454,7 +252,7 @@ include::{path}/transient-lb-content.adoc[] See also, link:https://developers.thoughtspot.com/docs/Enumeration_HostEvent#_getexportrequestforcurrentpinboard[HostEvent.getExportRequestForCurrentPinboard]. -=== Answer Report API +== Answer Report API To download Answer data via `/api/rest/2.0/report/answer` API, you need at least view access to the saved Answer. @@ -468,7 +266,7 @@ The API supports exporting saved Answers, pinned Answers from a Liveboard, and S * If the granular Role-Based Access Control (RBAC) is enabled, the `CAN_DOWNLOAD_DETAILED_DATA` (Can download detailed data) privilege is required to export in the PDF, XLSX or CSV formats, and the `CAN_DOWNLOAD_VISUALS` (Can download visuals) privilege is required for PNG exports. In this case the `DATADOWNLOADING` privilege ceases to exist. ==== -==== Example +=== Example [source,cURL] ---- @@ -525,12 +323,12 @@ Valid range: `80%` to `500%`. You can now export the PNG of any Answer in any aspect ratio and any scaling or zoom level. Just configure, scale, and export exactly what you need. [#exportSpotterData] -==== Export data generated from Spotter APIs +=== Export data generated from Spotter APIs To export results generated from Spotter APIs such as `/api/rest/2.0/ai/answer/create`, `/api/rest/2.0/ai/agent/converse/sse`, and `/api/rest/2.0/ai/conversation/{conversation_identifier}/converse`, include the session ID and generation number in the `POST` request body. When downloading a Spotter-generated Answer, do not specify the metadata object ID, because you will be exporting the data generated from a conversation session with Spotter and not a saved Answer. -===== Request example +==== Request example [source,cURL] ---- @@ -549,12 +347,12 @@ curl -X POST \ * `generation_number` indicates the Answer generation number. * `file_format` specifies the format of the output. You can export the Spotter-generated data as PNG, CSV, XLSX, or PDF file. By default, the API exports this data in PNG file format. -===== API Response +==== API Response If the API request is successful, ThoughtSpot returns the data in the specified file format. You can download the file to use it later or import it into your application environment. //// -===== Response codes +==== Response codes [width="100%" cols="2,4"] [options='header'] |=== @@ -567,124 +365,8 @@ If the API request is successful, ThoughtSpot returns the data in the specified |=== //// -== Pagination settings for Data APIs - -When you make REST API calls to some v2 Data endpoints to query data, the API may return many rows of data in response. By default, the following parameters are set in API requests to the v2 Data API endpoints: - -[source,JSON] ----- -{ - "data_format": "COMPACT", - "record_offset": 0, - "record_size": 10 -} ----- - -[WARNING] -==== -Do not set `record_size` to `-1`. On ThoughtSpot instances with a large number of objects or users, this can lead to slow responses, excessive logging, and out-of-memory failures. Specify an explicit `record_size` and iterate through pages programmatically. -==== - -The APIs return a maximum of 100000 rows of data at any given time. If you must retrieve a higher number of rows in an API call, contact ThoughtSpot Customer Support to increase the row size limit. However, if the record size and number of rows are high, the API may take a while to fetch the data, and the request may time out. - -== Runtime overrides -The Data API endpoints support the following runtime overrides: - -* Runtime filters -* Runtime sorting of columns -* Runtime Parameters - -=== Runtime filters -To add runtime filters, in the `runtime_filter` property, add the `col1`, `op1`, and `val1` parameters JSON key-value format: - -[source,JSON] ----- -"runtime_filter": { - "col1": "type", - "op1": "EQ", - "val1": "roasted", -} ----- - -To add additional filters, increment the number at the end of each parameter for each filter: for example, col2, op2, val2, and so on. - -[source,JSON] ----- -"runtime_filter": { - "col1": "type", - "op1": "EQ", - "val1": "roasted", - "col2": "tea", - "op2": "EQ", - "val2": "barley" -} ----- - -Some operators such as allow more than one value in the `val` parameter: - -[source,JSON] ----- - "runtime_filter": { - "col1": "tea", - "op1": "CONTAINS", - "val1": [ - "barley", - "mint" - ], - "col2": "type", - "op2": "CONTAINS", - "val2": [ - "roasted", - "loose leaves" - ] -} ----- - -For more information, see xref:runtime-filters.adoc#rtOperator[Supported runtime filter operators] and xref:runtime-filters.adoc#_rest_api_v2_0_endpoints[Apply runtime filters via REST APIs]. - -=== Runtime parameters - -To add runtime Parameters, in the `runtime_param_override` property, add the `param1, and `paramVal1` parameters JSON key-value format. The Parameter value must be defined as per the data type. For example, `Date Param` and `Date List Param` Parameters, specify Epoch time as value. - -To apply Parameter overrides on Liveboards and Answers, ensure that the Parameters are configured in the Model used for generating Liveboard visualizations and Answer. - -[source,JSON] ----- - "runtime_param_override": { - "param1": "Double List Param", - "paramVal1": 0.5 - } ----- - -To add additional Parameter overrides, increment the number at the end of each parameter: for example, paramVal2, and so on. - -[source,JSON] ----- - "runtime_param_override": { - "param1": "Double List Param", - "paramVal1": 0.5, - "param2": "Date Param", - "paramVal2": 1696932000 - } ----- - -For more information, see xref:runtime-parameters.adoc[Runtime Parameter overrides]. - -=== Runtime sort - -To sort columns on a Liveboard or Answer, define runtime sort properties in `runtime_sort` as a key-value pair in JSON format. The `runtime_sort` object allows `sortCol1` and `asc1` properties. To sort more columns, increment the number at the end of the parameter for each key: for example, `sortCol2`, `asc2`, `sortCol3`, `asc3`, and so on. - - -[source,JSON] ----- - "runtime_sort": { - "sortCol1": "sales", - "asc1": true, - "sortCol2": "region", - "asc2": false - } ----- - -For more information, see xref:runtime-sort.adoc#_rest_api_v2_0[Runtime sorting of columns]. +== Pagination and runtime overrides +The Report API endpoints support the same runtime overrides as the Data API endpoints. For more information, see xref:data-apis-v2.adoc#_runtime_overrides[Runtime overrides]. +For information about pagination, record size, and the maximum row limit that apply to the Data API endpoints, see xref:data-apis-v2.adoc#pagination[Pagination settings for Data APIs]. diff --git a/modules/ROOT/pages/rest-apiv2-changelog.adoc b/modules/ROOT/pages/rest-apiv2-changelog.adoc index 22e0cfcaf..bd72e1316 100644 --- a/modules/ROOT/pages/rest-apiv2-changelog.adoc +++ b/modules/ROOT/pages/rest-apiv2-changelog.adoc @@ -217,7 +217,7 @@ Automatic file naming:: The API now automatically names exported files based on the Answer title and appends the correct file extension (`.png`, `.pdf`, `.csv`, or `.xlsx`). Contact ThoughtSpot Support to enable these settings for PNG downloads on your ThoughtSpot instance. -For more information, see xref:data-report-v2-api.adoc#_answer_report_api[Answer report API documentation]. +For more information, see xref:report-apis-v2.adoc#_answer_report_api[Answer report API documentation]. === Share metadata API: Collections support [beta betaBackground]^Beta^ @@ -288,7 +288,7 @@ The `POST /api/rest/2.0/report/liveboard` API endpoint enhances the PDF download * `"page_size": "CONTINUOUS"` for a seamless PDF export that matches the full length of your Liveboard. Unlike the A4 format, which introduces forced page breaks between visualizations, this continuous flow maintains your exact design and intended layout. * `zoom_level` offers various download size options to suit the viewer's screen dimensions, thereby enhancing legibility. This can be set only when `page_size` is specified as `CONTINUOUS`. -For more information, see xref:data-report-v2-api.adoc#_liveboard_report_api[Liveboard Report API documentation]. +For more information, see xref:report-apis-v2.adoc#_liveboard_report_api[Liveboard Report API documentation]. === Metadata search API enhancements @@ -445,7 +445,7 @@ The `same_as_parent` parameter specifies if the configuration should inherit set === Liveboard Report API enhancements You can now download Liveboard reports in the CSV and XLSX formats through the `POST /api/rest/2.0/report/liveboard` API endpoint. Both these options are Early Access features. -For more information, see xref:data-report-v2-api.adoc[Data and Report APIs]. +For more information, see xref:report-apis-v2.adoc[Report APIs]. === Email customization API enhancements @@ -752,7 +752,7 @@ In addition to these parameters, you can also define the following properties fo * `image_scale` * `include_header` -For more information, see xref:data-report-v2-api.adoc#_liveboard_report_api[Liveboard Report API]. +For more information, see xref:report-apis-v2.adoc#_liveboard_report_api[Liveboard Report API]. === REST API Java SDK @@ -794,7 +794,7 @@ Filters metadata objects by the user-defined object ID. This parameter returns d === Report APIs The Liveboard export API (`/api/rest/2.0/report/liveboard`) now allows overriding filters applied to a Liveboard. The `override_filters` array allows specifying several types of filters and updates the Liveboard data during export. -For more information, see xref:data-report-v2-api.adoc#_override_filters[Override filters]. +For more information, see xref:report-apis-v2.adoc#_override_filters[Override filters]. == Version 10.6.0.cl, March 2025 diff --git a/modules/ROOT/pages/spotter-agent-apis.adoc b/modules/ROOT/pages/spotter-agent-apis.adoc index 5ea2587af..caea17b5e 100644 --- a/modules/ROOT/pages/spotter-agent-apis.adoc +++ b/modules/ROOT/pages/spotter-agent-apis.adoc @@ -1083,7 +1083,7 @@ If the conversation session is not found or has expired, the API returns an erro [#process_results] == Process results generated from a conversation session -To export or download the Answer data generated by the Spotter APIs, use the xref:data-report-v2-api.adoc#exportSpotterData[Answer report] API. +To export or download the Answer data generated by the Spotter APIs, use the xref:report-apis-v2.adoc#exportSpotterData[Answer report] API. The `session_id` and `gen_no` values from the `answer` event metadata are required to identify the answer to export. @@ -1106,7 +1106,7 @@ The `file_format` parameter accepts `PDF`, `PNG`, `CSV`, or `XLSX`. [NOTE] ==== -Using tokens generated by the Spotter API in a xref:data-report-v2-api.adoc#_search_data_api[Search Data API] request can return invalid column errors, because these tokens may reference formulas or columns not present in the data model. Instead, use the xref:data-report-v2-api.adoc#exportSpotterData[Answer report] API and include the session ID and generation number obtained from the Spotter API in your API request to retrieve the data. +Using tokens generated by the Spotter API in a xref:data-apis-v2.adoc#_search_data_api[Search Data API] request can return invalid column errors, because these tokens may reference formulas or columns not present in the data model. Instead, use the xref:report-apis-v2.adoc#exportSpotterData[Answer report] API and include the session ID and generation number obtained from the Spotter API in your API request to retrieve the data. ==== diff --git a/modules/ROOT/pages/whats-new.adoc b/modules/ROOT/pages/whats-new.adoc index 56a89557d..c0cec74b8 100644 --- a/modules/ROOT/pages/whats-new.adoc +++ b/modules/ROOT/pages/whats-new.adoc @@ -443,7 +443,7 @@ Current period inclusion in rolling date filters:: The rolling date filters with the **Last ** and **Next ** filter types support including current period. Developers can disable, show, or hide this option using `isThisPeriodInDateFiltersEnabled` or `Action.IncludeCurrentPeriod`. Liveboard PNG export:: -The PNG export workflow in the `/api/rest/2.0/report/liveboard` REST API is enhanced to provide high-resolution PNG files. The legacy PNG workflow is deprecated in 26.4.0.cl. For more information about breaking changes and deprecation guidelines, see xref:deprecated-features.adoc[Deprecation announcements]. For information about the new PNG download workflow, see xref:data-report-v2-api.adoc#_liveboard_report_api[Liveboard report API documentation]. +The PNG export workflow in the `/api/rest/2.0/report/liveboard` REST API is enhanced to provide high-resolution PNG files. The legacy PNG workflow is deprecated in 26.4.0.cl. For more information about breaking changes and deprecation guidelines, see xref:deprecated-features.adoc[Deprecation announcements]. For information about the new PNG download workflow, see xref:report-apis-v2.adoc#_liveboard_report_api[Liveboard report API documentation]. --- diff --git a/src/components/SecondaryHeader/index.tsx b/src/components/SecondaryHeader/index.tsx index 42361b8d3..e472489b4 100644 --- a/src/components/SecondaryHeader/index.tsx +++ b/src/components/SecondaryHeader/index.tsx @@ -102,7 +102,7 @@ export const CATEGORY_PAGEIDS: Record = { 'collections', 'connections', 'connection-config', 'rest-apiv2-getstarted', 'api-authv2', 'rest-apiv2-js', 'rest-apiv2-search', 'rest-apiv2-users-search', 'rest-apiv2-groups-search', 'rest-apiv2-metadata-search', - 'fetch-data-and-report-apis', 'rest-api-sdk', 'rest-api-sdk-typescript', 'rest-api-sdk-java', + 'fetch-data-and-report-apis', 'report-apis', 'rest-api-sdk', 'rest-api-sdk-typescript', 'rest-api-sdk-java', 'rest-api-getstarted', 'api-auth-session', 'catalog-and-audit', 'rest-api-pagination', 'runtime-sort', 'v1v2-comparison', 'graphql-guide', 'webhooks-rest-api', 'rest-v2-changelog', 'rest-v1-changelog', diff --git a/src/configs/doc-configs.js b/src/configs/doc-configs.js index 19ebabe2b..d5e37c73f 100644 --- a/src/configs/doc-configs.js +++ b/src/configs/doc-configs.js @@ -117,7 +117,7 @@ module.exports = { 'rest-api-v2', 'rest-apiv2-reference', 'restV2-playground', 'rest-apiv2-getstarted', 'api-authv2', 'rest-apiv2-js', 'rest-apiv2-search', 'rest-apiv2-users-search', 'rest-apiv2-groups-search', - 'rest-apiv2-metadata-search', 'fetch-data-and-report-apis', + 'rest-apiv2-metadata-search', 'fetch-data-and-report-apis', 'report-apis', 'rest-api-sdk', 'rest-api-sdk-typescript', 'rest-api-sdk-java', 'rest-api-getstarted', 'api-auth-session', 'catalog-and-audit', 'rest-api-pagination', 'runtime-sort', 'v1v2-comparison', From b68e57d14297bfbb55d60575aa81dc6c03efea38 Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Wed, 12 Aug 2026 12:31:20 +0530 Subject: [PATCH 054/154] Removed trailing beta msg for Coll --- modules/ROOT/pages/collections.adoc | 5 ----- 1 file changed, 5 deletions(-) diff --git a/modules/ROOT/pages/collections.adoc b/modules/ROOT/pages/collections.adoc index 4a5cf27ca..53dfbd7a6 100644 --- a/modules/ROOT/pages/collections.adoc +++ b/modules/ROOT/pages/collections.adoc @@ -9,11 +9,6 @@ ThoughtSpot now provides REST APIs that enable developers to organize different ThoughtSpot objects into an organizational container called *Collections*. These objects can be Liveboards, Answers, data models, tables, and even other Collections. Collections provide a powerful way to manage your data assets, making discovery and collaboration easier, while ensuring the integrity of embedded workflows. -[NOTE] -==== -The Collections APIs are in Beta and disabled by default on ThoughtSpot instances. To enable these APIs on your instance, contact ThoughtSpot Support. -==== - == Before you begin * For REST API v2 operations, the Org context is determined based on the authentication token used in your API requests. Ensure you log in to the appropriate Org context from which you want to send API requests. From 04d98004e77c7d4b6ca83d09fceef09c5d4d6ecc Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Wed, 12 Aug 2026 15:23:41 +0530 Subject: [PATCH 055/154] review changes --- modules/ROOT/pages/tml.adoc | 151 +++++++++++++++++++++++++++++++++++- 1 file changed, 149 insertions(+), 2 deletions(-) diff --git a/modules/ROOT/pages/tml.adoc b/modules/ROOT/pages/tml.adoc index 127583da2..0cdafe3c1 100644 --- a/modules/ROOT/pages/tml.adoc +++ b/modules/ROOT/pages/tml.adoc @@ -147,6 +147,154 @@ Creates an import TML tasks and processes TMLs asynchronously * +++POST /api/rest/2.0/metadata/tml/async/status+++ + Fetches status of import tasks +=== Best practices for async TML import + +Use the following guidelines to configure and manage async TML import tasks effectively. + +==== Choose the right import policy + +[width="100%", cols="1,3,2,2"] +[options='header'] +|==== +|Policy|Behavior|Recommended use case|Limits and risks + +|`ALL_OR_NONE` +|All objects are validated and saved in a single database write. +If any object fails, no objects are written. +|Small, tightly coupled object sets requiring atomicity. +|Limit to approximately 50 TML objects per task. +Exceeding this risks OOM errors or database write failures. +Liveboard size affects this limit; Liveboards averaging approximately 30 visualizations are a useful sizing baseline. + +|`VALIDATE_ONLY` +|Objects are validated in memory. +No changes are written to the database. +|Pre-import validation before committing to a production import. +|All changes accumulate in memory. +Very large tasks risk OOM errors. + +|`PARTIAL` +|Objects that pass validation are written. +Failed objects are skipped without dropping subentities. +If a subentity (such as a visualization) fails, the parent object (such as a Liveboard) also fails and is not written. +|Large-scale migrations where some failures are expected. +Resubmit failed objects as a new task after fixing errors. +|Recommended policy for large imports. +Objects are written incrementally, reducing memory pressure. + +|`PARTIAL_OBJECT` +|Objects that pass validation are written. +If a subentity (visualization, join, or RLS rule) fails, the parent object is written with a warning and the failed subentity is dropped. +|Large-scale migrations where pipeline continuity matters more than completeness. +|Recommended when a missing visualization or dropped join is acceptable in the target environment. +|==== + +[NOTE] +==== +If you use custom scripts to batch imports with `ALL_OR_NONE`, the net result across batches is effectively the same as `PARTIAL` behavior—some batches succeed and some fail. +Use the `PARTIAL` policy directly for large-volume imports rather than scripting `ALL_OR_NONE` batches. +==== + +[IMPORTANT] +==== +Use `PARTIAL` or `PARTIAL_OBJECT` for large import operations. +`ALL_OR_NONE` and `VALIDATE_ONLY` process all objects in memory or in a single database transaction, which can cause OOM errors on large tasks. +==== + +==== Size your import tasks + +* For `ALL_OR_NONE` and `VALIDATE_ONLY`, limit tasks to approximately 50 TML objects. +There is no hard code limit, but larger tasks risk OOM errors or failed database writes. +The safe upper bound depends on Liveboard complexity. +Liveboards with an average of approximately 30 visualizations each provide a reasonable sizing baseline. + +* For `PARTIAL` and `PARTIAL_OBJECT`, there is no per-task object limit enforced by the API. +These policies write objects incrementally and are appropriate for large migration workloads. + +* The API payload size limit is 500 MB per request (infrastructure limit). +Contact ThoughtSpot Support if your use case requires a larger limit. + + +==== Avoid parallel imports of the same object + +Never submit tasks that include the same object in more than one active task simultaneously. +Concurrent writes to the same object cause a version conflict, and one of the tasks will fail. + +Design your import pipeline so that each object appears in at most one active import task at a time. +Sequence tasks, do not parallelize them across the same objects. + +==== Monitor the task queue and status + +The async import queue supports a maximum of 100 concurrent tasks. +Submitting more than 100 tasks at once causes the excess tasks to be rejected with a `FAILED` status immediately. + +Poll the `POST /api/rest/2.0/metadata/tml/async/status` endpoint to check task status. + +[width="100%", cols="1,4"] +[options='header'] +|==== +|Status value|Description + +|`IN_QUEUE` +|The task is waiting to be processed. +The queue limit is 100 concurrent tasks. +Tasks submitted beyond the limit are rejected immediately with status `FAILED`. + +|`IN_PROGRESS` +|The task is being processed. + +|`COMPLETED` +|The task processing is complete. +`COMPLETED` does not mean every object imported successfully. +Individual objects within the task have their own statuses. +Inspect per-object status in the response to identify failures. + +|`FAILED` +|The task failed. +This could be due to multiple reasons such as - the queue was full at submission time, a policy-level failure occurred, or an unrecoverable error was encountered during processing. +|==== + +*Recommended polling intervals:* + +The status API enforces a rate limit of 100 requests per minute. +Exceeding this limit returns an error. + +For practical use: + +* For small tasks, poll no more frequently than every 30 seconds. +* For large tasks, a polling interval of 1 minute is recommended, as larger tasks take proportionally longer to complete. + +==== Use API parameters correctly + +The following parameters in `POST /api/rest/2.0/metadata/tml/async/import` require careful use: + +`create_new`:: +Set `create_new: true` only when you want to create objects with new GUIDs, not update existing objects. +Setting this parameter on objects that already exist creates duplicates. +Do not set this parameter unless you are certain that new objects should be created. + +`skip_diff_check`:: +Set `skip_diff_check: true` only when you want to force a re-import of a TML file that has not changed since the previous import. +By default, ThoughtSpot identifies unchanged objects and skips them to reduce import time. +Enable this parameter only when unchanged files must be explicitly reprocessed. + +`enable_large_metadata_validation`:: +Set to `true` if the database contains multiple thousands of tables. +When enabled, ThoughtSpot validates schema one table at a time, which helps circumvent metadata fetching limitations of the Cloud Data Warehouse (CDW). +Default: `false`. + +`enable_personalized_view_upsert`:: +Set to `true` to enable update and insert of personalized views in a Liveboard during TML import. +When enabled, personalized views are preserved or created as part of the import operation instead of being discarded. +Default: `false`. + + +==== Schedule large imports during off-peak hours + +Large TML migrations can temporarily increase system resource usage. +Schedule bulk async imports during off-peak hours to reduce the risk of impacting users who are actively using the cluster. + + === Schedule import tasks You can import TML objects asynchronously by scheduling TML import tasks via `POST` request to POST `/api/rest/2.0/metadata/tml/async/import` API endpoint. You can send the following parameters in the API request body: @@ -177,7 +325,7 @@ Imports objects that validate successfully and skips the objects that do not val |`skip_diff_check` + __Optional__ -|__Boolean__. When set to `true`, skips the diff check before processing TML objects for import. By default, ThoughtSpot compares each TML object against its last imported version and skips objects that have not changed, which reduces unnecessary reimports. Set to `true` to bypass this check and reimport all objects regardless of whether they have changed. |`false` +|__Boolean__ |`false` |`enable_large_metadata_validation` + __Optional__ |__Boolean__. Available from 10.5.0.cl. Enables validation for large metadata objects. Set to `true` if the database contains multiple thousands of tables. When enabled, it allows for schema validation of one table at a time and helps circumvent the metadata fetching limitations of the Cloud Data Warehouse (CDW). @@ -546,4 +694,3 @@ ThoughtSpot instances act as a constantly running service, so deployment only in But this changed with the link:https://developers.thoughtspot.com/docs/git-integration[Git integration] feature. ThoughtSpot now allows you to connect your deployment instance to a Git repository, push TML files to CI/CD pipelines, and deploy commits from your Git repository to your production environment. However, ThoughtSpot’s Git integration does not support moving objects within the same Org or application instance. For example, it does not support moving objects in an environment where xref:multitenancy-without-orgs[multi-tenancy is implemented using groups]. /// - From 70c01c946b5e96f66ac4dde57038c88bce325789 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Fri, 14 Aug 2026 09:03:03 +0530 Subject: [PATCH 056/154] SCAL-330028 --- modules/ROOT/pages/authentication.adoc | 24 ++++++++++++------- modules/ROOT/pages/rest-api-v2-reference.adoc | 2 +- 2 files changed, 16 insertions(+), 10 deletions(-) diff --git a/modules/ROOT/pages/authentication.adoc b/modules/ROOT/pages/authentication.adoc index eb70d5729..106bf6c27 100644 --- a/modules/ROOT/pages/authentication.adoc +++ b/modules/ROOT/pages/authentication.adoc @@ -556,9 +556,13 @@ curl -X POST \ If `auto_create` is set to `true` and the username specified in the API request already exists in ThoughtSpot, the `/api/rest/2.0/auth/token/custom` API does not update user properties such as display name, email, Org, or group assignments. ==== -=== Retrieving token information +=== Generating a session token +To generate a new authentication token for an existing authenticated session, send a `GET` request to `/api/rest/2.0/auth/session/token`. This endpoint mints a fresh bearer token valid for 24 hours. It does not return the token currently held by the caller's session, but issues a new token derived from the authenticated session context. -To get the authentication token assigned to the current session of the logged-in user, send a request to `/api/rest/2.0/auth/session/token`. You can also use this API to get the token issued for the logged-in user for trusted authentication. +[NOTE] +==== +Use this endpoint when your integration needs a new token without requiring the user to re-authenticate. If you need a token with a specific expiry or security scope, use the `POST /api/rest/2.0/auth/token/full`, `POST /api/rest/2.0/auth/token/custom`, or `POST /api/rest/2.0/auth/token/object` endpoints instead. +==== ==== Example request @@ -572,15 +576,17 @@ curl -X GET \ ==== Example response +If the API request is successful, ThoughtSpot returns a new authentication token. The `expiration_time_in_millis` value reflects the 24-hour validity of the newly issued token from the time of the request. + [source,JSON] ---- - { - "token": "{AUTH_TOKEN}", - "creation_time_in_millis":1704471154477, - "expiration_time_in_millis":1704557554477, - "valid_for_user_id":"59481331-ee53-42be-a548-bd87be6ddd4a", - "valid_for_username":"tsadmin" - } +{ + "token": "{AUTH_TOKEN}", + "creation_time_in_millis": 1704471154477, + "expiration_time_in_millis": 1704557554477, + "valid_for_user_id": "59481331-ee53-42be-a548-bd87be6ddd4a", + "valid_for_username": "tsadmin" +} ---- === Revoking a token diff --git a/modules/ROOT/pages/rest-api-v2-reference.adoc b/modules/ROOT/pages/rest-api-v2-reference.adoc index 65bf32f9a..b55eed3cf 100644 --- a/modules/ROOT/pages/rest-api-v2-reference.adoc +++ b/modules/ROOT/pages/rest-api-v2-reference.adoc @@ -134,7 +134,7 @@ Gets session information for the currently logged-in user. + ThoughtSpot Software:__ 9.0.1.sw or later __ a| +++Try it out+++ |`GET /api/rest/2.0/auth/session/token` + -Gets the authentication token used by the currently logged-in user. +Generates a new bearer token from an existing authenticated session. |ThoughtSpot Cloud: __9.4.0.cl or later__ + ThoughtSpot Software: __9.5.1.sw or later__ a| +++Try it out +++ From 64b07357e22d1512ad59c9797a4cce518946c99d Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Fri, 14 Aug 2026 09:17:20 +0530 Subject: [PATCH 057/154] SCAL-332127 --- modules/ROOT/pages/security-settings.adoc | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/modules/ROOT/pages/security-settings.adoc b/modules/ROOT/pages/security-settings.adoc index df7e65ca1..a0a1a3131 100644 --- a/modules/ROOT/pages/security-settings.adoc +++ b/modules/ROOT/pages/security-settings.adoc @@ -316,6 +316,7 @@ curl -X POST \ }' ---- +//// [#custom-app-schemes] ==== Allow custom app schemes for mobile and hybrid embeds If you are embedding ThoughtSpot in a mobile or hybrid application built with frameworks such as Capacitor or Ionic, your application may use a custom URL scheme (for example, `capacitor://localhost` or `ionic://localhost`) rather than an `https://` origin. @@ -405,6 +406,7 @@ init({ .then(d => d.token), }); ---- +//// [#csp-cors-hosts] ==== Domain name format for CSP and CORS configuration @@ -456,11 +458,11 @@ If your domain URL has a non-standard port, for example `mysite.com:8080`, make |[tag greenBackground tick]#✓# Supported |[tag greenBackground tick]#✓# Supported 2*|[tag greenBackground tick]#✓# Supported -|URLs with custom schemes such as: + -`capacitor://localhost` + -`ionic://localhost` +//|URLs with custom schemes such as: + +//`capacitor://localhost` + +//`ionic://localhost` -|[tag greenBackground tick]#✓# Supported |[tag greenBackground tick]#✓# Supported a|[tag greenBackground tick]#✓# Supported |[tag greenBackground tick]#✓# Supported +//|[tag greenBackground tick]#✓# Supported |[tag greenBackground tick]#✓# Supported a|[tag greenBackground tick]#✓# Supported |[tag greenBackground tick]#✓# Supported |Wildcard (`\*`) , (`.*`) for domain URL + |[tag greenBackground tick]#✓# Supported |[tag greenBackground tick]#✓# Supported a|[tag orangeBackground tick]#✓# Partial support + From 115b79311131cf79d65376b24f3b7ec1ac41fd99 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Fri, 14 Aug 2026 14:56:20 +0530 Subject: [PATCH 058/154] removed beta label --- modules/ROOT/pages/spotter-ai-memory-api.adoc | 2 -- 1 file changed, 2 deletions(-) diff --git a/modules/ROOT/pages/spotter-ai-memory-api.adoc b/modules/ROOT/pages/spotter-ai-memory-api.adoc index ce4546424..0c87f4f04 100644 --- a/modules/ROOT/pages/spotter-ai-memory-api.adoc +++ b/modules/ROOT/pages/spotter-ai-memory-api.adoc @@ -7,8 +7,6 @@ :page-description: Use the AI memory REST API v2 endpoints to export and import Spotter memory across ThoughtSpot environments. :keywords: Spotter memory, AI memory, memory migration, memory export, memory import, Spotter memory, REST API -[beta betaBackground]#Beta# - ThoughtSpot provides public REST API v2 endpoints to import and export memory for the following purposes: * To promote validated Spotter knowledge from a development environment to production. From 09c2bcad2882d3f37900424b9dd3132d164ea90d Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Fri, 14 Aug 2026 16:50:07 +0530 Subject: [PATCH 059/154] SCAL-331857/SCAL-331862 fixes --- .../pages/mcp-connect-custom-chatbot.adoc | 113 +++++++++++++++++ modules/ROOT/pages/mcp-server-changelog.adoc | 12 ++ .../pages/mcp-tool-reference-spotter3.adoc | 117 ++++++++++++++++-- 3 files changed, 229 insertions(+), 13 deletions(-) diff --git a/modules/ROOT/pages/mcp-connect-custom-chatbot.adoc b/modules/ROOT/pages/mcp-connect-custom-chatbot.adoc index 2b78d3cf7..60d722554 100644 --- a/modules/ROOT/pages/mcp-connect-custom-chatbot.adoc +++ b/modules/ROOT/pages/mcp-connect-custom-chatbot.adoc @@ -161,6 +161,119 @@ The above example: * Sends the required headers with the authentication token and ThoughtSpot host URL in MCP requests. * Wraps the MCP client as a tool and passes it into `GoogleGenAI` so Gemini can call ThoughtSpot tools as part of answering a user's query. + +[#accessing-full-tool-responses] +== Accessing full tool responses + +By default, Spotter's MCP tools return a simplified response optimized for host agent understanding: step headings and thinking narration while Spotter works, any clarifications or caveats it raises, and the answer as a title, search query, embeddable `iframe_url`, and an `answer_id` you can save to a dashboard. +For most integrations, this is the right balance of relevant context without unnecessary token use. + +Some integrations need to display granular metadata about Spotter's internal tool calls, such as the columns in the data model used to answer the question or the details behind fetching memory. +For those cases only, you can enable the full response to receive the raw event stream. +Enabling it is a deliberate tradeoff: you take on higher token costs on every turn and take on work the default response does for you. +Use the default unless you have a specific requirement the default cannot meet. + +=== Default vs. full response + +[cols="2,3,3", options="header"] +|==== +||Default response + +(optimized for agent understanding)|Full response + +(higher token costs) + +|Progress and narration +|Step headings, thinking narration, clarifications, and caveats +|Same + +|The answer +|Title, search query, TML tokens, embeddable `iframe_url`, `answer_id` +|Title, search query, TML tokens, plus raw metadata — no preconstructed `iframe_url`; you build it yourself + +|Additional metadata +|Not included +|Formulas, parameters, subqueries, chart type, data source ID + +|Context cost +|Lower +|Meaningfully higher — the full metadata payload is sent on every `get_session_updates` response +|==== + +Neither response includes the underlying result data. In both cases, values are rendered inside the visualization itself. + +=== When to use it + +* *Default response (recommended)* — the user reads the answer from the visualization. +Start here if you are unsure. You can switch to the full response later without changing your session or message flow, because only the content of the updates changes. + +* *Full response* — use when your agent needs to explain the analysis behind the answer — for example, full tool call metadata, memories used, and dataset instructions referenced — so users can confirm their question was interpreted correctly. + +[NOTE] +==== +The full response's metadata — token breakdown, formulas, parameters, subqueries, and more — is sent with every `get_session_updates` response. +In longer conversations or high-volume integrations, this adds substantial extra token usage compared to the default response. +==== + +=== Enabling the full response + +Add `enable-raw-session-updates=true` to your MCP endpoint URL: + +Bearer token MCP endpoint: +[source] +---- +https://agent.thoughtspot.app/token/mcp?api-version=latest&enable-raw-session-updates=true +---- + +OAuth-authenticated MCP endpoint: +[source] +---- +https://agent.thoughtspot.app/mcp?api-version=latest&enable-raw-session-updates=true +---- + +=== Constructing the answer iframe yourself + +With the full response enabled, the raw answer event does not include a preconstructed `iframe_url`. +Build it from fields in the event's `metadata` object. + +Sample raw answer event: + +[source,json] +---- +{ + "id": "qiZ_1idPqVFr", + "type": "answer", + "group_id": "33bhxx6PYH1X", + "metadata": { + "sage_query": "top 10 [product] sort by [sales]", + "session_id": "a5174918-6db0-4214-a0fc-f46da38851c4", + "gen_no": 2, + "transaction_id": "2a5f389c-ba37-447a-85cb-1b43d1d77a69", + "generation_number": 1, + "tml_phrases": [ + "top 10 [product] sort by [sales]" + ], + "title": "Top 10 products by sales", + "worksheet_id": "cd252e5c-b552-49a8-821d-3eadaa049cca", + "type": "thinking" + }, + "title": "Top 10 products by sales" +} +---- + +Construct the `iframe_url` from the metadata fields: + +[source,javascript] +---- +const iframeUrl = + `${clusterUrl}/?tsmcp=true#/embed/conv-assist-answer` + + `?sessionId=${evt.metadata.session_id}` + + `&genNo=${evt.metadata.gen_no}` + + `&acSessionId=${evt.metadata.transaction_id}` + + `&acGenNo=${evt.metadata.generation_number}`; +---- + +For the complete event schema, see the xref:spotter-agent-apis.adoc#_api_response_2[Spotter Agent API, window=_blank]. + + == Verifying the integration To verify the integration: diff --git a/modules/ROOT/pages/mcp-server-changelog.adoc b/modules/ROOT/pages/mcp-server-changelog.adoc index 9fad5a7c1..e91d4c839 100644 --- a/modules/ROOT/pages/mcp-server-changelog.adoc +++ b/modules/ROOT/pages/mcp-server-changelog.adoc @@ -36,12 +36,24 @@ a| a| +[discrete] +==== Step headings in `get_session_updates` responses +Spotter now reports each step it works through while processing a question. +`get_session_updates` returns these as `session_update` objects with `type: "step_notification"` and a short heading in the `text` field, such as `Searching data models` or `Running query`. For more information, see xref:mcp-tool-reference-spotter3.adoc#get_session_updates[get_session_updates response]. + +--- + +[discrete] +==== Full tool response via URL flag +You can now receive the raw Spotter event stream from `get_session_updates` by appending `enable-raw-session-updates=true` to your MCP endpoint URL. The full response includes granular metadata about Spotter's internal tool calls, such as the columns in the data model used to answer the question, formulas, parameters, and subqueries. For guidance on when to use the full response and how to enable it, see xref:mcp-connect-custom-chatbot.adoc#accessing-full-tool-responses[Accessing full tool responses]. For the response format reference, see xref:mcp-tool-reference-spotter3.adoc#full-response[Full response (raw event stream)]. + [discrete] ==== ThoughtSpot skill for skill-aware LLM clients A companion skill, `analyzing-data-with-thoughtspot` is now available for LLM clients that support skills, such as Claude. Install the skill alongside the ThoughtSpot Spotter MCP Server to improve how the client orchestrates ThoughtSpot MCP tools, including smarter routing of data questions, real-time progress narration during polling, and surfacing ThoughtSpot-generated visualization links instead of regenerating charts. For more information, see xref:mcp-server-client-connection.adoc#_using_the_thoughtspot_skill_with_skill_aware_clients[Using the ThoughtSpot skill with skill-aware clients]. + |==== == July 2026 diff --git a/modules/ROOT/pages/mcp-tool-reference-spotter3.adoc b/modules/ROOT/pages/mcp-tool-reference-spotter3.adoc index b2a21dbd5..622c6ca25 100644 --- a/modules/ROOT/pages/mcp-tool-reference-spotter3.adoc +++ b/modules/ROOT/pages/mcp-tool-reference-spotter3.adoc @@ -161,8 +161,29 @@ call_mcp_tool( -- === Response +Each poll returns a wrapper object with an `is_done` flag and a `session_updates` array. Session updates stream across multiple polling calls. Accumulate them all before rendering the final answer. -Poll returning intermediate updates with the "is_thinking" response: +`session_updates` objects use three `type` values: + +[cols="1,1,3", options="header"] +|==== +|Type|`is_thinking`|Description + +|`step_notification`|`true` +|A short heading announcing the step Spotter is about to start, such as `Searching data models` or `Running query`. +Step headings arrive as soon as Spotter begins each step, before the narration text for that step. +Render these immediately so the user sees progress in real time. + +|`text_chunk`|`true` (thinking) or `false` (final) +|A fragment of Spotter's narration. Concatenate chunks to form the complete narration string. +When `is_thinking` is `false`, the chunk is part of the final answer narration, not an intermediate thinking step. + +|`answer`|`false` +|The analytical result. Contains a title, the ThoughtSpot search query used, an embeddable `iframe_url`, and an `answer_id` for creating dashboards. +Exactly one `answer` update is present per question. +|==== + +Poll returning intermediate updates: [source,json] ---- @@ -171,14 +192,19 @@ Poll returning intermediate updates with the "is_thinking" response: "session_updates": [ { "is_thinking": true, - "type": "text-chunk", - "text": "Let me look at your sales data by region..." + "type": "step_notification", + "text": "Searching data models" + }, + { + "is_thinking": true, + "type": "text_chunk", + "text": " to find the most relevant dataset for your question..." } ] } ---- -Poll returning final updates: +Poll returning the final answer: [source,json] ---- @@ -186,27 +212,38 @@ Poll returning final updates: "is_done": true, "session_updates": [ { - "is_thinking": false, - "type": "text-chunk", - "text": "Data broken down by region..." + "is_thinking": true, + "type": "step_notification", + "text": "Running query" + }, + { + "is_thinking": true, + "type": "text_chunk", + "text": "Running the query against the sales data model..." }, { "is_thinking": false, - "type": "text", + "type": "text_chunk", "text": "I'm interpreting 'last quarter' as Q4 2025 (October–December), based on a fiscal year starting in April." }, { "is_thinking": false, "type": "answer", - "answer_title": "Total Sales by Region — Q4 2025", - "answer_query": "total sales by region last quarter", - "iframe_url": "https://your-instance.thoughtspot.cloud/embed/...", - "answer_id": "answer-guid-xyz789" + "answer_id": "{\"session_id\":\"1a3d...\",\"gen_no\":2}", + "answer_title": "Total sales by region", + "answer_data_source_id": "cd252e5c-...", + "answer_query": "[sales] [region]", + "iframe_url": "https://your-instance.thoughtspot.cloud/?tsmcp=true#/embed/conv-assist-answer?..." } ] } ---- +[NOTE] +==== +The `step_notification` type was introduced alongside the default response format. Step headings always arrive before the narration text for that step. +==== + === Handling streamed responses Spotter queries are processed asynchronously and streamed in real time. This means the full response is never contained in a single `get_session_updates` call. @@ -219,7 +256,61 @@ A typical response sequence might look like: . Intermediate conclusions: partial results or contextual notes before the final answer. . The final answer: one or more `answer` updates containing the visualization title, the underlying query, and the embeddable iframe URL. -This means a complete response might span 5–20+ `get_session_updates` calls and contain many `session_update` objects before `is_done` becomes `true`. All of this content — the thinking, the narration, and the final answer — should be accumulated and presented together to give the user the full picture. +This means a complete response might span 5–20+ `get_session_updates` calls and contain many `session_update` objects before `is_done` becomes `true`. All of this content, the thinking, the narration, and the final answer, should be accumulated and presented together to give the user the full picture. + + +[#full-response] +=== Full response (raw event stream) + +By default, `get_session_updates` returns a simplified response optimized for host agent understanding. +For integrations that need granular metadata about Spotter's internal tool calls, you can enable the full raw event stream. + +For guidance on when to use the full response and how to enable it, see xref:mcp-connect-custom-chatbot.adoc#accessing-full-tool-responses[Accessing full tool responses]. + +==== Default response format + +Three update types. Flat, fixed keys. `is_thinking` is the top-level flag that distinguishes intermediate reasoning from the final answer. + +[source,json] +---- +{"is_thinking":true,"type":"step_notification","text":"Searching for Datasets"} +{"is_thinking":true,"type":"text_chunk","text":" to find the most relevant dataset..."} +{"is_thinking":false,"type":"answer", + "answer_id":"{\"session_id\":\"1a3d...\",\"gen_no\":2}", + "answer_title":"Total sales by region", + "answer_data_source_id":"cd252e5c-...", + "answer_query":"[sales] [region]", + "iframe_url":"https://your-instance.thoughtspot.cloud/?tsmcp=true#/embed/conv-assist-answer?..."} +---- + +==== Full response format (raw upstream events) + +When `enable-raw-session-updates=true` is appended to your MCP endpoint URL, `get_session_updates` returns the raw Spotter event stream. +The full response does not include a preconstructed `iframe_url`. You must build it yourself. For guidance, see xref:mcp-connect-custom-chatbot.adoc#accessing-full-tool-responses[Accessing full tool responses]. + +[source,json] +---- +{"type":"ack","node_id":"pvzWZ8wdaL0w"} +{"type":"conv_title","title":"Total revenue by region","conv_id":"iZ87F742SMkA"} +{"type":"notification","group_id":"5aOOckJ31v8d","code":"TOOL_CALL_NOTIFICATION", + "metadata":{"type":"thinking","tool_name":"search_datasets", + "tool_args":{"keywords":["revenue","region","sales"]}, + "tool_code":"SEARCHING_DATASETS","tool_title":"Searching for Datasets"}} +{"id":"m2xDLBXcPF5D","type":"text-chunk","group_id":"br31Y9vnKmDp", + "metadata":{"format":"markdown","type":"thinking"},"content":" to find a"} +{"id":"SpzpcgHBt_Pm","type":"answer","group_id":"TlhE-TPW05tu", + "title":"total sales by region", + "answer_id":"{\"session_id\":\"fc3bd346-...\",\"gen_no\":2}", + "metadata":{"sage_query":"[sales] [region]","session_id":"fc3bd346-...","gen_no":2, + "transaction_id":"8e5654f3-...","generation_number":1, + "warning_details":[{"warningType":"CHART_INTENT_APPLIED"}, + {"warningType":"CHART_INTENT_DETECTED"}], + "ambiguous_phrases":null,"query_intent":null, + "tml_phrases":["[sales] [region]"],"cached":false, + "sub_queries":null,"worksheet_id":"cd252e5c-...","type":"thinking"}} +---- + +For the complete event schema, see the xref:spotter-agent-apis.adoc#_api_response_2[Spotter Agent API, window=_blank]. === Type definition: session_update From dbde42ae7078b4d0d434bd4b54b40c41471c0ab0 Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Mon, 3 Aug 2026 14:46:41 +0530 Subject: [PATCH 060/154] SCAL-313912 --- modules/ROOT/pages/tml.adoc | 24 +++++------------------- 1 file changed, 5 insertions(+), 19 deletions(-) diff --git a/modules/ROOT/pages/tml.adoc b/modules/ROOT/pages/tml.adoc index 0cdafe3c1..486855d2c 100644 --- a/modules/ROOT/pages/tml.adoc +++ b/modules/ROOT/pages/tml.adoc @@ -214,6 +214,7 @@ These policies write objects incrementally and are appropriate for large migrati * The API payload size limit is 500 MB per request (infrastructure limit). Contact ThoughtSpot Support if your use case requires a larger limit. +// TODO: verify with engineering — confirm whether the ~50-object guideline counts TML strings in the array, or total distinct objects including dependents. ==== Avoid parallel imports of the same object @@ -251,18 +252,13 @@ Inspect per-object status in the response to identify failures. |`FAILED` |The task failed. -This could be due to multiple reasons such as - the queue was full at submission time, a policy-level failure occurred, or an unrecoverable error was encountered during processing. +Possible causes: the queue was full at submission time, a policy-level failure occurred, or an unrecoverable error was encountered during processing. |==== *Recommended polling intervals:* -The status API enforces a rate limit of 100 requests per minute. -Exceeding this limit returns an error. - -For practical use: - -* For small tasks, poll no more frequently than every 30 seconds. -* For large tasks, a polling interval of 1 minute is recommended, as larger tasks take proportionally longer to complete. +* Minimum polling interval: 30 seconds. +* For large tasks: poll every 1 minute. Large tasks take proportionally longer to complete. ==== Use API parameters correctly @@ -279,22 +275,12 @@ By default, ThoughtSpot identifies unchanged objects and skips them to reduce im Enable this parameter only when unchanged files must be explicitly reprocessed. `enable_large_metadata_validation`:: -Set to `true` if the database contains multiple thousands of tables. -When enabled, ThoughtSpot validates schema one table at a time, which helps circumvent metadata fetching limitations of the Cloud Data Warehouse (CDW). -Default: `false`. - -`enable_personalized_view_upsert`:: -Set to `true` to enable update and insert of personalized views in a Liveboard during TML import. -When enabled, personalized views are preserved or created as part of the import operation instead of being discarded. -Default: `false`. - +// TODO: verify with engineering — confirm purpose, behavior, and recommended use of `enable_large_metadata_validation` before publishing. ==== Schedule large imports during off-peak hours Large TML migrations can temporarily increase system resource usage. Schedule bulk async imports during off-peak hours to reduce the risk of impacting users who are actively using the cluster. - - === Schedule import tasks You can import TML objects asynchronously by scheduling TML import tasks via `POST` request to POST `/api/rest/2.0/metadata/tml/async/import` API endpoint. You can send the following parameters in the API request body: From 7a63ab4812b3e8c2b7675e9532dbdba5a3c5756a Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Mon, 3 Aug 2026 16:33:04 +0530 Subject: [PATCH 061/154] SCAL-313912 --- modules/ROOT/pages/tml.adoc | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/modules/ROOT/pages/tml.adoc b/modules/ROOT/pages/tml.adoc index 486855d2c..3a6a4b2b9 100644 --- a/modules/ROOT/pages/tml.adoc +++ b/modules/ROOT/pages/tml.adoc @@ -281,6 +281,7 @@ Enable this parameter only when unchanged files must be explicitly reprocessed. Large TML migrations can temporarily increase system resource usage. Schedule bulk async imports during off-peak hours to reduce the risk of impacting users who are actively using the cluster. + === Schedule import tasks You can import TML objects asynchronously by scheduling TML import tasks via `POST` request to POST `/api/rest/2.0/metadata/tml/async/import` API endpoint. You can send the following parameters in the API request body: @@ -297,16 +298,16 @@ __Optional__ |__Boolean__. Specify if import operation must be run for all Orgs __Requires Org administration privileges to access TML objects across all Orgs.__| `false` -|`import_policy` a|__String__. Available from 10.5.0.cl. Policy to follow during import. The allowed values are: +|`import_policy` a|__String__. Policy to follow during import. The allowed values are: -* `PARTIAL` + -Imports objects that validate successfully. Skips the objects that do not validate successfully and their dependent objects if any. -* `ALL_OR_NONE` + -Imports all objects that validate successfully. If the import fails for one object, no objects will be imported. -* `VALIDATE_ONLY` + -Validates the objects but does not import them. -* `PARTIAL_OBJECT` + -Imports objects that validate successfully and skips the objects that do not validate successfully. If the import fails for a visualization object in a Liveboard TML, the Liveboard will be imported without that visualization object. Similarly, if importing a relationship in a logical table fails, the table TML will be imported with warnings in the API response. +* `PARTIAL` +//Imports objects that validate successfully. Skips the objects that do not validate successfully and their dependent objects if any. +* `ALL_OR_NONE` +//Imports all objects that validate successfully. If the import fails for one object, no objects will be imported. +* `VALIDATE_ONLY` +//Validates the objects but does not import them. +* `PARTIAL_OBJECT` +//Imports objects that validate successfully and skips the objects that do not validate successfully. If the import fails for a visualization object in a Liveboard TML, the Liveboard will be imported without that visualization object. Similarly, if importing a relationship in a logical table fails, the table TML will be imported with warnings in the API response. | `PARTIAL_OBJECT` |`skip_diff_check` + @@ -314,7 +315,7 @@ __Optional__ |__Boolean__ |`false` |`enable_large_metadata_validation` + __Optional__ - |__Boolean__. Available from 10.5.0.cl. Enables validation for large metadata objects. Set to `true` if the database contains multiple thousands of tables. When enabled, it allows for schema validation of one table at a time and helps circumvent the metadata fetching limitations of the Cloud Data Warehouse (CDW). + |__Boolean__. Enables validation for large metadata objects. Set to `true` if the database contains multiple thousands of tables. When enabled, it allows for schema validation of one table at a time and helps circumvent the metadata fetching limitations of the Cloud Data Warehouse (CDW). |`false` |==== //// From 78ccd59fe42cc6f06f8ab0e2817637004b741c60 Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Tue, 4 Aug 2026 10:12:33 +0530 Subject: [PATCH 062/154] SCAL-313912 --- modules/ROOT/pages/tml.adoc | 44 ++++++++++++++++++++++++------------- 1 file changed, 29 insertions(+), 15 deletions(-) diff --git a/modules/ROOT/pages/tml.adoc b/modules/ROOT/pages/tml.adoc index 3a6a4b2b9..d02077f00 100644 --- a/modules/ROOT/pages/tml.adoc +++ b/modules/ROOT/pages/tml.adoc @@ -31,10 +31,14 @@ See the following pages for the detailed syntax of TML files for each object typ For TML modification tips and recommendations, see xref:modify-tml.adoc[TML modification]. + +//// [NOTE] ==== -Worksheets are deprecated in ThoughtSpot and replaced by Models from 10.12.0.cl onwards. +Worksheets are deprecated in ThoughtSpot and replaced by Models. ==== +//// + == TML import and export via REST API @@ -60,17 +64,6 @@ To import TML representation of the metadata objects into ThoughtSpot, use one o * xref:tml-api.adoc#import[POST /tspublic/v1/metadata/tml/import] (REST API v1) //While the v1 API accepts a string containing a JSON array of TML objects to upload, in YAML or JSON format, the v2 accepts it only in the JSON format. - -There are multiple kinds of imports possible: - -* `PARTIAL` imports all objects that validate successfully, and ignores objects that do not validate successfully. -* `ALL_OR_NONE` imports the objects that validate successfully. -* `VALIDATE_ONLY` validates the objects but does not import them. -* `PARTIAL_OBJECT` (only applicable to REST API v2) -imports objects that validate successfully and skips the objects that do not validate successfully. If the import fails for a visualization object in a Liveboard TML, the Liveboard will be imported without that visualization object. Similarly, if importing a relationship in a logical table fails, the table TML will be imported with warnings in the API response. - -You can also specify additional parameters to set the Org context and skip CDW validation checks for Table TMLs. - [NOTE] ==== If you import only a Model object, it may take some time for the Model to become available in the ThoughtSpot system. You may need to wait for a few seconds to create answers and Liveboards. @@ -252,13 +245,18 @@ Inspect per-object status in the response to identify failures. |`FAILED` |The task failed. -Possible causes: the queue was full at submission time, a policy-level failure occurred, or an unrecoverable error was encountered during processing. +This could be due to multiple reasons such as - the queue was full at submission time, a policy-level failure occurred, or an unrecoverable error was encountered during processing. |==== *Recommended polling intervals:* -* Minimum polling interval: 30 seconds. -* For large tasks: poll every 1 minute. Large tasks take proportionally longer to complete. +The status API enforces a rate limit of 100 requests per minute. +Exceeding this limit returns an error. + +For practical use: + +* For small tasks, poll no more frequently than every 30 seconds. +* For large tasks, a polling interval of 1 minute is recommended, as larger tasks take proportionally longer to complete. ==== Use API parameters correctly @@ -276,12 +274,28 @@ Enable this parameter only when unchanged files must be explicitly reprocessed. `enable_large_metadata_validation`:: // TODO: verify with engineering — confirm purpose, behavior, and recommended use of `enable_large_metadata_validation` before publishing. +Set to `true` if the database contains multiple thousands of tables. +When enabled, ThoughtSpot validates schema one table at a time, which helps circumvent metadata fetching limitations of the Cloud Data Warehouse (CDW). +Default: `false`. + +`enable_personalized_view_upsert`:: +Set to `true` to enable update and insert of personalized views in a Liveboard during TML import. +When enabled, personalized views are preserved or created as part of the import operation instead of being discarded. +Default: `false`. ++ +[IMPORTANT] +==== +This parameter requires the improved personalized views management feature to be enabled on your ThoughtSpot instance. +If the feature is not enabled, setting `enable_personalized_view_upsert: true` returns a `400 Bad Request` error: `enable_personalized_view_upsert is not supported`. +// TODO: verify with engineering — confirm what enables isImprovedPersonalizedViewsManagementEnabled() (release gate, tscli flag, or support request) and whether this is on by default in 26.8.0.cl or requires explicit enablement. +==== ==== Schedule large imports during off-peak hours Large TML migrations can temporarily increase system resource usage. Schedule bulk async imports during off-peak hours to reduce the risk of impacting users who are actively using the cluster. + === Schedule import tasks You can import TML objects asynchronously by scheduling TML import tasks via `POST` request to POST `/api/rest/2.0/metadata/tml/async/import` API endpoint. You can send the following parameters in the API request body: From 11d05e99704bbd49aa246b3abd7211eae104945b Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Tue, 4 Aug 2026 13:25:52 +0530 Subject: [PATCH 063/154] SCAL-313912 --- modules/ROOT/pages/tml.adoc | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/modules/ROOT/pages/tml.adoc b/modules/ROOT/pages/tml.adoc index d02077f00..870040337 100644 --- a/modules/ROOT/pages/tml.adoc +++ b/modules/ROOT/pages/tml.adoc @@ -326,10 +326,14 @@ __Requires Org administration privileges to access TML objects across all Orgs._ |`skip_diff_check` + __Optional__ -|__Boolean__ |`false` +|__Boolean__. |`false` |`enable_large_metadata_validation` + __Optional__ - |__Boolean__. Enables validation for large metadata objects. Set to `true` if the database contains multiple thousands of tables. When enabled, it allows for schema validation of one table at a time and helps circumvent the metadata fetching limitations of the Cloud Data Warehouse (CDW). + |__Boolean__ +|`false` +|`enable_personalized_view_upsert` + +__Optional__ +|__Boolean__ |`false` |==== //// From 750109ff37a6963a7c70755f2d59cc01f599707a Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Tue, 4 Aug 2026 14:13:12 +0530 Subject: [PATCH 064/154] SCAL-313912 --- modules/ROOT/pages/tml.adoc | 10 +--------- 1 file changed, 1 insertion(+), 9 deletions(-) diff --git a/modules/ROOT/pages/tml.adoc b/modules/ROOT/pages/tml.adoc index 870040337..6982e39fd 100644 --- a/modules/ROOT/pages/tml.adoc +++ b/modules/ROOT/pages/tml.adoc @@ -282,13 +282,7 @@ Default: `false`. Set to `true` to enable update and insert of personalized views in a Liveboard during TML import. When enabled, personalized views are preserved or created as part of the import operation instead of being discarded. Default: `false`. -+ -[IMPORTANT] -==== -This parameter requires the improved personalized views management feature to be enabled on your ThoughtSpot instance. -If the feature is not enabled, setting `enable_personalized_view_upsert: true` returns a `400 Bad Request` error: `enable_personalized_view_upsert is not supported`. -// TODO: verify with engineering — confirm what enables isImprovedPersonalizedViewsManagementEnabled() (release gate, tscli flag, or support request) and whether this is on by default in 26.8.0.cl or requires explicit enablement. -==== + ==== Schedule large imports during off-peak hours @@ -431,8 +425,6 @@ response starting from offset position. The maximum limit for the `record_size` that user can pass in an API request is 50. If the `record_size` exceeds this threshold, the API returns a bad request error. To extend the `record_size` limit, contact ThoughtSpot Support. ==== | `5` -|`include_import_response`|__Boolean__. Specify whether to include the import response when fetching status for the import task. - |==== [IMPORTANT] From a37e826b77b0fce9b57a3a017eb9dddd9b96aede Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Wed, 12 Aug 2026 15:23:41 +0530 Subject: [PATCH 065/154] review changes --- modules/ROOT/pages/tml.adoc | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/modules/ROOT/pages/tml.adoc b/modules/ROOT/pages/tml.adoc index 6982e39fd..61913346b 100644 --- a/modules/ROOT/pages/tml.adoc +++ b/modules/ROOT/pages/tml.adoc @@ -207,7 +207,6 @@ These policies write objects incrementally and are appropriate for large migrati * The API payload size limit is 500 MB per request (infrastructure limit). Contact ThoughtSpot Support if your use case requires a larger limit. -// TODO: verify with engineering — confirm whether the ~50-object guideline counts TML strings in the array, or total distinct objects including dependents. ==== Avoid parallel imports of the same object @@ -273,7 +272,6 @@ By default, ThoughtSpot identifies unchanged objects and skips them to reduce im Enable this parameter only when unchanged files must be explicitly reprocessed. `enable_large_metadata_validation`:: -// TODO: verify with engineering — confirm purpose, behavior, and recommended use of `enable_large_metadata_validation` before publishing. Set to `true` if the database contains multiple thousands of tables. When enabled, ThoughtSpot validates schema one table at a time, which helps circumvent metadata fetching limitations of the Cloud Data Warehouse (CDW). Default: `false`. @@ -320,7 +318,7 @@ __Requires Org administration privileges to access TML objects across all Orgs._ |`skip_diff_check` + __Optional__ -|__Boolean__. |`false` +|__Boolean__ |`false` |`enable_large_metadata_validation` + __Optional__ |__Boolean__ From 2007dff90b47fb882ac16d807c91ff3de7426dc6 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Mon, 17 Aug 2026 10:17:53 +0530 Subject: [PATCH 066/154] search object tool updates --- modules/ROOT/pages/mcp-server-changelog.adoc | 11 + .../pages/mcp-tool-reference-spotter3.adoc | 264 +++++++++++++++++- 2 files changed, 274 insertions(+), 1 deletion(-) diff --git a/modules/ROOT/pages/mcp-server-changelog.adoc b/modules/ROOT/pages/mcp-server-changelog.adoc index e91d4c839..4df7147dd 100644 --- a/modules/ROOT/pages/mcp-server-changelog.adoc +++ b/modules/ROOT/pages/mcp-server-changelog.adoc @@ -36,6 +36,17 @@ a| a| +[discrete] +==== New `search_objects` tool [.version-badge.new]#New# +The new `search_objects` MCP tool lets agents search for existing ThoughtSpot content by name or description and return matching objects with their metadata and deep links. + +Use `search_objects` when a user refers to content that already exists. For example, "open the regional sales Liveboard" or "what dashboards has Priya built." +The tool is independent of the analysis session workflow: it does not require a session and does not need to be called before `create_analysis_session`. + +Supported object types: Liveboard, Liveboard viz, Answer, and Worksheet. +Results include the object's title, author, tags, verified status, last-modified date, and a deep link for opening the object in the ThoughtSpot UI. +Results are paginated using an opaque cursor. For reference, see xref:mcp-tool-reference-spotter3.adoc#search_objects[search_objects]. + [discrete] ==== Step headings in `get_session_updates` responses Spotter now reports each step it works through while processing a question. diff --git a/modules/ROOT/pages/mcp-tool-reference-spotter3.adoc b/modules/ROOT/pages/mcp-tool-reference-spotter3.adoc index 622c6ca25..b927f6d89 100644 --- a/modules/ROOT/pages/mcp-tool-reference-spotter3.adoc +++ b/modules/ROOT/pages/mcp-tool-reference-spotter3.adoc @@ -6,8 +6,10 @@ :page-pageid: mcp-tool-reference-spotter3 :page-description: Refer to this guide to learn which MCP tools are supported, input parameters used for tool calls, and the response format. -The ThoughtSpot Spotter Model Context Protocol (MCP) Server integration exposes a session-based workflow for running natural language analytics queries against your ThoughtSpot data sources. The pattern is always: **create a session** → **send a message** → **poll for updates**. +The ThoughtSpot Spotter Model Context Protocol (MCP) Server integration exposes tools for running natural language analytics queries and searching existing ThoughtSpot content. The core analytics pattern is: **create a session** → **send a message** → **poll for updates**. The `search_objects` tool is independent of this workflow and can be called at any time. +* <> + +Search for existing ThoughtSpot content by name or description. * <> + Start an analytical session. * <> + @@ -23,6 +25,266 @@ Switch your active Org for the current session. (OAuth connections on Org-enable * <> + Verify that the MCP Server is reachable. +[#search_objects] +== search_objects +Search for existing ThoughtSpot content by name or description, and return the matching objects with their metadata and deep links. + +Use this tool when a user refers to content that already exists — for example, "open the regional sales Liveboard" or "what dashboards has Priya built." +`search_objects` is independent of the analysis session workflow: it does not require a session and does not need to be called before `create_analysis_session`. + +`search_objects` returns identifiers and metadata only. +It never returns the object's data or contents, and it does not run queries. +To answer a data question, use the session workflow instead. + +=== Input parameters + +[cols="2,4", options="header"] +|==== +|Field|Description + +|`query` + +__Required__ +|The search term, matched against object names and descriptions. Must be non-empty. + +|`types` + +__Optional__ +|Restrict results to these object types. Accepts an array of `LIVEBOARD`, `LIVEBOARD_VIZ`, `ANSWER`, `WORKSHEET`. Omit to search all types. + +|`author_name` + +__Optional__ +|Restrict results to objects authored by this user, matched against the author's display name. Case-insensitive substring match. + +|`tag` + +__Optional__ +|Restrict results to objects carrying this tag or sticker, matched by tag name. Case-insensitive substring match. + +|`modified_since` + +__Optional__ +|Return only objects last modified on or after this epoch-millisecond timestamp. + +|`verified_only` + +__Optional__ +|If `true`, return only objects marked as verified. + +|`limit` + +__Optional__ +|Maximum number of results to return. Positive integer. Defaults to `10`. + +|`cursor` + +__Optional__ +|Opaque pagination cursor returned as `next_cursor` by a previous call. Omit on the first page. +|==== + +=== Object types + +The `types` input parameter and the `type` field on each result use the same tokens. +Any value returned in a result can be passed back as a `types` filter. + +[cols="1,3", options="header"] +|==== +|Value|Meaning + +|`LIVEBOARD`|A Liveboard. +|`LIVEBOARD_VIZ`|A single visualization pinned on a Liveboard. Distinct from a standalone Answer. Render this as "Liveboard viz". +|`ANSWER`|A saved Answer. +|`WORKSHEET`|A Worksheet or model. +|==== + +=== Example call + +[div tabbed-code] +-- +[source,javascript] +---- +const results = await callMCPTool("search_objects", { + query: "regional sales", // Required — search term matched against object names and descriptions. + types: ["LIVEBOARD", "LIVEBOARD_VIZ"], // Optional — restrict to these object types. + author_name: "Priya", // Optional — case-insensitive substring match on author display name. + tag: "Certified", // Optional — case-insensitive substring match on tag name. + verified_only: true, // Optional — return only verified objects. + limit: 5 // Optional — maximum results to return. Defaults to 10. +}); +---- + +[source,python] +---- +call_mcp_tool( + "search_objects", + { + "query": "regional sales", # Required — search term matched against object names and descriptions. + "types": ["LIVEBOARD", "LIVEBOARD_VIZ"], # Optional — restrict to these object types. + "author_name": "Priya", # Optional — case-insensitive substring match on author display name. + "tag": "Certified", # Optional — case-insensitive substring match on tag name. + "verified_only": True, # Optional — return only verified objects. + "limit": 5, # Optional — maximum results to return. Defaults to 10. + }, +) +---- +-- + +=== Response + +A call returns one of three outcomes. + +==== Successful match + +`status` is omitted when the search returned results. + +[source,json] +---- +{ + "results": [ + { + "object_id": "b2c4e6a8-1234-4f5a-9abc-def012345678", + "title": "Regional Sales Performance", + "type": "LIVEBOARD", + "author_name": "Priya Raman", + "description": "Weekly sales tracking by region and rep.", + "tags": ["Sales", "Certified"], + "last_modified": "2026-05-15T14:30:00.000Z", + "verified": true, + "external_link": "https://your-instance.thoughtspot.cloud/#/insights/pinboard/b2c4e6a8-1234-4f5a-9abc-def012345678", + "query": null, + "confidence": 0.94 + }, + { + "object_id": "b2c4e6a8-1234-4f5a-9abc-def012345678", + "visualization_id": "77f1a0d3-5678-4b21-8e90-aa1122334455", + "title": "Sales by Region", + "type": "LIVEBOARD_VIZ", + "author_name": "Priya Raman", + "tags": ["Sales"], + "last_modified": "2026-05-15T14:30:00.000Z", + "verified": false, + "external_link": "https://your-instance.thoughtspot.cloud/#/insights/pinboard/b2c4e6a8-1234-4f5a-9abc-def012345678/77f1a0d3-5678-4b21-8e90-aa1122334455", + "query": "sales by region monthly", + "confidence": 0.81 + } + ], + "next_cursor": "10" +} +---- + +==== No results + +The search ran successfully but nothing matched. + +[source,json] +---- +{ + "status": "no_results", + "results": [], + "next_cursor": null +} +---- + +Tell the user that nothing matched and suggest broadening the search term or removing a filter. Do not synthesize results. + +==== Error + +The search could not be completed. + +[source,json] +---- +{ + "status": "error", + "results": [], + "error": { + "code": "RATE_LIMITED", + "message": "ThoughtSpot rate limit reached. Try again shortly.", + "retryable": true + } +} +---- + +If `retryable` is `true`, wait briefly and retry the same call. If `retryable` is `false`, surface the `message` to the user and do not retry automatically. + +=== Response fields + +[cols="2,1,4", options="header"] +|==== +|Field|Type|Description + +|`status`|String +|Omitted on a successful hit list. +`no_results` means the search ran but matched nothing. +`error` means the search failed and `error` is populated. + +|`results`|Array +|Ranked list of matching objects, most relevant first. Empty for `no_results` and `error`. + +|`next_cursor`|String +|Cursor to pass back as `cursor` to retrieve the next page. `null` when there are no more results. Omitted on `error`. + +|`error`|Object +|Present only when `status` is `error`. Contains `code`, `message`, and `retryable`. +|==== + +=== Fields on each result + +[cols="2,1,4", options="header"] +|==== +|Field|Type|Description + +|`object_id`|String +|GUID of the object. +For a `LIVEBOARD_VIZ` result, this is the GUID of the parent Liveboard, not the visualization. + +|`visualization_id`|String +|Present only on `LIVEBOARD_VIZ` results. GUID of the specific visualization pinned on the Liveboard identified by `object_id`. + +|`title`|String +|Display name of the object. + +|`type`|String +|Object type: `LIVEBOARD`, `LIVEBOARD_VIZ`, `ANSWER`, or `WORKSHEET`. Can be passed back as a `types` filter. + +|`author_name`|String +|Display name of the user who authored the object. + +|`description`|String +|Description of the object. Omitted when the object has none. + +|`tags`|Array of strings +|Names of the tags or stickers applied to the object. + +|`last_modified`|String +|ISO 8601 timestamp of the last modification. For example, `2026-05-15T14:30:00.000Z`. Omitted when unavailable. Render as a plain date. + +|`verified`|Boolean +|Whether the object is marked as verified. + +|`external_link`|String +|Deep link to open the object in the ThoughtSpot UI. This link opens in a browser tab. It is not an embeddable iframe URL. + +|`query`|String +|For an Answer or Liveboard viz, the search tokens that define it — for example, `sales by region monthly`. `null` for a Liveboard. + +|`confidence`|Number +|Relevance score for the search term. Use for ranking only. Do not display this value to the user. +|==== + +=== Pagination + +`search_objects` returns up to `limit` results per call (default `10`). +When more results are available, the response includes a `next_cursor` value. +Pass this value back as `cursor` in the next call to retrieve the following page. +When `next_cursor` is `null`, there are no further results. + +[source,javascript] +---- +// Fetch the first page +let response = await callMCPTool("search_objects", { query: "sales" }); + +// Fetch the next page if a cursor was returned +if (response.next_cursor) { + response = await callMCPTool("search_objects", { + query: "sales", + cursor: response.next_cursor + }); +} +---- + [#create_analysis_session] == create_analysis_session Start an analytical session with ThoughtSpot's analytics agent. This is the required first step before sending any questions. From 7587b77d7bb8c7f621e0f371255e0e4cf64d018c Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Mon, 17 Aug 2026 22:31:04 +0530 Subject: [PATCH 067/154] SCAL-331862 updates --- modules/ROOT/pages/mcp-server-changelog.adoc | 9 +--- .../pages/mcp-tool-reference-spotter3.adoc | 46 +++++++++---------- 2 files changed, 24 insertions(+), 31 deletions(-) diff --git a/modules/ROOT/pages/mcp-server-changelog.adoc b/modules/ROOT/pages/mcp-server-changelog.adoc index 4df7147dd..3a6cd1c76 100644 --- a/modules/ROOT/pages/mcp-server-changelog.adoc +++ b/modules/ROOT/pages/mcp-server-changelog.adoc @@ -38,14 +38,7 @@ a| [discrete] ==== New `search_objects` tool [.version-badge.new]#New# -The new `search_objects` MCP tool lets agents search for existing ThoughtSpot content by name or description and return matching objects with their metadata and deep links. - -Use `search_objects` when a user refers to content that already exists. For example, "open the regional sales Liveboard" or "what dashboards has Priya built." -The tool is independent of the analysis session workflow: it does not require a session and does not need to be called before `create_analysis_session`. - -Supported object types: Liveboard, Liveboard viz, Answer, and Worksheet. -Results include the object's title, author, tags, verified status, last-modified date, and a deep link for opening the object in the ThoughtSpot UI. -Results are paginated using an opaque cursor. For reference, see xref:mcp-tool-reference-spotter3.adoc#search_objects[search_objects]. +The new `search_objects` MCP tool lets agents search for existing ThoughtSpot content by name or description and return matching objects with their metadata and deep links. For more information, see xref:mcp-tool-reference-spotter3.adoc#search_objects[search_objects]. [discrete] ==== Step headings in `get_session_updates` responses diff --git a/modules/ROOT/pages/mcp-tool-reference-spotter3.adoc b/modules/ROOT/pages/mcp-tool-reference-spotter3.adoc index b927f6d89..dc3bcd942 100644 --- a/modules/ROOT/pages/mcp-tool-reference-spotter3.adoc +++ b/modules/ROOT/pages/mcp-tool-reference-spotter3.adoc @@ -29,11 +29,11 @@ Verify that the MCP Server is reachable. == search_objects Search for existing ThoughtSpot content by name or description, and return the matching objects with their metadata and deep links. -Use this tool when a user refers to content that already exists — for example, "open the regional sales Liveboard" or "what dashboards has Priya built." -`search_objects` is independent of the analysis session workflow: it does not require a session and does not need to be called before `create_analysis_session`. +Use this tool when a user refers to content that already exists. For example, "open the regional sales Liveboard" or "what dashboards has Priya built". The +`search_objects` tool is independent of the analysis session workflow. Tt does not require a session and does not need to be called before `create_analysis_session`. + +`search_objects` returns identifiers and metadata only. It never returns the object's data or contents, and it does not run queries. -`search_objects` returns identifiers and metadata only. -It never returns the object's data or contents, and it does not run queries. To answer a data question, use the session workflow instead. === Input parameters @@ -87,7 +87,7 @@ Any value returned in a result can be passed back as a `types` filter. |`LIVEBOARD`|A Liveboard. |`LIVEBOARD_VIZ`|A single visualization pinned on a Liveboard. Distinct from a standalone Answer. Render this as "Liveboard viz". |`ANSWER`|A saved Answer. -|`WORKSHEET`|A Worksheet or model. +|`WORKSHEET`|A data model object. |==== === Example call @@ -97,12 +97,12 @@ Any value returned in a result can be passed back as a `types` filter. [source,javascript] ---- const results = await callMCPTool("search_objects", { - query: "regional sales", // Required — search term matched against object names and descriptions. - types: ["LIVEBOARD", "LIVEBOARD_VIZ"], // Optional — restrict to these object types. - author_name: "Priya", // Optional — case-insensitive substring match on author display name. - tag: "Certified", // Optional — case-insensitive substring match on tag name. - verified_only: true, // Optional — return only verified objects. - limit: 5 // Optional — maximum results to return. Defaults to 10. + query: "regional sales", // Required. Search term matched against object names and descriptions. + types: ["LIVEBOARD", "LIVEBOARD_VIZ"], // Optional. Restrict to these object types. + author_name: "Priya", // Optional. Case-insensitive substring match on author display name. + tag: "Certified", // Optional. Case-insensitive substring match on tag name. + verified_only: true, // Optional. Return only verified objects. + limit: 5 // Optional. Maximum results to return. Defaults to 10. }); ---- @@ -111,12 +111,12 @@ const results = await callMCPTool("search_objects", { call_mcp_tool( "search_objects", { - "query": "regional sales", # Required — search term matched against object names and descriptions. - "types": ["LIVEBOARD", "LIVEBOARD_VIZ"], # Optional — restrict to these object types. - "author_name": "Priya", # Optional — case-insensitive substring match on author display name. - "tag": "Certified", # Optional — case-insensitive substring match on tag name. - "verified_only": True, # Optional — return only verified objects. - "limit": 5, # Optional — maximum results to return. Defaults to 10. + "query": "regional sales", # Required. Search term matched against object names and descriptions. + "types": ["LIVEBOARD", "LIVEBOARD_VIZ"], # Optional. Restrict to these object types. + "author_name": "Priya", # Optional. Case-insensitive substring match on author display name. + "tag": "Certified", # Optional. Case-insensitive substring match on tag name. + "verified_only": True, # Optional. Return only verified objects. + "limit": 5, # Optional. Maximum results to return. Defaults to 10. }, ) ---- @@ -258,7 +258,7 @@ For a `LIVEBOARD_VIZ` result, this is the GUID of the parent Liveboard, not the |Deep link to open the object in the ThoughtSpot UI. This link opens in a browser tab. It is not an embeddable iframe URL. |`query`|String -|For an Answer or Liveboard viz, the search tokens that define it — for example, `sales by region monthly`. `null` for a Liveboard. +|For an Answer or Liveboard viz, the search tokens that define it. For example, `sales by region monthly`. `null` for a Liveboard. |`confidence`|Number |Relevance score for the search term. Use for ranking only. Do not display this value to the user. @@ -301,7 +301,7 @@ The `data_source_id` is optional. Provide this when the user has specified or co [source,javascript] ---- const session = await callMCPTool("create_analysis_session", { - data_source_id: "model-guid-123" // Optional — GUID of the ThoughtSpot worksheet or model to query. Omit to let ThoughtSpot automatically select the most relevant data source. + data_source_id: "model-guid-123" // Optional. GUID of the ThoughtSpot model to query. Omit to let ThoughtSpot automatically select the most relevant data source. }); ---- @@ -310,7 +310,7 @@ const session = await callMCPTool("create_analysis_session", { call_mcp_tool( "create_analysis_session", { - "data_source_id": "model-guid-123" # Optional — GUID of the ThoughtSpot worksheet or model to query. + "data_source_id": "model-guid-123" # Optional. GUID of the ThoughtSpot model to query. }, ) ---- @@ -355,7 +355,7 @@ const sendMessage = await callMCPTool("send_session_message", { analytical_session_id: "sess_abc123", // Session ID from create_analysis_session. message: "What were total sales by region last quarter?", // User's natural language question. additional_context: "The user's fiscal year starts in April. " + - "Focus on underperforming regions only." // Optional — external information to influence the analysis. + "Focus on underperforming regions only." // Optional. External information to influence the analysis. }); ---- @@ -366,7 +366,7 @@ call_mcp_tool( { "analytical_session_id": "sess_abc123", # Session ID from create_analysis_session. "message": "What were total sales by region last quarter?", # User's natural language question. - "additional_context": ( # Optional — external information + "additional_context": ( # Optional. External information "The user's fiscal year starts in April." "Focus on underperforming regions only." # to influence the analysis. ), @@ -632,7 +632,7 @@ const dashboard = await callMCPTool("create_dashboard", { note_tile: "

Q4 2025 Regional Sales Analysis

" + "

Analysis of total sales by region for Q4 2025, highlighting " + "top-performing and underperforming regions.
" + - "Generated on 2026-04-16 10:00 AM

" // Required — single-line HTML string rendered as a styled summary tile at the top of the dashboard. + "Generated on 2026-04-16 10:00 AM

" // Required. Single-line HTML string rendered as a styled summary tile at the top of the dashboard. }); ---- From eab0c322ea867ca9a6e516a8e4ee6954a3faf5ae Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Mon, 17 Aug 2026 22:45:21 +0530 Subject: [PATCH 068/154] label update --- modules/ROOT/pages/mcp-server-changelog.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/mcp-server-changelog.adoc b/modules/ROOT/pages/mcp-server-changelog.adoc index 3a6cd1c76..3af9f93e4 100644 --- a/modules/ROOT/pages/mcp-server-changelog.adoc +++ b/modules/ROOT/pages/mcp-server-changelog.adoc @@ -37,7 +37,7 @@ a| a| [discrete] -==== New `search_objects` tool [.version-badge.new]#New# +==== New `search_objects` tool The new `search_objects` MCP tool lets agents search for existing ThoughtSpot content by name or description and return matching objects with their metadata and deep links. For more information, see xref:mcp-tool-reference-spotter3.adoc#search_objects[search_objects]. [discrete] From c0fa33019a3a743c2a9a5ef571ca9d96488f3f92 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Tue, 18 Aug 2026 11:56:02 +0530 Subject: [PATCH 069/154] link and formatting fixes --- modules/ROOT/pages/rest-apiv2-changelog.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/ROOT/pages/rest-apiv2-changelog.adoc b/modules/ROOT/pages/rest-apiv2-changelog.adoc index 22e0cfcaf..7b274d0e5 100644 --- a/modules/ROOT/pages/rest-apiv2-changelog.adoc +++ b/modules/ROOT/pages/rest-apiv2-changelog.adoc @@ -37,7 +37,7 @@ Collections `obj_id` support::: The `obj_id` attribute is now supported for the *Collections* object type in TML import and export APIs. This enables stable cross-environment identification for Collections, matching the behavior already available for Models, Liveboards, Answers, and other object types. + To assign or update the `obj_id` for a Collections object, use the `POST /api/rest/2.0/metadata/identity/update` API endpoint. -+ + === Roles API @@ -55,7 +55,7 @@ The `every_n_minutes` schedule frequency option is deprecated in 26.8.0.cl. Sche === REST API C# SDK ThoughtSpot provides the REST API C# SDK (`ThoughtSpot.RestApi.Sdk`) to help .NET developers interact programmatically with ThoughtSpot REST API v2 endpoints. The SDK targets `net8.0` and is available on link:https://www.nuget.org/packages/ThoughtSpot.RestApi.Sdk[NuGet, window=_blank]. -For information about how to install and use the SDK, see xref:rest-api-sdk-csharp.adoc[C# SDK for REST APIs]. +For information about how to install and use the SDK, see xref:rest-api-csharp-sdk.adoc[C# SDK for REST APIs]. == Version 26.7.0.cl, July 2026 From 6ba8b4036d56932093aa1a539b3d750302655171 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Tue, 18 Aug 2026 22:13:40 +0530 Subject: [PATCH 070/154] typo fixes --- .../pages/mcp-connect-custom-chatbot.adoc | 19 +++++++++---------- modules/ROOT/pages/mcp-server-changelog.adoc | 2 +- 2 files changed, 10 insertions(+), 11 deletions(-) diff --git a/modules/ROOT/pages/mcp-connect-custom-chatbot.adoc b/modules/ROOT/pages/mcp-connect-custom-chatbot.adoc index 60d722554..90b20efaf 100644 --- a/modules/ROOT/pages/mcp-connect-custom-chatbot.adoc +++ b/modules/ROOT/pages/mcp-connect-custom-chatbot.adoc @@ -173,7 +173,7 @@ For those cases only, you can enable the full response to receive the raw event Enabling it is a deliberate tradeoff: you take on higher token costs on every turn and take on work the default response does for you. Use the default unless you have a specific requirement the default cannot meet. -=== Default vs. full response +=== Default and full response comparison [cols="2,3,3", options="header"] |==== @@ -187,7 +187,7 @@ Use the default unless you have a specific requirement the default cannot meet. |The answer |Title, search query, TML tokens, embeddable `iframe_url`, `answer_id` -|Title, search query, TML tokens, plus raw metadata — no preconstructed `iframe_url`; you build it yourself +|Title, search query, TML tokens, and raw metadata. No preconstructed `iframe_url`; you build it yourself. |Additional metadata |Not included @@ -195,21 +195,22 @@ Use the default unless you have a specific requirement the default cannot meet. |Context cost |Lower -|Meaningfully higher — the full metadata payload is sent on every `get_session_updates` response +|Meaningfully higher. The full metadata payload is sent on every `get_session_updates` response |==== Neither response includes the underlying result data. In both cases, values are rendered inside the visualization itself. === When to use it -* *Default response (recommended)* — the user reads the answer from the visualization. -Start here if you are unsure. You can switch to the full response later without changing your session or message flow, because only the content of the updates changes. +Default response (Recommended):: +The user reads the answer from the visualization. Start here if you are unsure. You can switch to the full response later without changing your session or message flow, because only the content of the updates changes. -* *Full response* — use when your agent needs to explain the analysis behind the answer — for example, full tool call metadata, memories used, and dataset instructions referenced — so users can confirm their question was interpreted correctly. +Full response:: +Use when your agent needs to explain the analysis behind the answer. For example, full tool call metadata, memories used, and dataset instructions referenced, so users can confirm their question was interpreted correctly. [NOTE] ==== -The full response's metadata — token breakdown, formulas, parameters, subqueries, and more — is sent with every `get_session_updates` response. +The full response's metadata, including token breakdown, formulas, parameters, subqueries, and more, is sent with every `get_session_updates` response. In longer conversations or high-volume integrations, this adds substantial extra token usage compared to the default response. ==== @@ -231,8 +232,7 @@ https://agent.thoughtspot.app/mcp?api-version=latest&enable-raw-session-updates= === Constructing the answer iframe yourself -With the full response enabled, the raw answer event does not include a preconstructed `iframe_url`. -Build it from fields in the event's `metadata` object. +With the full response enabled, the raw answer event does not include a preconstructed `iframe_url`. Build it from fields in the event's `metadata` object. Sample raw answer event: @@ -273,7 +273,6 @@ const iframeUrl = For the complete event schema, see the xref:spotter-agent-apis.adoc#_api_response_2[Spotter Agent API, window=_blank]. - == Verifying the integration To verify the integration: diff --git a/modules/ROOT/pages/mcp-server-changelog.adoc b/modules/ROOT/pages/mcp-server-changelog.adoc index 3af9f93e4..f58792a33 100644 --- a/modules/ROOT/pages/mcp-server-changelog.adoc +++ b/modules/ROOT/pages/mcp-server-changelog.adoc @@ -37,7 +37,7 @@ a| a| [discrete] -==== New `search_objects` tool +==== `search_objects` MCP tool The new `search_objects` MCP tool lets agents search for existing ThoughtSpot content by name or description and return matching objects with their metadata and deep links. For more information, see xref:mcp-tool-reference-spotter3.adoc#search_objects[search_objects]. [discrete] From 7593fde8994ed9c57d367f692693c60bb0ae347b Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Tue, 18 Aug 2026 22:37:19 +0530 Subject: [PATCH 071/154] edits --- modules/ROOT/pages/mcp-server-changelog.adoc | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/modules/ROOT/pages/mcp-server-changelog.adoc b/modules/ROOT/pages/mcp-server-changelog.adoc index f58792a33..5c01d63ef 100644 --- a/modules/ROOT/pages/mcp-server-changelog.adoc +++ b/modules/ROOT/pages/mcp-server-changelog.adoc @@ -40,6 +40,8 @@ a| ==== `search_objects` MCP tool The new `search_objects` MCP tool lets agents search for existing ThoughtSpot content by name or description and return matching objects with their metadata and deep links. For more information, see xref:mcp-tool-reference-spotter3.adoc#search_objects[search_objects]. +--- + [discrete] ==== Step headings in `get_session_updates` responses Spotter now reports each step it works through while processing a question. @@ -51,6 +53,8 @@ Spotter now reports each step it works through while processing a question. ==== Full tool response via URL flag You can now receive the raw Spotter event stream from `get_session_updates` by appending `enable-raw-session-updates=true` to your MCP endpoint URL. The full response includes granular metadata about Spotter's internal tool calls, such as the columns in the data model used to answer the question, formulas, parameters, and subqueries. For guidance on when to use the full response and how to enable it, see xref:mcp-connect-custom-chatbot.adoc#accessing-full-tool-responses[Accessing full tool responses]. For the response format reference, see xref:mcp-tool-reference-spotter3.adoc#full-response[Full response (raw event stream)]. +--- + [discrete] ==== ThoughtSpot skill for skill-aware LLM clients A companion skill, `analyzing-data-with-thoughtspot` is now available for LLM clients that support skills, such as Claude. From 0bcb139e744fe14dd17e9a05c4747afa1628b553 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Wed, 19 Aug 2026 11:32:24 +0530 Subject: [PATCH 072/154] review comments and typo fixes --- modules/ROOT/pages/mcp-integration.adoc | 9 +- .../pages/mcp-server-client-connection.adoc | 27 +- modules/ROOT/pages/mcp-server-spotter3.adoc | 17 +- .../pages/mcp-tool-reference-spotter3.adoc | 799 +++++++++--------- 4 files changed, 425 insertions(+), 427 deletions(-) diff --git a/modules/ROOT/pages/mcp-integration.adoc b/modules/ROOT/pages/mcp-integration.adoc index f95b1147f..942542efe 100644 --- a/modules/ROOT/pages/mcp-integration.adoc +++ b/modules/ROOT/pages/mcp-integration.adoc @@ -6,7 +6,7 @@ :page-pageid: mcp-integration :page-description: Learn what ThoughtSpot Spotter MCP Server is, when to use it, and how it fits into your AI and analytics architecture. -ThoughtSpot’s Model Context Protocol (MCP) Server enables integration of ThoughtSpot analytics into any AI-native application, custom chatbot, or LLM platform that supports MCP. Instead of rebuilding analytics logic yourself, you connect an LLM/AI agent to the ThoughtSpot Spotter MCP Server. +ThoughtSpot's Model Context Protocol (MCP) Server enables integration of ThoughtSpot analytics into any AI-native application, custom chatbot, or LLM platform that supports MCP. Instead of rebuilding analytics logic yourself, you connect an LLM/AI agent to the ThoughtSpot Spotter MCP Server. == Overview ThoughtSpot Spotter MCP Server exposes ThoughtSpot analytics as tools and resources that MCP-compatible agents can discover and use. When integrated, the MCP Server provides your AI agent or LLM with the following capabilities: @@ -15,6 +15,7 @@ ThoughtSpot Spotter MCP Server exposes ThoughtSpot analytics as tools and resour * Natural language queries and responses * Programmatic creation of Liveboards and visualizations * Generating embeddable visualizations +* Searching for existing ThoughtSpot content by name, author, tag, or type === Supported integrations ThoughtSpot Spotter MCP Server supports two primary integration options: @@ -24,7 +25,7 @@ ThoughtSpot Spotter MCP Server supports two primary integration options: | Integration option | Description | xref:mcp-server-client-connection.adoc[Plug-and-play clients] -|This integration works with agents or LLMs that natively support MCP, such as Claude, ChatGPT, Gemini, or custom MCP clients. It allows your AI agent to call tools directly and leverage ThoughtSpot’s governed analytics, business semantic layer, data context, and row-level/object-level security, without the need to build your analytics logic. +|This integration works with agents or LLMs that natively support MCP, such as Claude, ChatGPT, Gemini, or custom MCP clients. It allows your AI agent to call tools directly and leverage ThoughtSpot's governed analytics, business semantic layer, data context, and row-level/object-level security, without the need to build your analytics logic. **When to use**: If your application already has an AI chat interface or agentic experience, you can quickly add analytics to your existing setup without custom development. @@ -36,7 +37,7 @@ If your application already has an AI chat interface or agentic experience, you Use this option if your organization requires a custom conversation flow, backend orchestration, and a tailored analytics experience for your users. |=== -Regardless of integration mode, ThoughtSpot’s semantic layer, data context, and security features ensure trusted and governed analytics for all users. +Regardless of integration mode, ThoughtSpot's semantic layer, data context, and security features ensure trusted and governed analytics for all users. === Spotter MCP Server license ThoughtSpot Spotter MCP Server is available as an add-on with the following link:https://www.thoughtspot.com/pricing[license plans]: @@ -69,7 +70,7 @@ The remote MCP server hosted by ThoughtSpot. | Your ThoughtSpot instance where data models, Liveboards, and security policies exist. + - Executes queries and generates visualizations -- Enforces data security with RLS and CLS rules. +- Enforces data security with row-level security (RLS) and column-level security (CLS) rules. - In integrations using the MCP Server with Spotter 3 support, it provides additional capabilities such as advanced analytics, reasoning, forecasting, automatic data source selection, and deep research. |=== diff --git a/modules/ROOT/pages/mcp-server-client-connection.adoc b/modules/ROOT/pages/mcp-server-client-connection.adoc index 82cb6fd91..89618fe66 100644 --- a/modules/ROOT/pages/mcp-server-client-connection.adoc +++ b/modules/ROOT/pages/mcp-server-client-connection.adoc @@ -29,7 +29,7 @@ When your MCP client is connected to the ThoughtSpot Spotter MCP Server, the AI Before you begin, review the following prerequisites: * Ensure that your setup has access to a ThoughtSpot application instance with 10.11.0.cl or a later release. For MCP Server with Spotter 3 capabilities, ensure that your ThoughtSpot instance is 26.2.0.cl or later. -* Ensure that the users have the necessary permissions to view data from relevant models and tables in ThoughtSpot. Existing RLS/CLS rules on tables are enforced automatically in data source responses. To create charts or Liveboards from a conversation session, data download and content creation privileges are required. +* Ensure that users have the necessary permissions to view data from relevant models and tables in ThoughtSpot. Existing row-level security (RLS) and column-level security (CLS) rules on tables are enforced automatically in data source responses. Creating charts or dashboards from a conversation session requires data download and content creation privileges. == Using ThoughtSpot Spotter with ChatGPT and Claude The ThoughtSpot Spotter MCP Server is available directly from the ChatGPT and Claude marketplaces. If you want to use ThoughtSpot Spotter with ChatGPT or Claude, you can install it directly from these marketplaces instead of manually configuring it. @@ -131,11 +131,11 @@ To verify the integration: . Start a chat session with the agent and verify the response. . Verify that MCP tools are being called to generate responses. See the xref:mcp-tool-reference-guide.adoc[MCP tool reference guide] for information about tool calls. -. Try the Liveboard creation request and verify whether a Liveboard is added to your ThoughtSpot application. +. Try the dashboard creation request and verify whether a Liveboard is added to your ThoughtSpot application. == Using the ThoughtSpot skill with skill-aware clients Some LLM clients, such as Claude, support skills—packaged sets of instructions and best practices that an agent can load on demand to perform specific tasks more reliably. -Alongside the ThoughtSpot Spotter MCP Server, ThoughtSpot provides a companion skill that helps skill-aware clients use the MCP tools more effectively. For example, routing questions intelligently, streaming its thinking as it works, and surfacing ThoughtSpot's own visualizations instead of generating charts. +Alongside the ThoughtSpot Spotter MCP Server, ThoughtSpot provides a companion skill that helps skill-aware clients use the MCP tools more effectively, such as routing questions intelligently, streaming its thinking as it works, and surfacing ThoughtSpot's own visualizations instead of generating new charts. [NOTE] ==== @@ -183,26 +183,19 @@ If user authentication fails, or if the server returns HTTP 500, 401, or 403 sta * Verify whether the user has the necessary privileges to view data or create content. == Switching between Orgs +If the user has access to multiple ThoughtSpot Orgs, the ThoughtSpot Spotter MCP Server defaults to the last Org the user was logged into. -If you have access to multiple ThoughtSpot Orgs, the ThoughtSpot Spotter MCP Server defaults to the last Org you were logged into. To switch to a different Org, switch to the Org in ThoughtSpot and re-authenticate with your MCP client. +To switch Orgs mid-session without re-authentication, use the `list_orgs` and `switch_org` MCP tools: -To switch Orgs: +. Call `list_orgs` to retrieve the Orgs your account can access, along with each Org's ID and display name. +. Call `switch_org` with the `org_id` of the Org you want to switch to. +The MCP Server switches your active Org immediately. Any subsequent tool calls in the session run in the context of the new Org. -. Log in to your ThoughtSpot instance. -. Select the Org you want to work with using the *Org switcher* in the top navigation bar, next to the help icon. For example, Org A. -. Return to your MCP client and authenticate with your ThoughtSpot credentials. -The MCP Server connects to the Org you selected for all subsequent requests. - -To switch to a different Org later: - -. Log out of ThoughtSpot. -. Log in to your ThoughtSpot instance. -. Select the new Org using the *Org switcher*. For example, Org B. -. Return to your MCP client and re-authenticate with your ThoughtSpot credentials. +For more information, see xref:mcp-tool-reference-spotter3.adoc#list_orgs[list_orgs] and xref:mcp-tool-reference-spotter3.adoc#switch_org[switch_org]. [NOTE] ==== -You must repeat this process each time you want to change Orgs. Currently, the ThoughtSpot Spotter MCP Server cannot switch Orgs mid-session without re-authentication. +`list_orgs` and `switch_org` are available on OAuth-authenticated connections on Org-enabled ThoughtSpot instances only. ==== == Additional resources diff --git a/modules/ROOT/pages/mcp-server-spotter3.adoc b/modules/ROOT/pages/mcp-server-spotter3.adoc index e5f7cdfaf..fe03bf9c8 100644 --- a/modules/ROOT/pages/mcp-server-spotter3.adoc +++ b/modules/ROOT/pages/mcp-server-spotter3.adoc @@ -68,7 +68,10 @@ The agent calls `send_session_message` with the `analytical_session_id` and the ThoughtSpot confirms receipt with a `success` response and begins processing the question asynchronously. The answer is not returned in this call. 4. *Agent polls `get_session_updates` for results* + -The agent calls `get_session_updates` repeatedly in a loop until `is_done` is `true`. ThoughtSpot streams updates incrementally across multiple polls. The agent must accumulate updates from every poll. ThoughtSpot returns the following update types: +The agent calls `get_session_updates` repeatedly in a loop until `is_done` is `true`. ThoughtSpot streams updates incrementally across multiple polls. The agent must accumulate updates from every poll. + +//// +ThoughtSpot returns the following update types: * `text-chunk` - real-time thinking narration from Spotter describing what it is doing, streamed in fragments. Concatenate chunks in order to form the complete narration. * `text` - complete standalone messages representing clarifications, caveats, or assumptions Spotter made during analysis. @@ -77,18 +80,24 @@ The agent calls `get_session_updates` repeatedly in a loop until `is_done` is `t ** `answer_query` - the ThoughtSpot search query used to generate the answer. ** `iframe_url` - an embeddable URL for rendering an interactive ThoughtSpot visualization. ** `answer_id` - a unique identifier for the answer, used as input for creating a dashboard. +//// -5. *A dashboard is generated from the results (optional)* + +5. *User generates a dashboard with the results (optional)* + The user can choose to save answers from the conversation as a ThoughtSpot dashboard. For this workflow, the agent extracts the `answer_id` and `answer_title` from each `answer` type update collected during polling and calls `create_dashboard`. + ThoughtSpot creates a dashboard and returns a `dashboard_id` and a `dashboard_url`, a direct link to the dashboard in the ThoughtSpot UI. -6. *User asks a follow-up question (optional)* + +The other optional tool calls include: + +* *User asks a follow-up question (optional)* + The user can ask a follow-up question in the same session. The agent calls `send_session_message` again using the same `analytical_session_id`. ThoughtSpot retains the full conversation context automatically. The agent returns to step 4 to poll for the follow-up response. -7. *User switches to a different Org (optional)* + +* *User switches to a different Org (optional)* + If the user belongs to more than one Org and connects over OAuth, the agent calls `list_orgs` to return all accessible Orgs and flags the Org that the user is currently logged in. When the user requests a switch, the agent calls `switch_org` with the target `org_id`. For more information, see xref:mcp-tool-reference-spotter3.adoc#org-switching-tools[Org switching tools]. +* *Agent searches for existing content (optional)* + +If the user refers to content that already exists, for example, "open the regional sales Liveboard", the agent calls `search_objects` with a search term and optional filters such as object type, author, tag, or verified status. `search_objects` returns a ranked list of matching objects with their metadata and deep links. + == Additional resources * For information about MCP, see the link:https://modelcontextprotocol.io[Model Context Protocol specification, window=_blank]. * For implementation details, see the link:https://github.com/thoughtspot/mcp-server[MCP Server GitHub repository, window=_blank]. diff --git a/modules/ROOT/pages/mcp-tool-reference-spotter3.adoc b/modules/ROOT/pages/mcp-tool-reference-spotter3.adoc index dc3bcd942..d2f2e6822 100644 --- a/modules/ROOT/pages/mcp-tool-reference-spotter3.adoc +++ b/modules/ROOT/pages/mcp-tool-reference-spotter3.adoc @@ -8,8 +8,6 @@ The ThoughtSpot Spotter Model Context Protocol (MCP) Server integration exposes tools for running natural language analytics queries and searching existing ThoughtSpot content. The core analytics pattern is: **create a session** → **send a message** → **poll for updates**. The `search_objects` tool is independent of this workflow and can be called at any time. -* <> + -Search for existing ThoughtSpot content by name or description. * <> + Start an analytical session. * <> + @@ -18,6 +16,8 @@ Send a natural language question or follow-up. Poll for streamed responses. * <> + Create a dashboard from session answers. +* <> + +Search for existing ThoughtSpot content by name or description. * <> + List the Orgs your account can access. (OAuth connections on Org-enabled instances only) * <> + @@ -25,69 +25,64 @@ Switch your active Org for the current session. (OAuth connections on Org-enable * <> + Verify that the MCP Server is reachable. -[#search_objects] -== search_objects -Search for existing ThoughtSpot content by name or description, and return the matching objects with their metadata and deep links. - -Use this tool when a user refers to content that already exists. For example, "open the regional sales Liveboard" or "what dashboards has Priya built". The -`search_objects` tool is independent of the analysis session workflow. Tt does not require a session and does not need to be called before `create_analysis_session`. - -`search_objects` returns identifiers and metadata only. It never returns the object's data or contents, and it does not run queries. - -To answer a data question, use the session workflow instead. - -=== Input parameters +[#create_analysis_session] +== create_analysis_session +Start an analytical session with ThoughtSpot's analytics agent. This is the required first step before sending any questions. -[cols="2,4", options="header"] -|==== -|Field|Description +Sessions are conversational. Once created, you can send multiple follow-up questions to the same session without calling `create_analysis_session` again. -|`query` + -__Required__ -|The search term, matched against object names and descriptions. Must be non-empty. +=== Input parameter +The `data_source_id` is optional. Provide this when the user has specified or confirmed a data source, or when context makes a particular source obvious. Omit to let ThoughtSpot automatically select the most relevant source based on the question. -|`types` + -__Optional__ -|Restrict results to these object types. Accepts an array of `LIVEBOARD`, `LIVEBOARD_VIZ`, `ANSWER`, `WORKSHEET`. Omit to search all types. +=== Example call -|`author_name` + -__Optional__ -|Restrict results to objects authored by this user, matched against the author's display name. Case-insensitive substring match. +[div tabbed-code] +-- +[source,javascript] +---- +const session = await callMCPTool("create_analysis_session", { + data_source_id: "model-guid-123" // Optional. GUID of the ThoughtSpot model to query. Omit to let ThoughtSpot automatically select the most relevant data source. +}); +---- -|`tag` + -__Optional__ -|Restrict results to objects carrying this tag or sticker, matched by tag name. Case-insensitive substring match. +[source,python] +---- +call_mcp_tool( + "create_analysis_session", + { + "data_source_id": "model-guid-123" # Optional. GUID of the ThoughtSpot model to query. + }, +) +---- +-- -|`modified_since` + -__Optional__ -|Return only objects last modified on or after this epoch-millisecond timestamp. +=== Response -|`verified_only` + -__Optional__ -|If `true`, return only objects marked as verified. +[source,json] +---- +{ + "analytical_session_id": "session-guid-abc123" +} +---- -|`limit` + -__Optional__ -|Maximum number of results to return. Positive integer. Defaults to `10`. +* `analytical_session_id`: Session ID. Pass this to `send_session_message` and `get_session_updates`. -|`cursor` + -__Optional__ -|Opaque pagination cursor returned as `next_cursor` by a previous call. Omit on the first page. -|==== +* Always capture the returned `analytical_session_id`. It is required for all subsequent calls. -=== Object types +[#send_session_message] +== send_session_message +Send a natural language analytical question or follow-up to an existing session. The agent processes requests asynchronously, so this tool does not return the answer directly; use `get_session_updates` to retrieve the response. -The `types` input parameter and the `type` field on each result use the same tokens. -Any value returned in a result can be passed back as a `types` filter. +=== Input parameters -[cols="1,3", options="header"] +[cols="2,4", options="header"] |==== -|Value|Meaning +|Field|Description -|`LIVEBOARD`|A Liveboard. -|`LIVEBOARD_VIZ`|A single visualization pinned on a Liveboard. Distinct from a standalone Answer. Render this as "Liveboard viz". -|`ANSWER`|A saved Answer. -|`WORKSHEET`|A data model object. +|`analytical_session_id` | The session to send the message to. Obtained from the `create_analysis_session` call. +|`message`|A natural language analytical question or follow-up to send to the ThoughtSpot agent. +|`additional_context` + +__Optional__|Can be used to provide external information relating to the question. For example, "The user's fiscal year starts in April," or "The user is a manager of the West region." |==== === Example call @@ -96,27 +91,25 @@ Any value returned in a result can be passed back as a `types` filter. -- [source,javascript] ---- -const results = await callMCPTool("search_objects", { - query: "regional sales", // Required. Search term matched against object names and descriptions. - types: ["LIVEBOARD", "LIVEBOARD_VIZ"], // Optional. Restrict to these object types. - author_name: "Priya", // Optional. Case-insensitive substring match on author display name. - tag: "Certified", // Optional. Case-insensitive substring match on tag name. - verified_only: true, // Optional. Return only verified objects. - limit: 5 // Optional. Maximum results to return. Defaults to 10. +const sendMessage = await callMCPTool("send_session_message", { + analytical_session_id: "sess_abc123", // Session ID from create_analysis_session. + message: "What were total sales by region last quarter?", // User's natural language question. + additional_context: "The user's fiscal year starts in April. " + + "Focus on underperforming regions only." // Optional. External information to influence the analysis. }); ---- [source,python] ---- call_mcp_tool( - "search_objects", + "send_session_message", { - "query": "regional sales", # Required. Search term matched against object names and descriptions. - "types": ["LIVEBOARD", "LIVEBOARD_VIZ"], # Optional. Restrict to these object types. - "author_name": "Priya", # Optional. Case-insensitive substring match on author display name. - "tag": "Certified", # Optional. Case-insensitive substring match on tag name. - "verified_only": True, # Optional. Return only verified objects. - "limit": 5, # Optional. Maximum results to return. Defaults to 10. + "analytical_session_id": "sess_abc123", # Session ID from create_analysis_session. + "message": "What were total sales by region last quarter?", # User's natural language question. + "additional_context": ( # Optional. External information + "The user's fiscal year starts in April." + "Focus on underperforming regions only." # to influence the analysis. + ), }, ) ---- @@ -124,328 +117,75 @@ call_mcp_tool( === Response -A call returns one of three outcomes. - -==== Successful match - -`status` is omitted when the search returned results. - [source,json] ---- { - "results": [ - { - "object_id": "b2c4e6a8-1234-4f5a-9abc-def012345678", - "title": "Regional Sales Performance", - "type": "LIVEBOARD", - "author_name": "Priya Raman", - "description": "Weekly sales tracking by region and rep.", - "tags": ["Sales", "Certified"], - "last_modified": "2026-05-15T14:30:00.000Z", - "verified": true, - "external_link": "https://your-instance.thoughtspot.cloud/#/insights/pinboard/b2c4e6a8-1234-4f5a-9abc-def012345678", - "query": null, - "confidence": 0.94 - }, - { - "object_id": "b2c4e6a8-1234-4f5a-9abc-def012345678", - "visualization_id": "77f1a0d3-5678-4b21-8e90-aa1122334455", - "title": "Sales by Region", - "type": "LIVEBOARD_VIZ", - "author_name": "Priya Raman", - "tags": ["Sales"], - "last_modified": "2026-05-15T14:30:00.000Z", - "verified": false, - "external_link": "https://your-instance.thoughtspot.cloud/#/insights/pinboard/b2c4e6a8-1234-4f5a-9abc-def012345678/77f1a0d3-5678-4b21-8e90-aa1122334455", - "query": "sales by region monthly", - "confidence": 0.81 - } - ], - "next_cursor": "10" + "success": true } ---- -==== No results +* `success`: Confirms whether the message was successfully received by the agent. -The search ran successfully but nothing matched. +[NOTE] +==== +* After a successful send, immediately begin polling with `get_session_updates`. +* Do not send a second message until `get_session_updates` returns `is_done: true`. The agent processes one message at a time per session. +* To ask a follow-up question, reuse the same `analytical_session_id`. There is no need to create a new session. +==== -[source,json] ----- -{ - "status": "no_results", - "results": [], - "next_cursor": null -} ----- +[#get_session_updates] +== get_session_updates +Poll for the latest response from a ThoughtSpot analytics session. Call this repeatedly after `send_session_message` until `is_done` is `true`. -Tell the user that nothing matched and suggest broadening the search term or removing a filter. Do not synthesize results. +**Important**: A single call to `get_session_updates` will rarely contain the full response. Spotter streams its work incrementally, including intermediate thinking steps, across multiple polling calls. You must accumulate updates from every poll and combine them to get the complete picture. -==== Error +=== Input parameters +Send the `analytical_session_id` to specify the session to retrieve updates for. -The search could not be completed. +=== Example call -[source,json] +[div tabbed-code] +-- +[source,typescript] ---- -{ - "status": "error", - "results": [], - "error": { - "code": "RATE_LIMITED", - "message": "ThoughtSpot rate limit reached. Try again shortly.", - "retryable": true - } -} +const updates = await callMCPTool("get_session_updates", { + analytical_session_id: "session-guid-abc123" // Session ID from the `create_analysis_session` call. +}); ---- -If `retryable` is `true`, wait briefly and retry the same call. If `retryable` is `false`, surface the `message` to the user and do not retry automatically. - -=== Response fields - -[cols="2,1,4", options="header"] -|==== -|Field|Type|Description - -|`status`|String -|Omitted on a successful hit list. -`no_results` means the search ran but matched nothing. -`error` means the search failed and `error` is populated. +[source,python] +---- +call_mcp_tool( + "get_session_updates", + {"analytical_session_id": "sess_abc123"}, # Session ID from create_analysis_session. +) +---- +-- -|`results`|Array -|Ranked list of matching objects, most relevant first. Empty for `no_results` and `error`. +=== Response +Each poll returns a wrapper object with an `is_done` flag and a `session_updates` array. Session updates stream across multiple polling calls. Accumulate them all before rendering the final answer. -|`next_cursor`|String -|Cursor to pass back as `cursor` to retrieve the next page. `null` when there are no more results. Omitted on `error`. +`session_updates` objects use three `type` values: -|`error`|Object -|Present only when `status` is `error`. Contains `code`, `message`, and `retryable`. +[cols="1,1,3", options="header"] |==== +|Type|`is_thinking`|Description -=== Fields on each result - -[cols="2,1,4", options="header"] -|==== -|Field|Type|Description +|`step_notification`|`true` +|A short heading announcing the step Spotter is about to start, such as `Searching data models` or `Running query`. +Step headings arrive as soon as Spotter begins each step, before the narration text for that step. +Render these immediately so the user sees progress in real time. -|`object_id`|String -|GUID of the object. -For a `LIVEBOARD_VIZ` result, this is the GUID of the parent Liveboard, not the visualization. +|`text_chunk`|`true` (thinking) or `false` (final) +|A fragment of Spotter's narration. Concatenate chunks to form the complete narration string. +When `is_thinking` is `false`, the chunk is part of the final answer narration, not an intermediate thinking step. -|`visualization_id`|String -|Present only on `LIVEBOARD_VIZ` results. GUID of the specific visualization pinned on the Liveboard identified by `object_id`. +|`answer`|`false` +|The analytical result. Contains a title, the ThoughtSpot search query used, an embeddable `iframe_url`, and an `answer_id` for creating dashboards. +Exactly one `answer` update is present per question. +|==== -|`title`|String -|Display name of the object. - -|`type`|String -|Object type: `LIVEBOARD`, `LIVEBOARD_VIZ`, `ANSWER`, or `WORKSHEET`. Can be passed back as a `types` filter. - -|`author_name`|String -|Display name of the user who authored the object. - -|`description`|String -|Description of the object. Omitted when the object has none. - -|`tags`|Array of strings -|Names of the tags or stickers applied to the object. - -|`last_modified`|String -|ISO 8601 timestamp of the last modification. For example, `2026-05-15T14:30:00.000Z`. Omitted when unavailable. Render as a plain date. - -|`verified`|Boolean -|Whether the object is marked as verified. - -|`external_link`|String -|Deep link to open the object in the ThoughtSpot UI. This link opens in a browser tab. It is not an embeddable iframe URL. - -|`query`|String -|For an Answer or Liveboard viz, the search tokens that define it. For example, `sales by region monthly`. `null` for a Liveboard. - -|`confidence`|Number -|Relevance score for the search term. Use for ranking only. Do not display this value to the user. -|==== - -=== Pagination - -`search_objects` returns up to `limit` results per call (default `10`). -When more results are available, the response includes a `next_cursor` value. -Pass this value back as `cursor` in the next call to retrieve the following page. -When `next_cursor` is `null`, there are no further results. - -[source,javascript] ----- -// Fetch the first page -let response = await callMCPTool("search_objects", { query: "sales" }); - -// Fetch the next page if a cursor was returned -if (response.next_cursor) { - response = await callMCPTool("search_objects", { - query: "sales", - cursor: response.next_cursor - }); -} ----- - -[#create_analysis_session] -== create_analysis_session -Start an analytical session with ThoughtSpot's analytics agent. This is the required first step before sending any questions. - -Sessions are conversational. Once created, you can send multiple follow-up questions to the same session without calling `create_analysis_session` again. - -=== Input parameter -The `data_source_id` is optional. Provide this when the user has specified or confirmed a data source, or when context makes a particular source obvious. Omit to let ThoughtSpot automatically select the most relevant source based on the question. - -=== Example call - -[div tabbed-code] --- -[source,javascript] ----- -const session = await callMCPTool("create_analysis_session", { - data_source_id: "model-guid-123" // Optional. GUID of the ThoughtSpot model to query. Omit to let ThoughtSpot automatically select the most relevant data source. -}); ----- - -[source,python] ----- -call_mcp_tool( - "create_analysis_session", - { - "data_source_id": "model-guid-123" # Optional. GUID of the ThoughtSpot model to query. - }, -) ----- --- - -=== Response - -[source,json] ----- -{ - "analytical_session_id": "session-guid-abc123" -} ----- - -* `analytical_session_id`: Session ID. Pass this to `send_session_message` and `get_session_updates`. - -* Always capture the returned `analytical_session_id`. It is required for all subsequent calls. - -[#send_session_message] -== send_session_message -Send a natural language analytical question or follow-up to an existing session. The agent processes requests asynchronously, so this tool does not return the answer directly; use `get_session_updates` to retrieve the response. - -=== Input parameters - -[cols="2,4", options="header"] -|==== -|Field|Description - -|`analytical_session_id` | The session to send the message to. Obtained from the `create_analysis_session` call. -|`message`|A natural language analytical question or follow-up to send to the ThoughtSpot agent. -|`additional_context` + -__Optional__|Can be used to provide external information relating to the question. For example, “The user’s fiscal year starts in April”, or “The user is a manager of the West region”. -|==== - -=== Example call - -[div tabbed-code] --- -[source,javascript] ----- -const sendMessage = await callMCPTool("send_session_message", { - analytical_session_id: "sess_abc123", // Session ID from create_analysis_session. - message: "What were total sales by region last quarter?", // User's natural language question. - additional_context: "The user's fiscal year starts in April. " + - "Focus on underperforming regions only." // Optional. External information to influence the analysis. -}); ----- - -[source,python] ----- -call_mcp_tool( - "send_session_message", - { - "analytical_session_id": "sess_abc123", # Session ID from create_analysis_session. - "message": "What were total sales by region last quarter?", # User's natural language question. - "additional_context": ( # Optional. External information - "The user's fiscal year starts in April." - "Focus on underperforming regions only." # to influence the analysis. - ), - }, -) ----- --- - -=== Response - -[source,json] ----- -{ - "success": true -} ----- - -* `success`: Confirms whether the message was successfully received by the agent. - -[NOTE] -==== -* After a successful send, immediately begin polling with `get_session_updates`. -* Do not send a second message until `get_session_updates` returns `is_done: true`. The agent processes one message at a time per session. -* To ask a follow-up question, reuse the same `analytical_session_id`. There is no need to create a new session. -==== - -[#get_session_updates] -== get_session_updates -Poll for the latest response from a ThoughtSpot analytics session. Call this repeatedly after `send_session_message` until `is_done` is `true`. - -**Important**: A single call to `get_session_updates` will rarely contain the full response. Spotter streams its work incrementally, including intermediate thinking steps, across multiple polling calls. You must accumulate updates from every poll and combine them to get the complete picture. - -=== Input parameters -Send the `analytical_session_id` to specify the session to retrieve updates for. - -=== Example call - -[div tabbed-code] --- -[source,typescript] ----- -const updates = await callMCPTool("get_session_updates", { - analytical_session_id: "session-guid-abc123" // Session ID from the `create_analysis_session` call. -}); ----- - -[source,python] ----- -call_mcp_tool( - "get_session_updates", - {"analytical_session_id": "sess_abc123"}, # Session ID from create_analysis_session. -) ----- --- - -=== Response -Each poll returns a wrapper object with an `is_done` flag and a `session_updates` array. Session updates stream across multiple polling calls. Accumulate them all before rendering the final answer. - -`session_updates` objects use three `type` values: - -[cols="1,1,3", options="header"] -|==== -|Type|`is_thinking`|Description - -|`step_notification`|`true` -|A short heading announcing the step Spotter is about to start, such as `Searching data models` or `Running query`. -Step headings arrive as soon as Spotter begins each step, before the narration text for that step. -Render these immediately so the user sees progress in real time. - -|`text_chunk`|`true` (thinking) or `false` (final) -|A fragment of Spotter's narration. Concatenate chunks to form the complete narration string. -When `is_thinking` is `false`, the chunk is part of the final answer narration, not an intermediate thinking step. - -|`answer`|`false` -|The analytical result. Contains a title, the ThoughtSpot search query used, an embeddable `iframe_url`, and an `answer_id` for creating dashboards. -Exactly one `answer` update is present per question. -|==== - -Poll returning intermediate updates: +Poll returning intermediate updates: [source,json] ---- @@ -509,29 +249,19 @@ The `step_notification` type was introduced alongside the default response forma === Handling streamed responses Spotter queries are processed asynchronously and streamed in real time. This means the full response is never contained in a single `get_session_updates` call. -Each call to `get_session_updates` returns only the updates generated since the previous call. The `session_updates` array may indicate that Spotter is still processing with an `is_thinking` state, may include intermediate updates, or may contain several updates at once. Updates typically arrive as text or text-chunk types, reflecting Spotter’s ongoing reasoning, before the final answer update is provided. This intermediate content shows Spotter’s step-by-step thought process and should be preserved and presented to the user for transparency into how the answer is derived. +Each call to `get_session_updates` returns only the updates generated since the previous call. The `session_updates` array may indicate that Spotter is still processing with an `is_thinking` state, may include intermediate updates, or may contain several updates at once. Updates typically arrive as `step_notification` or `text_chunk` types, reflecting Spotter's ongoing reasoning, before the final answer update is provided. This intermediate content shows Spotter's step-by-step thought process and should be preserved and presented to the user for transparency into how the answer is derived. A typical response sequence might look like: -. Thinking narration: `text-chunk` updates with `is_thinking` state describing what Spotter is doing. -. Clarifications or caveats: `text` updates explaining assumptions, filters applied, or potential ambiguities in the question. -. Intermediate conclusions: partial results or contextual notes before the final answer. +. Step headings: `step_notification` updates announcing each step Spotter is about to start. +. Thinking narration: `text_chunk` updates with `is_thinking: true` describing what Spotter is doing. +. Clarifications or caveats: `text_chunk` updates with `is_thinking: false` explaining assumptions, filters applied, or potential ambiguities in the question. . The final answer: one or more `answer` updates containing the visualization title, the underlying query, and the embeddable iframe URL. This means a complete response might span 5–20+ `get_session_updates` calls and contain many `session_update` objects before `is_done` becomes `true`. All of this content, the thinking, the narration, and the final answer, should be accumulated and presented together to give the user the full picture. - -[#full-response] -=== Full response (raw event stream) - -By default, `get_session_updates` returns a simplified response optimized for host agent understanding. -For integrations that need granular metadata about Spotter's internal tool calls, you can enable the full raw event stream. - -For guidance on when to use the full response and how to enable it, see xref:mcp-connect-custom-chatbot.adoc#accessing-full-tool-responses[Accessing full tool responses]. - -==== Default response format - -Three update types. Flat, fixed keys. `is_thinking` is the top-level flag that distinguishes intermediate reasoning from the final answer. +=== Default response format +Includes three types, `step_notification`, `text_chunk`, `answer`. Flat, fixed keys, `is_thinking` as the top-level flag that distinguishes intermediate reasoning from the final answer. [source,json] ---- @@ -545,8 +275,32 @@ Three update types. Flat, fixed keys. `is_thinking` is the top-level flag that d "iframe_url":"https://your-instance.thoughtspot.cloud/?tsmcp=true#/embed/conv-assist-answer?..."} ---- -==== Full response format (raw upstream events) +==== Type definition: session_update + +Each item in the `session_updates` list is a `session_update` object. The `type` field determines which other fields are present. + +[cols="2,2,4", options="header"] +|==== +|Field|Type|Description +.3+|`type` +|`"step_notification"`|A short heading announcing the step Spotter is about to start, such as `Searching data models` or `Running query`. +|`"text_chunk"` | A streaming fragment of Spotter's narration. Concatenate all chunks to reconstruct the full text. +|`"answer"`|Populates `answer_title`, `answer_query`, `answer_data_source_id`, `iframe_url` fields. A data visualization result with a title, the underlying query, and an embeddable URL. +|`text`|__String__|The text content of the message. Present only when `type` is `"step_notification"` or `"text_chunk"`. For `"text_chunk"` updates, concatenate all chunks to form the complete message. +|`answer_title`|__String__|A human-readable title describing what the answer shows. Present only when `type` is `"answer"`. +|`answer_data_source_id`|__String__|GUID of the data source used to generate the answer. Present only when `type` is `"answer"`. +|`answer_query`|__String__|The search query ThoughtSpot used to generate the answer. Present only when `type` is `"answer"`. Useful for explaining to users what data was queried or for diagnosing unexpected results. +|`iframe_url`|__String__|An embeddable URL for rendering the answer as an interactive visualization. Present only when `type` is `"answer"`. Use this to display a live chart or table if your environment supports iframes. +|==== + +[#full-response] +=== Full response (raw event stream) +By default, `get_session_updates` returns a simplified response optimized for host agent understanding. +For integrations that need granular metadata about Spotter's internal tool calls, you can enable the full raw event stream. +For guidance on when to use the full response and how to enable it, see xref:mcp-connect-custom-chatbot.adoc#accessing-full-tool-responses[Accessing full tool responses]. + +==== Full response format (raw upstream events) When `enable-raw-session-updates=true` is appended to your MCP endpoint URL, `get_session_updates` returns the raw Spotter event stream. The full response does not include a preconstructed `iframe_url`. You must build it yourself. For guidance, see xref:mcp-connect-custom-chatbot.adoc#accessing-full-tool-responses[Accessing full tool responses]. @@ -574,23 +328,6 @@ The full response does not include a preconstructed `iframe_url`. You must build For the complete event schema, see the xref:spotter-agent-apis.adoc#_api_response_2[Spotter Agent API, window=_blank]. -=== Type definition: session_update - -Each item in the `session_updates` list is a `session_update` object. The `type` field determines which other fields are present. - -[cols="2,2,4", options="header"] -|==== -|Field|Type|Description -.3+|`type` -|`"text"`|A complete natural language message from the agent. -|`"text-chunk"` | A streaming chunk of a longer message. Concatenate all chunks to reconstruct the full text. -|`"answer"`|Populates `answer_title`, `answer_query`, `iframe_url` fields. A data visualization result with a title, the underlying query, and an embeddable URL. -|`text`|__String__|The text content of the message. Present only when `type` is `"text"` or `"text-chunk"`. For `"text-chunk"` updates, concatenate all chunks in order to form the complete message. -|`answer_title`|__String__|A human-readable title describing what the answer shows. Present only when `type` is `"answer"`. -|`answer_query`|__String__|The search query ThoughtSpot used to generate the answer. Present only when `type` is `"answer"`. Useful for explaining to users what data was queried or for diagnosing unexpected results. -|`iframe_url`|__String__|An embeddable URL for rendering the answer as an interactive visualization. Present only when `type` is `"answer"`. Use this to display a live chart or table if your environment supports iframes. -|==== - [#create_dashboard] == create_dashboard Create a ThoughtSpot dashboard from answers generated in an analysis session. @@ -673,10 +410,269 @@ dashboard = call_mcp_tool( |`dashboard_url`|A link to the newly created dashboard in ThoughtSpot. |==== +[#search_objects] +== search_objects +Search for existing ThoughtSpot content by name or description, and return the matching objects with their metadata and deep links. + +Use this tool when a user refers to content that already exists. For example, "open the regional sales Liveboard" or "what dashboards has Priya built". The +`search_objects` tool is independent of the analysis session workflow. It does not require a session and does not need to be called before `create_analysis_session`. + +`search_objects` returns identifiers and metadata only. It never returns the object's data or contents, and it does not run queries. + +To answer a data question, use the session workflow instead. + +=== Input parameters + +[cols="2,4", options="header"] +|==== +|Field|Description + +|`query` + +__Required__ +|The search term, matched against object names and descriptions. Must be non-empty. + +|`types` + +__Optional__ +|Restrict results to these object types. Accepts an array of `LIVEBOARD`, `LIVEBOARD_VIZ`, `ANSWER`, `WORKSHEET`. Omit to search all types. + +|`author_name` + +__Optional__ +|Restrict results to objects authored by this user, matched against the author's display name. Case-insensitive substring match. + +|`tag` + +__Optional__ +|Restrict results to objects carrying this tag or sticker, matched by tag name. Case-insensitive substring match. + +|`modified_since` + +__Optional__ +|Return only objects last modified on or after this epoch-millisecond timestamp. + +|`verified_only` + +__Optional__ +|If `true`, return only objects marked as verified. + +|`limit` + +__Optional__ +|Maximum number of results to return. Positive integer. Defaults to `10`. + +|`cursor` + +__Optional__ +|Opaque pagination cursor returned as `next_cursor` by a previous call. Omit on the first page. +|==== + +=== Object types + +The `types` input parameter and the `type` field on each result use the same tokens. +Any value returned in a result can be passed back as a `types` filter. + +[cols="1,3", options="header"] +|==== +|Value|Meaning + +|`LIVEBOARD`|A Liveboard. +|`LIVEBOARD_VIZ`|A single visualization pinned on a Liveboard. Distinct from a standalone Answer. Render this as "Liveboard viz". +|`ANSWER`|A saved Answer. +|`WORKSHEET`|A data model object. +|==== + +=== Example call + +[div tabbed-code] +-- +[source,javascript] +---- +const results = await callMCPTool("search_objects", { + query: "regional sales", // Required. Search term matched against object names and descriptions. + types: ["LIVEBOARD", "LIVEBOARD_VIZ"], // Optional. Restrict to these object types. + author_name: "Priya", // Optional. Case-insensitive substring match on author display name. + tag: "Certified", // Optional. Case-insensitive substring match on tag name. + verified_only: true, // Optional. Return only verified objects. + limit: 5 // Optional. Maximum results to return. Defaults to 10. +}); +---- + +[source,python] +---- +call_mcp_tool( + "search_objects", + { + "query": "regional sales", # Required. Search term matched against object names and descriptions. + "types": ["LIVEBOARD", "LIVEBOARD_VIZ"], # Optional. Restrict to these object types. + "author_name": "Priya", # Optional. Case-insensitive substring match on author display name. + "tag": "Certified", # Optional. Case-insensitive substring match on tag name. + "verified_only": True, # Optional. Return only verified objects. + "limit": 5, # Optional. Maximum results to return. Defaults to 10. + }, +) +---- +-- + +=== Response + +A call returns one of three outcomes. + +==== Successful match + +`status` is omitted when the search returned results. + +[source,json] +---- +{ + "results": [ + { + "object_id": "b2c4e6a8-1234-4f5a-9abc-def012345678", + "title": "Regional Sales Performance", + "type": "LIVEBOARD", + "author_name": "Priya Raman", + "description": "Weekly sales tracking by region and rep.", + "tags": ["Sales", "Certified"], + "last_modified": "2026-05-15T14:30:00.000Z", + "verified": true, + "external_link": "https://your-instance.thoughtspot.cloud/#/insights/pinboard/b2c4e6a8-1234-4f5a-9abc-def012345678", + "query": null, + "confidence": 0.94 + }, + { + "object_id": "b2c4e6a8-1234-4f5a-9abc-def012345678", + "visualization_id": "77f1a0d3-5678-4b21-8e90-aa1122334455", + "title": "Sales by Region", + "type": "LIVEBOARD_VIZ", + "author_name": "Priya Raman", + "tags": ["Sales"], + "last_modified": "2026-05-15T14:30:00.000Z", + "verified": false, + "external_link": "https://your-instance.thoughtspot.cloud/#/insights/pinboard/b2c4e6a8-1234-4f5a-9abc-def012345678/77f1a0d3-5678-4b21-8e90-aa1122334455", + "query": "sales by region monthly", + "confidence": 0.81 + } + ], + "next_cursor": "10" +} +---- + +==== No results + +The search ran successfully but nothing matched. + +[source,json] +---- +{ + "status": "no_results", + "results": [], + "next_cursor": null +} +---- + +Tell the user that nothing matched and suggest broadening the search term or removing a filter. Do not synthesize results. + +==== Error + +The search could not be completed. + +[source,json] +---- +{ + "status": "error", + "results": [], + "error": { + "code": "RATE_LIMITED", + "message": "ThoughtSpot rate limit reached. Try again shortly.", + "retryable": true + } +} +---- + +If `retryable` is `true`, wait briefly and retry the same call. If `retryable` is `false`, surface the `message` to the user and do not retry automatically. + +=== Response fields + +[cols="2,1,4", options="header"] +|==== +|Field|Type|Description + +|`status`|String +|Omitted on a successful hit list. +`no_results` means the search ran but matched nothing. +`error` means the search failed and `error` is populated. + +|`results`|Array +|Ranked list of matching objects, most relevant first. Empty for `no_results` and `error`. + +|`next_cursor`|String +|Cursor to pass back as `cursor` to retrieve the next page. `null` when there are no more results. Omitted on `error`. + +|`error`|Object +|Present only when `status` is `error`. Contains `code`, `message`, and `retryable`. +|==== + +=== Fields on each result + +[cols="2,1,4", options="header"] +|==== +|Field|Type|Description + +|`object_id`|String +|GUID of the object. +For a `LIVEBOARD_VIZ` result, this is the GUID of the parent Liveboard, not the visualization. + +|`visualization_id`|String +|Present only on `LIVEBOARD_VIZ` results. GUID of the specific visualization pinned on the Liveboard identified by `object_id`. + +|`title`|String +|Display name of the object. + +|`type`|String +|Object type: `LIVEBOARD`, `LIVEBOARD_VIZ`, `ANSWER`, or `WORKSHEET`. Can be passed back as a `types` filter. + +|`author_name`|String +|Display name of the user who authored the object. + +|`description`|String +|Description of the object. Omitted when the object has none. + +|`tags`|Array of strings +|Names of the tags or stickers applied to the object. + +|`last_modified`|String +|ISO 8601 timestamp of the last modification. For example, `2026-05-15T14:30:00.000Z`. Omitted when unavailable. Render as a plain date. + +|`verified`|Boolean +|Whether the object is marked as verified. + +|`external_link`|String +|Deep link to open the object in the ThoughtSpot UI. This link opens in a browser tab. It is not an embeddable iframe URL. + +|`query`|String +|For an Answer or Liveboard viz, the search tokens that define it. For example, `sales by region monthly`. `null` for a Liveboard. + +|`confidence`|Number +|Relevance score for the search term. Use for ranking only. Do not display this value to the user. +|==== + +=== Pagination + +`search_objects` returns up to `limit` results per call (default `10`). +When more results are available, the response includes a `next_cursor` value. +Pass this value back as `cursor` in the next call to retrieve the following page. +When `next_cursor` is `null`, there are no further results. + +[source,javascript] +---- +// Fetch the first page +let response = await callMCPTool("search_objects", { query: "sales" }); + +// Fetch the next page if a cursor was returned +if (response.next_cursor) { + response = await callMCPTool("search_objects", { + query: "sales", + cursor: response.next_cursor + }); +} +---- + == Visualizations embedded in iframe When displaying the embedded visualization using the `iframe_url` property, the following user interaction features are included by default: - [cols="2,2,2", options="header"] |=== | Area @@ -723,12 +719,11 @@ When displaying the embedded visualization using the `iframe_url` property, the | Visible |=== -The following features are not supported directly. However, you can use the *Make a Copy* option to access these capabilities: +The following features are not supported directly in visualizations embedded in an iframe. However, you can use the *Make a Copy* option to access these capabilities: -* Drill down * Changing filters * Changing chart type or chart configuration -* Show underlying data, view query SQL or query visualizer +* View query SQL or query visualizer * SpotIQ analysis [#org-switching-tools] From dc9104eae8b02ff63c2c4c103e3f2b88f2ff9307 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Wed, 19 Aug 2026 12:06:22 +0530 Subject: [PATCH 073/154] formatting fix --- .../pages/mcp-server-client-connection.adoc | 30 ++++++++++--------- 1 file changed, 16 insertions(+), 14 deletions(-) diff --git a/modules/ROOT/pages/mcp-server-client-connection.adoc b/modules/ROOT/pages/mcp-server-client-connection.adoc index 89618fe66..36c9936f1 100644 --- a/modules/ROOT/pages/mcp-server-client-connection.adoc +++ b/modules/ROOT/pages/mcp-server-client-connection.adoc @@ -167,20 +167,6 @@ See the xref:mcp-tool-reference-guide.adoc[MCP tool reference guide] for informa Skill availability and installation steps may vary by client. Refer to your client's documentation for instructions on adding and managing skills. ==== -== Troubleshooting errors - -MCP Server is not connected:: - -* Verify that the MCP Server is reachable. -* Ensure that you have access to a ThoughtSpot instance. -* Ensure that there are no configuration errors. -* If the issue persists, verify the logs and contact ThoughtSpot Support for assistance. - -Authentication failure:: -If user authentication fails, or if the server returns HTTP 500, 401, or 403 status codes: -* Verify whether the MCP Server endpoint and ThoughtSpot host are correctly configured in your client and are reachable. -* Check whether the user session has expired. Log in to your ThoughtSpot application to start a new session. -* Verify whether the user has the necessary privileges to view data or create content. == Switching between Orgs If the user has access to multiple ThoughtSpot Orgs, the ThoughtSpot Spotter MCP Server defaults to the last Org the user was logged into. @@ -198,6 +184,22 @@ For more information, see xref:mcp-tool-reference-spotter3.adoc#list_orgs[list_o `list_orgs` and `switch_org` are available on OAuth-authenticated connections on Org-enabled ThoughtSpot instances only. ==== +== Troubleshooting errors + +MCP Server is not connected:: + +* Verify that the MCP Server is reachable. +* Ensure that you have access to a ThoughtSpot instance. +* Ensure that there are no configuration errors. +* If the issue persists, verify the logs and contact ThoughtSpot Support for assistance. + +Authentication failure:: +If user authentication fails, or if the server returns HTTP 500, 401, or 403 status codes: +* Verify whether the MCP Server endpoint and ThoughtSpot host are correctly configured in your client and are reachable. +* Check whether the user session has expired. Log in to your ThoughtSpot application to start a new session. +* Verify whether the user has the necessary privileges to view data or create content. + + == Additional resources * For information about the MCP Server features and architecture, see xref:mcp-integration.adoc[MCP Server integration]. * To view the MCP Server code, go to the link:https://github.com/thoughtspot/mcp-server[MCP Server GitHub repository, window=_blank]. \ No newline at end of file From ef9de7f5e8be6721de415091c5b49c8a4c8f6393 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Thu, 6 Aug 2026 08:55:48 +0530 Subject: [PATCH 074/154] edits --- modules/ROOT/pages/mcp-server-client-connection.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/ROOT/pages/mcp-server-client-connection.adoc b/modules/ROOT/pages/mcp-server-client-connection.adoc index 36c9936f1..e39893307 100644 --- a/modules/ROOT/pages/mcp-server-client-connection.adoc +++ b/modules/ROOT/pages/mcp-server-client-connection.adoc @@ -134,12 +134,12 @@ To verify the integration: . Try the dashboard creation request and verify whether a Liveboard is added to your ThoughtSpot application. == Using the ThoughtSpot skill with skill-aware clients -Some LLM clients, such as Claude, support skills—packaged sets of instructions and best practices that an agent can load on demand to perform specific tasks more reliably. +Some LLM clients such as Claude support skills. Skills are packaged sets of instructions and best practices that an agent can load on demand to perform specific tasks more reliably. Alongside the ThoughtSpot Spotter MCP Server, ThoughtSpot provides a companion skill that helps skill-aware clients use the MCP tools more effectively, such as routing questions intelligently, streaming its thinking as it works, and surfacing ThoughtSpot's own visualizations instead of generating new charts. [NOTE] ==== -The skill is installed separately from the connector. Connecting the ThoughtSpot Spotter connector (or configuring the MCP server) gives your client access to the available tools. Installing the skill doesn't provide the tools themselves; instead, it helps the client understand when and how to orchestrate those tools effectively. You can use the MCP server without the skill, but clients that support skills generally produce better results when both the connector and the skill are installed. +The skill is installed separately from the connector. Connecting the ThoughtSpot Spotter connector (or configuring the MCP Server) gives your client access to the available tools. Installing the skill doesn't provide the tools themselves; instead, it helps the client understand when and how to orchestrate those tools effectively. You can use the MCP Server without the skill, but clients that support skills generally produce better results when both the connector and the skill are installed. ==== === Before you begin From e1bfe2a79e8a35e9b973a6a1e15826008b8ba9f2 Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Wed, 19 Aug 2026 17:25:51 +0530 Subject: [PATCH 075/154] split the tml file --- .../pages/common/nav-in-product-help.adoc | 2 + modules/ROOT/pages/common/nav-rest-api.adoc | 2 + modules/ROOT/pages/open-issues.adoc | 2 +- modules/ROOT/pages/rest-apiv2-changelog.adoc | 6 +- modules/ROOT/pages/tml-export.adoc | 83 +++ modules/ROOT/pages/tml-import.adoc | 413 +++++++++++++++ modules/ROOT/pages/tml.adoc | 487 +----------------- modules/ROOT/pages/whats-new.adoc | 2 +- src/components/SecondaryHeader/index.tsx | 1 + src/configs/doc-configs.js | 2 +- 10 files changed, 511 insertions(+), 489 deletions(-) create mode 100644 modules/ROOT/pages/tml-export.adoc create mode 100644 modules/ROOT/pages/tml-import.adoc diff --git a/modules/ROOT/pages/common/nav-in-product-help.adoc b/modules/ROOT/pages/common/nav-in-product-help.adoc index 2d9f1a12c..2f6f8dd4e 100644 --- a/modules/ROOT/pages/common/nav-in-product-help.adoc +++ b/modules/ROOT/pages/common/nav-in-product-help.adoc @@ -233,6 +233,8 @@ REST APIs ** link:{{navprefix}}/style-customization-apis[Style customization APIs] ** link:{{navprefix}}/audit-logs[Audit logs] ** link:{{navprefix}}/tml[TML] +*** link:{{navprefix}}/tml-import[Import TML] +*** link:{{navprefix}}/tml-export[Export TML] ** link:{{navprefix}}/collections[Collections] ** link:{{navprefix}}/connections[Connections] ** link:{{navprefix}}/connection-config[Connection configuration] diff --git a/modules/ROOT/pages/common/nav-rest-api.adoc b/modules/ROOT/pages/common/nav-rest-api.adoc index fa8b242f4..a01e7dbcc 100644 --- a/modules/ROOT/pages/common/nav-rest-api.adoc +++ b/modules/ROOT/pages/common/nav-rest-api.adoc @@ -31,6 +31,8 @@ REST APIs *** link:{{navprefix}}/spotter-nl-instructions[Data model instructions APIs ^BETA^] ** link:{{navprefix}}/audit-logs[Audit logs] ** link:{{navprefix}}/tml[TML] +*** link:{{navprefix}}/tml-import[Import TML] +*** link:{{navprefix}}/tml-export[Export TML] ** link:{{navprefix}}/collections[Collections] ** link:{{navprefix}}/connections[Connections] ** link:{{navprefix}}/connection-config[Connection configuration] diff --git a/modules/ROOT/pages/open-issues.adoc b/modules/ROOT/pages/open-issues.adoc index 37d91ef2c..718fc29f6 100644 --- a/modules/ROOT/pages/open-issues.adoc +++ b/modules/ROOT/pages/open-issues.adoc @@ -78,7 +78,7 @@ On exporting and reimporting TML in YAML format in the REST API v2 Playground, t This issue occurs because when reimporting TML invalid characters are added to the TML YAML content in the Playground resulting in an invalid syntax error. **Workaround**: + -See xref:tml.adoc#yamlReimport[YAML reimport in the REST API v2 Playground]. +See xref:tml-import.adoc#yamlReimport[YAML reimport in the REST API v2 Playground]. |===== diff --git a/modules/ROOT/pages/rest-apiv2-changelog.adoc b/modules/ROOT/pages/rest-apiv2-changelog.adoc index bd72e1316..f21342428 100644 --- a/modules/ROOT/pages/rest-apiv2-changelog.adoc +++ b/modules/ROOT/pages/rest-apiv2-changelog.adoc @@ -30,7 +30,7 @@ Two new fields have been added to the TML for Personalized Views. You can see th * A new `author` field is added to the Personalized View TML during export. This field is used to assign ownership during import. * Personalized Views now carry an `obj_id` field for stable cross-environment object identity, consistent with other object types. -For more information, see xref:tml.adoc#personalized-views-portability[Personalized Views portability in TML]. +For more information, see xref:tml-import.adoc#personalized-views-portability[Personalized Views portability in TML]. Collections `obj_id` support::: // SOURCE: SCAL-317357 @@ -863,7 +863,7 @@ Allows you to specify if all objects should be imported during the TML import op * `enable_large_metadata_validation` + Indicates if the TMLs with large and complex metadata should be validated before the import. + -For more information about these attributes, see xref:tml.adoc#_import_tml_objects_asynchronously[Import TML objects asynchronously]. +For more information about these attributes, see xref:tml-import.adoc#_import_tml_objects_asynchronously[Import TML objects asynchronously]. TML import API:: @@ -925,7 +925,7 @@ Validates and imports TML objects asynchronously. Use this API endpoint when imp * `POST /api/rest/2.0/metadata/tml/async/status` + Fetches task status for the async TML import operations. -For more information, see xref:tml.adoc#_import_tml_objects_asynchronously[Import TML objects asynchronously]. +For more information, see xref:tml-import.adoc#_import_tml_objects_asynchronously[Import TML objects asynchronously]. === API enhancements diff --git a/modules/ROOT/pages/tml-export.adoc b/modules/ROOT/pages/tml-export.adoc new file mode 100644 index 000000000..bdaf32488 --- /dev/null +++ b/modules/ROOT/pages/tml-export.adoc @@ -0,0 +1,83 @@ += Export TML +:toc: true +:toclevels: 2 + +:page-title: Export TML +:page-pageid: tml-export +:page-description: Export the TML representation of ThoughtSpot metadata objects via REST API +// SOURCE: SCAL-307283, SCAL-317357 + +[#export-tml] +To export the TML data, your account must have the `DATAMANAGEMENT` (Can manage data) or `ADMINISTRATION` (Can administer ThoughtSpot) privilege. + +The default format to export the objects is YAML in v1, and JSON in v2 APIs. To export the TML representation of the metadata objects from ThoughtSpot in JSON or YAML format, use one of the following endpoints: + +* link:https://developers.thoughtspot.com/docs/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fmetadata%2Fexport-metadata-tml[**POST** /api/rest/2.0/metadata/tml/export] (REST API v2) +* xref:tml-api.adoc#export[**POST** /tspublic/v1/metadata/tml/export] (REST API v1) + +To export the TML representation of the metadata objects in a *batch*, use one of the following endpoints: + +* link:https://developers.thoughtspot.com/docs/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fmetadata%2Fexport-metadata-tml-batched[**POST** /api/rest/2.0/metadata/tml/export/batch] (REST API v2) +* xref:tml-api.adoc#BatchExport[**POST** /tspublic/v1/metadata/tml/export/batch] (REST API v1) + +There are several export options available with these APIs: + +== Metadata specification for Answers +To export a specific metadata object, specify the name or ID of the object. + +For Answer objects, the `identifier` is optional, and you can define parameters such as `session_identifier` and `generation_number` instead. These attributes can be used to export unsaved Answers generated from Spotter queries or Answers that do not have the name and ID assigned. + +== Export associated objects + +To export associated objects, set the following attributes: + +* `export_associated` + +When set to `true`, exports the associated objects for the `export_ids` specified in the API request. The API exports any underlying Models, tables, or views for a given object. By default, the API does not export these underlying objects. +* `export_dependent` + +Specifies if the Tables of the referenced Connection object must be included in the export. +* `export_connection_as_dependent` + +Specifies if a Connection object must be included as a dependent object when exporting a Table, Model, Answer, or Liveboard TML. + +== Export FQNs + +When `export_fqn=true`, the API exports the FQNs of the referenced objects in the TML data. For example, if you are exporting a Liveboard and its associated objects, the API returns the Liveboard TML data with the FQNs of the referenced Model. +Note that the FQN of a referenced object is the same as the GUID of that object. + +ThoughtSpot recommends adding the fqn property before importing the TML objects into the system, because only the name of a referenced object is not sufficient to identify the referenced object during TML import. For example, if your ThoughtSpot instance has two Models with the same name, the TML import for a Liveboard that uses one of these Models would fail unless the Liveboard TML includes the FQN of the referenced object. +The `export_fqn` attribute is useful when ThoughtSpot has multiple objects with the same name and you want to eliminate ambiguity during TML import. The `export_fqn=true` property adds the FQNs of the referenced objects in the TML export API response and saves the manual effort of adding FQNs for TML import. + +For more information about using FQNs during import, see xref:tml-import.adoc#import-tml[Import TML]. + +== Export schema + +Specifies the schema version to use during TML export. For link:https://docs.thoughtspot.com/cloud/latest/models[Models, window=_blank], set `export_schema_version` to v2. +The v1 schema is used for Worksheet objects (Deprecated). + +== Additional export options for REST API v2 +Following are some additional attributes which can be set for exporting objects: + +* `include_obj_id_ref` + +When set to `true`, exports the object ID of the referenced object. This flag will work only when the object ID feature is enabled. Contact ThoughtSpot Support to enable the feature. + +* `include_guid` + +When set to `true`, exports the guid of the object. This flag will work only when the object ID feature is enabled. Contact ThoughtSpot Support to enable the feature. +* `include_obj_id` + +When set to `true`, exports the object ID of the object. This flag will work only when the object ID feature is enabled. Contact ThoughtSpot Support to enable the feature. +* `export_with_associated_feedbacks` + +When set to `true`, exports the TML of an object along with all feedback, such as Spotter or Sage feedback, associated with that object. No feedback file will be exported if there are no feedback entries associated with the object +* `export_column_security_rules` [beta betaBackground]^Beta^ + +When set to `true`, exports the column-level security rules defined on the object. Contact ThoughtSpot Support to enable the feature. +* `export_with_column_aliases` [beta betaBackground]^Beta^ + +When set to `true`, export column aliases of the Model if the data Model includes any link:https://docs.thoughtspot.com/cloud/latest/column-aliases[column aliases, window=_blank]. + +== Export in a batch +This API operation supports exporting User, User Group, and Role objects only. +To export objects in a batch, set the following additional attributes: + +* `batch_size` + +Exports the specified number of objects in a single API request. A batch size of up to 200 objects is allowed for a single API operation. + +* `batch_offset` + +Offsets the API response by the specified number. Batch offset value defines the starting position of the records for the results returned by the API. + +For more information, see the API documentation in REST API v2 Playground and xref:tml-api.adoc[Export a TML object using REST API v1]. diff --git a/modules/ROOT/pages/tml-import.adoc b/modules/ROOT/pages/tml-import.adoc new file mode 100644 index 000000000..562ae15f7 --- /dev/null +++ b/modules/ROOT/pages/tml-import.adoc @@ -0,0 +1,413 @@ += Import TML +:toc: true +:toclevels: 2 + +:page-title: Import TML +:page-pageid: tml-import +:page-description: Import the TML representation of ThoughtSpot metadata objects via REST API +// SOURCE: SCAL-307283, SCAL-317357 + +[NOTE] +==== +If using older versions of TML files for Liveboards, ensure that your TML file has the object name as `liveboard`. Replace any `pinboard` occurrences with `liveboard` before import. +==== + +[#import-tml] +To import a modified TML object, your account must have the `DATAMANAGEMENT` (*Can manage data*) or `ADMINISTRATION` (*Can administer ThoughtSpot*) privilege. + +You can import single or multiple objects using the `tml/import` API. If you are importing TML files one at a time, include the `fqn` property to distinguish objects that have the same name. If you have multiple connections or tables with the same name and the Connection or Table you reference in your TML does not have a unique name, it can lead to invalid object references. Adding `fqn` helps ThoughtSpot differentiate a Table from another with the same name. + +By default, the `fqn` parameter is not present in the TML file. However, you can xref:tml-export.adoc#_export_fqns[export TML with FQNs] and use it during the import. + +You can also set the `skip_diff_check` to `true` to skip diff check before processing TMLs for imports. This attribute helps identify the objects that haven’t been changed since the last import or TML update, and eliminates importing redundant objects. + +To import TML representation of the metadata objects into ThoughtSpot, use one of the following API endpoints: + +* +++POST /api/rest/2.0/metadata/tml/import+++ (REST API v2) +* xref:tml-api.adoc#import[POST /tspublic/v1/metadata/tml/import] (REST API v1) + +//While the v1 API accepts a string containing a JSON array of TML objects to upload, in YAML or JSON format, the v2 accepts it only in the JSON format. + +There are multiple kinds of imports possible: + +* `PARTIAL` imports all objects that validate successfully, and ignores objects that do not validate successfully. +* `ALL_OR_NONE` imports the objects that validate successfully. +* `VALIDATE_ONLY` validates the objects but does not import them. +* `PARTIAL_OBJECT` (only applicable to REST API v2) +imports objects that validate successfully and skips the objects that do not validate successfully. If the import fails for a visualization object in a Liveboard TML, the Liveboard will be imported without that visualization object. Similarly, if importing a relationship in a logical table fails, the table TML will be imported with warnings in the API response. + +You can also specify additional parameters to set the Org context and skip CDW validation checks for Table TMLs. + +[NOTE] +==== +If you import only a Model object, it may take some time for the Model to become available in the ThoughtSpot system. You may need to wait for a few seconds to create answers and Liveboards. + +However, if you import a Model along with Liveboards, answers, and other dependent objects in a single API call, the imported objects will be immediately available for use. +==== + +[#personalized-views-portability] +== Personalized Views portability [earlyAccess eaBackground]#Early Access# + +Personalized Views support improved portability across ThoughtSpot environments. When importing a Personalized View TML set the `enable_personalized_view_upsert` to `true` in the API request to `POST /api/rest/2.0/metadata/tml/import`. ThoughtSpot then checks the target environment for an existing Personalized View with a matching `obj_id`. If a match is found, the import updates the existing view rather than creating a duplicate. If no match is found, a new Personalized View is created. + +To enable this feature for your instance, contact your ThoughtSpot administrator. + +Two new fields are added to the TML, make it easier to migrate Personalized Views between environments without creating duplicates. + +`author`::: +A new `author` field is added to the Personalized View TML during export. This field is used to delegate ownership to another user during import. + +`obj_id`::: +A new `obj_id` field provides stable cross-environment object identity for inter-Org deployments. Use the same `obj_id` value across environments to ensure consistent identity during migrations. + + + +=== Example for a Personalized View TML with Object ID + +[source,yaml] +---- + views: + - view_guid: ff83055b-a867-43e7-978e-106e907e1912 + obj_id: California-LT-ff83855b + name: California - LT + view_filters: + - column: + - Retail Sales - Classic::Store State + oper: in + values: + - California + is_public: false + author: + username: user1 + user_email: user1@thoughtspot.com +---- + +=== Limitation without this feature enabled + +ThoughtSpot's link:https://docs.thoughtspot.com/cloud/latest/personalized-liveboard-views[personalized Liveboard views] let users apply filters and save configurations as named views on a Liveboard. +In multi-environment deployments (for example, a Dev instance and a Prod instance), these user-saved views can be lost when a Liveboard is updated and re-imported using the xref:#import-tml[TML import API] or the UI *Import TML* option. +If the import is performed by an administrator account, all personalized views saved by end users are removed as part of this replacement. + +Why this happens?:: + +Personalized views are stored as user-owned objects linked to the Liveboard’s GUID. When an admin imports a Liveboard TML that matches an existing GUID, the import operation overwrites the Liveboard, and the associated user views are not carried forward. ++ +This happens because personalized views are created and usually owned by end users in a different environment (likely a Prod instance). They are not included in Liveboard TML files exported from a development or staging environment, so the import has no record of them. + +Workarounds:: +. Import as a non-admin user - ++ +The simplest workaround is to perform the final TML import in the production environment using a *non-admin user account* that has edit access to the Liveboard, rather than an admin account. +Because non-admin users do not have the authority to overwrite user-linked metadata during import, ThoughtSpot preserves the existing personalized views attached to the Liveboard. +. Embed existing saved views in the TML before import - ++ +You can export the current saved views from the production Liveboard, append them to the updated TML, and then import the combined TML. + +== Import TML objects asynchronously +The REST v1 and v2 `metadata/tml/import` APIs import TML objects synchronously. When you try to import large and complex metadata objects, the synchronous import operation takes more time to process data and sometimes can result in a timeout error. + +To allow mutually exclusive import tasks to run in parallel, process TML objects asynchronously, and check import task status, ThoughtSpot provides the following APIs: + +* +++POST /api/rest/2.0/metadata/tml/async/import+++ + +Creates an import TML tasks and processes TMLs asynchronously + +* +++POST /api/rest/2.0/metadata/tml/async/status+++ + +Fetches status of import tasks + +=== Schedule import tasks + +You can import TML objects asynchronously by scheduling TML import tasks via `POST` request to POST `/api/rest/2.0/metadata/tml/async/import` API endpoint. You can send the following parameters in the API request body: + +[width="100%" cols="2,4,1"] +[options='header'] +|==== +|Form parameter|Description| Default +|`metadata_tmls` |__Array of strings__. Array of the TML strings. |__None__ +|`create_new` + +__Optional__ |__Boolean__. To create TML objects with new GUIDs during import, specify `true`. By default, ThoughtSpot updates the existing objects that have the same GUID as the objects you are importing. | `false` +|`all_orgs_context` + +__Optional__ |__Boolean__. Specify if import operation must be run for all Orgs on your instance. + +__Requires Org administration privileges to access TML objects across all Orgs.__| `false` + +|`import_policy` a|__String__. Available from 10.5.0.cl. Policy to follow during import. The allowed values are: + +* `PARTIAL` + +Imports objects that validate successfully. Skips the objects that do not validate successfully and their dependent objects if any. +* `ALL_OR_NONE` + +Imports all objects that validate successfully. If the import fails for one object, no objects will be imported. +* `VALIDATE_ONLY` + +Validates the objects but does not import them. +* `PARTIAL_OBJECT` + +Imports objects that validate successfully and skips the objects that do not validate successfully. If the import fails for a visualization object in a Liveboard TML, the Liveboard will be imported without that visualization object. Similarly, if importing a relationship in a logical table fails, the table TML will be imported with warnings in the API response. +| `PARTIAL_OBJECT` + +|`skip_diff_check` + +__Optional__ +|__Boolean__. When set to `true`, skips the diff check before processing TML objects for import. By default, ThoughtSpot compares each TML object against its last imported version and skips objects that have not changed, which reduces unnecessary reimports. Set to `true` to bypass this check and reimport all objects regardless of whether they have changed. |`false` +|`enable_large_metadata_validation` + +__Optional__ + |__Boolean__. Available from 10.5.0.cl. Enables validation for large metadata objects. Set to `true` if the database contains multiple thousands of tables. When enabled, it allows for schema validation of one table at a time and helps circumvent the metadata fetching limitations of the Cloud Data Warehouse (CDW). +|`false` +|==== +//// + + +|`skip_cdw_validation_for_tables` + +__Optional__ |__Boolean__. Skips Cloud Data Warehouse validation for table TML imports. | `false` +//// +==== Example request + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-host}/api/rest/2.0/metadata/tml/async/import' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "metadata_tmls": [ + "{\\\"guid\\\": \\\"2ed8192a-1e9d-47d1-810d-52b14cb0e9fe\\\",\\\"liveboard\\\": {\\\"name\\\": \\\"Total Sales\\\",\\\"visualizations\\\": [{\\\"id\\\": \\\"Viz_1\\\",\\\"answer\\\": {\\\"name\\\": \\\"Total quantity purchased, Total sales by region\\\",\\\"description\\\": \\\"test\\\",\\\"tables\\\": [{\\\"id\\\": \\\"(Sample) Retail - Apparel\\\",\\\"name\\\": \\\"(Sample) Retail - Apparel\\\"}],\\\"search_query\\\": \\\"[region] [quantity purchased] [sales]\\\",\\\"answer_columns\\\": [{\\\"name\\\": \\\"Total quantity purchased\\\"},{\\\"name\\\": \\\"Total sales\\\"},{\\\"name\\\": \\\"region\\\"}],\\\"table\\\": {\\\"table_columns\\\": [{\\\"column_id\\\": \\\"Total quantity purchased\\\",\\\"show_headline\\\": false},{\\\"column_id\\\": \\\"Total sales\\\",\\\"show_headline\\\": false},{\\\"column_id\\\": \\\"region\\\",\\\"show_headline\\\": false}],\\\"ordered_column_ids\\\": [\\\"region\\\",\\\"Total quantity purchased\\\",\\\"Total sales\\\"],\\\"client_state\\\": \\\"\\\",\\\"client_state_v2\\\": \\\"{\\\\\\\"tableVizPropVersion\\\\\\\": \\\\\\\"V1\\\\\\\"}\\\"},\\\"chart\\\": {\\\"type\\\": \\\"COLUMN\\\",\\\"chart_columns\\\": [{\\\"column_id\\\": \\\"Total quantity purchased\\\"},{\\\"column_id\\\": \\\"Total sales\\\"},{\\\"column_id\\\": \\\"region\\\"}],\\\"axis_configs\\\": [{\\\"x\\\": [\\\"region\\\"],\\\"y\\\": [\\\"Total quantity purchased\\\",\\\"Total sales\\\"]}],\\\"client_state\\\": \\\"\\\",\\\"client_state_v2\\\": \\\"{\\\\\\\"version\\\\\\\": \\\\\\\"V4DOT2\\\\\\\",\\\\\\\"chartProperties\\\\\\\": {\\\\\\\"responsiveLayoutPreference\\\\\\\": \\\\\\\"AUTO_ON\\\\\\\",\\\\\\\"chartSpecific\\\\\\\": {}},\\\\\\\"axisProperties\\\\\\\": [{\\\\\\\"id\\\\\\\": \\\\\\\"f6701821-5630-49cd-b26f-f98bebb4e98e\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"Y\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"Total quantity purchased\\\\\\\"],\\\\\\\"isOpposite\\\\\\\": false}},{\\\\\\\"id\\\\\\\": \\\\\\\"1e086aef-236d-4cf0-8909-9e04e04a1ac4\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"Y\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"Total sales\\\\\\\"],\\\\\\\"isOpposite\\\\\\\": true}},{\\\\\\\"id\\\\\\\": \\\\\\\"7be648d3-c791-43e4-bb13-63fea808f326\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"X\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"region\\\\\\\"]}}],\\\\\\\"systemSeriesColors\\\\\\\": [{\\\\\\\"serieName\\\\\\\": \\\\\\\"Total quantity purchased\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#48D1E0\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"Total sales\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#2E75F0\\\\\\\"}]}\\\"},\\\"display_mode\\\": \\\"CHART_MODE\\\"},\\\"viz_guid\\\": \\\"b8b38851-5980-40a1-bd88-608b7a9c6e86\\\"},{\\\"id\\\": \\\"Viz_2\\\",\\\"answer\\\": {\\\"name\\\": \\\"Total sales in a year\\\",\\\"tables\\\": [{\\\"id\\\": \\\"(Sample) Retail - Apparel\\\",\\\"name\\\": \\\"(Sample) Retail - Apparel\\\"}],\\\"search_query\\\": \\\"[sales] [store] [date].monthly [date].'\''this year'\''\\\",\\\"answer_columns\\\": [{\\\"name\\\": \\\"Month(date)\\\"},{\\\"name\\\": \\\"Total sales\\\"},{\\\"name\\\": \\\"store\\\"}],\\\"table\\\": {\\\"table_columns\\\": [{\\\"column_id\\\": \\\"Month(date)\\\",\\\"show_headline\\\": false},{\\\"column_id\\\": \\\"Total sales\\\",\\\"show_headline\\\": false},{\\\"column_id\\\": \\\"store\\\",\\\"show_headline\\\": false}],\\\"ordered_column_ids\\\": [\\\"store\\\",\\\"Month(date)\\\",\\\"Total sales\\\"],\\\"client_state\\\": \\\"\\\",\\\"client_state_v2\\\": \\\"{\\\\\\\"tableVizPropVersion\\\\\\\": \\\\\\\"V1\\\\\\\"}\\\"},\\\"chart\\\": {\\\"type\\\": \\\"LINE\\\",\\\"chart_columns\\\": [{\\\"column_id\\\": \\\"Month(date)\\\"},{\\\"column_id\\\": \\\"Total sales\\\"},{\\\"column_id\\\": \\\"store\\\"}],\\\"axis_configs\\\": [{\\\"x\\\": [\\\"Month(date)\\\"],\\\"y\\\": [\\\"Total sales\\\"],\\\"color\\\": [\\\"store\\\"]}],\\\"client_state\\\": \\\"\\\",\\\"client_state_v2\\\": \\\"{\\\\\\\"version\\\\\\\": \\\\\\\"V4DOT2\\\\\\\",\\\\\\\"chartProperties\\\\\\\": {\\\\\\\"responsiveLayoutPreference\\\\\\\": \\\\\\\"AUTO_ON\\\\\\\",\\\\\\\"chartSpecific\\\\\\\": {}},\\\\\\\"axisProperties\\\\\\\": [{\\\\\\\"id\\\\\\\": \\\\\\\"feb33c4a-614b-4623-9d12-1c4cf2250801\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"Y\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"Total sales\\\\\\\"],\\\\\\\"isOpposite\\\\\\\": false}},{\\\\\\\"id\\\\\\\": \\\\\\\"e89293cb-d10a-40d5-b787-81be33cc8b81\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"X\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"Month(date)\\\\\\\"]}}],\\\\\\\"systemSeriesColors\\\\\\\": [{\\\\\\\"serieName\\\\\\\": \\\\\\\"6a4acb32-9036-4d4c-a830-f2b06966a322\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#48D1E0\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"39e5242e-43d0-4ef7-8673-73b12433e0c5\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#2E75F0\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"arizona (85226)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#2E75F0\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"arizona (86001)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#48D1E0\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"california (91006)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#FCC838\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"california (94702)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#06BF7F\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"colorado (80301)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#8C62F5\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"colorado (80920)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#FF8142\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"connecticut (06110)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#ABC7F9\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"connecticut (06854)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#B5ECF2\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"delaware (19702)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#FDE9AF\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"georgia (30022)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#9BE5CB\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"georgia (30329)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#D1C0FB\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"idaho (83704)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#FFCCB3\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"illinois (60062)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#2359B6\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"illinois (60642)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#369FAA\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"indiana (46250)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#BF982A\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"iowa (50266)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#049160\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"maryland (21045)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#6A4ABA\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"massachusetts (01701)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#C26232\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"massachusetts (02215)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#71A1F4\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"michigan (48103)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#82DFE9\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"michigan (49512)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#FCD977\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"minnesota (55369)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#56D3A8\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"minnesota (55420)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#B094F8\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"missouri (63144)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#FFA97E\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"montana (59106)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#163772\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"montana (59718)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#22636B\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"nevada (89052)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#785F1A\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"nevada (89145)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#025B3C\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"new hampshire (03860)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#422E75\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"new jersey (07936)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#7A3D1F\\\\\\\"}]}\\\"},\\\"display_mode\\\": \\\"CHART_MODE\\\"},\\\"viz_guid\\\": \\\"7efc7b0e-e680-44a4-ba9c-3bd5d7272367\\\"},{\\\"id\\\": \\\"Viz_3\\\",\\\"answer\\\": {\\\"name\\\": \\\"Total sales by item type and region\\\",\\\"tables\\\": [{\\\"id\\\": \\\"(Sample) Retail - Apparel\\\",\\\"name\\\": \\\"(Sample) Retail - Apparel\\\"}],\\\"search_query\\\": \\\"[sales] [item type] [region]\\\",\\\"answer_columns\\\": [{\\\"name\\\": \\\"Total sales\\\"},{\\\"name\\\": \\\"item type\\\"},{\\\"name\\\": \\\"region\\\"}],\\\"table\\\": {\\\"table_columns\\\": [{\\\"column_id\\\": \\\"Total sales\\\",\\\"show_headline\\\": false},{\\\"column_id\\\": \\\"item type\\\",\\\"show_headline\\\": false},{\\\"column_id\\\": \\\"region\\\",\\\"show_headline\\\": false}],\\\"ordered_column_ids\\\": [\\\"item type\\\",\\\"region\\\",\\\"Total sales\\\"],\\\"client_state\\\": \\\"\\\",\\\"client_state_v2\\\": \\\"{\\\\\\\"tableVizPropVersion\\\\\\\": \\\\\\\"V1\\\\\\\"}\\\"},\\\"chart\\\": {\\\"type\\\": \\\"STACKED_COLUMN\\\",\\\"chart_columns\\\": [{\\\"column_id\\\": \\\"Total sales\\\"},{\\\"column_id\\\": \\\"item type\\\"},{\\\"column_id\\\": \\\"region\\\"}],\\\"axis_configs\\\": [{\\\"x\\\": [\\\"item type\\\"],\\\"y\\\": [\\\"Total sales\\\"],\\\"color\\\": [\\\"region\\\"]}],\\\"client_state\\\": \\\"\\\",\\\"client_state_v2\\\": \\\"{\\\\\\\"version\\\\\\\": \\\\\\\"V4DOT2\\\\\\\",\\\\\\\"chartProperties\\\\\\\": {\\\\\\\"responsiveLayoutPreference\\\\\\\": \\\\\\\"AUTO_ON\\\\\\\",\\\\\\\"chartSpecific\\\\\\\": {}},\\\\\\\"axisProperties\\\\\\\": [{\\\\\\\"id\\\\\\\": \\\\\\\"a330db6d-3714-4b5f-aed7-cca5ab679502\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"Y\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"Total sales\\\\\\\"],\\\\\\\"isOpposite\\\\\\\": false}},{\\\\\\\"id\\\\\\\": \\\\\\\"96ac1ce3-7efd-455e-a569-2cd0792b5f95\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"X\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"item type\\\\\\\"]}}],\\\\\\\"systemSeriesColors\\\\\\\": [{\\\\\\\"serieName\\\\\\\": \\\\\\\"Total sales\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#48D1E0\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"92153012-664c-458e-9a74-6138c5030838\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#2E75F0\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"east\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#06BF7F\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"midwest\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#FCC838\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"south\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#48D1E0\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"southwest\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#71A1F4\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"west\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#2E75F0\\\\\\\"}]}\\\"},\\\"display_mode\\\": \\\"CHART_MODE\\\"},\\\"viz_guid\\\": \\\"9de47a0e-6f20-40ba-9a52-3374ee530f09\\\"},{\\\"id\\\": \\\"Viz_4\\\",\\\"answer\\\": {\\\"name\\\": \\\"Total sales by state\\\",\\\"tables\\\": [{\\\"id\\\": \\\"(Sample) Retail - Apparel\\\",\\\"name\\\": \\\"(Sample) Retail - Apparel\\\"}],\\\"search_query\\\": \\\"[state] [store] [sales]\\\",\\\"answer_columns\\\": [{\\\"name\\\": \\\"Total sales\\\"},{\\\"name\\\": \\\"state\\\"},{\\\"name\\\": \\\"store\\\"}],\\\"table\\\": {\\\"table_columns\\\": [{\\\"column_id\\\": \\\"Total sales\\\",\\\"show_headline\\\": false},{\\\"column_id\\\": \\\"state\\\",\\\"show_headline\\\": false},{\\\"column_id\\\": \\\"store\\\",\\\"show_headline\\\": false}],\\\"ordered_column_ids\\\": [\\\"state\\\",\\\"store\\\",\\\"Total sales\\\"],\\\"client_state\\\": \\\"\\\",\\\"client_state_v2\\\": \\\"{\\\\\\\"tableVizPropVersion\\\\\\\": \\\\\\\"V1\\\\\\\"}\\\"},\\\"chart\\\": {\\\"type\\\": \\\"GEO_AREA\\\",\\\"chart_columns\\\": [{\\\"column_id\\\": \\\"Total sales\\\"},{\\\"column_id\\\": \\\"state\\\"},{\\\"column_id\\\": \\\"store\\\"}],\\\"axis_configs\\\": [{\\\"x\\\": [\\\"state\\\"],\\\"y\\\": [\\\"Total sales\\\"]}],\\\"client_state\\\": \\\"\\\",\\\"client_state_v2\\\": \\\"{\\\\\\\"version\\\\\\\": \\\\\\\"V4DOT2\\\\\\\",\\\\\\\"chartProperties\\\\\\\": {\\\\\\\"chartSpecific\\\\\\\": {}},\\\\\\\"axisProperties\\\\\\\": [{\\\\\\\"id\\\\\\\": \\\\\\\"e4943da4-f159-470c-836b-7c6c55d59c2f\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"Y\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"Total sales\\\\\\\"],\\\\\\\"isOpposite\\\\\\\": false}},{\\\\\\\"id\\\\\\\": \\\\\\\"b99d582a-b215-4381-89ad-280c451979e3\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"X\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"state\\\\\\\"]}}],\\\\\\\"systemMultiColorSeriesColors\\\\\\\": [{\\\\\\\"serieName\\\\\\\": \\\\\\\"Total sales\\\\\\\",\\\\\\\"colorMap\\\\\\\": [{\\\\\\\"serieName\\\\\\\": \\\\\\\"state\\\\\\\",\\\\\\\"color\\\\\\\": [\\\\\\\"#ffffb2\\\\\\\",\\\\\\\"#fddd87\\\\\\\",\\\\\\\"#fba35d\\\\\\\",\\\\\\\"#f75534\\\\\\\",\\\\\\\"#f9140a\\\\\\\",\\\\\\\"#d70315\\\\\\\",\\\\\\\"#b10026\\\\\\\"]}]}]}\\\"},\\\"display_mode\\\": \\\"CHART_MODE\\\"},\\\"viz_guid\\\": \\\"4ab1ed61-2930-46d4-af6f-778279d7414a\\\"}],\\\"filters\\\": [{\\\"column\\\": [\\\"region\\\"],\\\"oper\\\": \\\"in\\\",\\\"values\\\": [\\\"Midwest\\\"],\\\"is_mandatory\\\": false,\\\"is_single_value\\\": false,\\\"display_name\\\": \\\"region\\\"}],\\\"layout\\\": {\\\"tabs\\\": [{\\\"name\\\": \\\"Tab 1\\\",\\\"description\\\": \\\"\\\",\\\"tiles\\\": [{\\\"visualization_id\\\": \\\"Viz_1\\\",\\\"x\\\": 0,\\\"y\\\": 0,\\\"height\\\": 8,\\\"width\\\": 6},{\\\"visualization_id\\\": \\\"Viz_4\\\",\\\"x\\\": 6,\\\"y\\\": 0,\\\"height\\\": 8,\\\"width\\\": 6}],\\\"id\\\": \\\"2c4014b5-a606-4639-8ad0-01032ff3fc13\\\"},{\\\"name\\\": \\\"Tab 2\\\",\\\"description\\\": \\\"\\\",\\\"tiles\\\": [{\\\"visualization_id\\\": \\\"Viz_2\\\",\\\"x\\\": 0,\\\"y\\\": 0,\\\"height\\\": 8,\\\"width\\\": 6},{\\\"visualization_id\\\": \\\"Viz_3\\\",\\\"x\\\": 6,\\\"y\\\": 0,\\\"height\\\": 8,\\\"width\\\": 6}],\\\"id\\\": \\\"185b4875-e7c5-43d2-a9bc-0a404107a3ec\\\"}]}}}\", \"info\": { \"filename\": \"Copy of Total Sales.liveboard.tml\", \"name\": \"Copy of Total Sales\", \"id\": \"2ed8192a-1e9d-47d1-810d-52b14cb0e9fe\", \"type\": \"liveboard\", \"status\": { \"status_code\": \"OK\" } }" + ], + "create_new": true, + "all_orgs_context": false, +}' +---- + +==== Example response + +If the API request is successful, ThoughtSpot schedules an import task, and returns the task name and ID in the API response: + +[source,JSON] +---- +{ + "tenant_id": "default-tenant-id", + "org_id": 0, + "task_id": "075c322f-b000-4776-9c44-89e13420980c", + "task_name": "ASYNC_TML_26:Nov:2024-06:06:24", + "import_response": null, + "task_status": "IN_QUEUE", + "author_id": "08c6b203-ff6e-4ed8-b923-35ebbbfef27b", + "import_policy": "PARTIAL_OBJECT", + "created_at": null, + "in_progress_at": null, + "completed_at": null, + "total_object_count": 2, + "object_processed_count": null, + "modified_at": null, + "author_display_name": "UserA" +} +---- + +===== Response codes + +[options="header", cols="1,4"] +|==== +|HTTP status code|Description +|**200**|Async TML Import Task submitted successfully +|**400**|Invalid request +|**401**|Unauthorized access +|**403**|Forbidden access +|**500**|Unexpected Error +|==== + +=== Fetch status of the TML import task + +To fetch the status of a scheduled import task, send a `POST` request to the `POST /api/rest/2.0/metadata/tml/async/status` API endpoint. + +In the request body, include the following attributes: + +[width="100%" cols="2,4,1"] +[options='header'] +|==== +|Form parameter|Description| Default +|`task_ids` |__Array of strings__. Task IDs assigned to the scheduled TML async import operations. | __None__ +| `task_status` | __Array of strings__. Status of the scheduled import tasks to filter on. The following options are available: + + +* `COMPLETED` + +* `IN_QUEUE` + +* `IN_PROGRESS` + +* `FAILED` +| __None__ +|`author_identifier` + +__Optional__ |__String__. GUID of the author who initiated the import request. | __None__ +|`include_import_response` + +__Optional__ |__Boolean__. Specify whether to include import response in the task status objects.| `false` +|`record_offset` + +__Optional__ |__Integer__. The offset point, starting from where the task status should +be included in the response. | `0` +|`record_size` + +__Optional__ a|__Integer__. The number of task statuses to include in the +response starting from offset position. + +[NOTE] +==== +The maximum limit for the `record_size` that user can pass in an API request is 50. If the `record_size` exceeds this threshold, the API returns a bad request error. To extend the `record_size` limit, contact ThoughtSpot Support. +==== +| `5` + +|==== + +[IMPORTANT] +==== +You can poll up to 100 API requests per minute to get details of your TML import tasks. The API returns an error if you exceed this rate limit. +==== + +==== Example request + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-host}/api/rest/2.0/metadata/tml/async/status' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "record_offset": 0, + "record_size": 5, + "include_import_response": true, + "task_ids": [ + "c8c8c4da-0bc8-4460-8039-cfa7fd598335" + ], + "task_status": [ + "COMPLETED" + ], + "author_identifier": "95ac814f-eb01-4625-93c7-c7624b29d226" +}' +---- + +==== Example response + +If the API request is successful, ThoughtSpot returns the status details of the TML async import tasks. +If Orgs are enabled on your instance, the API returns task status only for objects within the current Org context. + +[source,JSON] +---- +{ + "status_list": [ + { + "tenant_id": "default-tenant-id", + "org_id": 0, + "task_id": "c8c8c4da-0bc8-4460-8039-cfa7fd598335", + "task_name": "ASYNC_TML_26:Nov:2024-06:06:24", + "import_response": { + "object": [ + { + "filename": "tml_0", + "zip_filename": "zip_tml_0", + "response": { + "status": { + "status_code": "ERROR", + "error_message": "Invalid YAML/JSON syntax in file." + } + }, + "request_index": 0 + }, + { + "filename": "tml_1", + "zip_filename": "zip_tml_1", + "response": { + "status": { + "status_code": "ERROR", + "error_message": "Invalid YAML/JSON syntax in file." + } + }, + "request_index": 1 + } + ], + "status": { + "status_code": "OK", + "error_code": 0, + "error_message": "" + } + }, + "task_status": "COMPLETED", + "author_id": "08c6b203-ff6e-4ed8-b923-35ebbbfef27b", + "import_policy": "PARTIAL_OBJECT", + "created_at": 1732601184212, + "in_progress_at": 1732601184255, + "completed_at": 1732601184476, + "total_object_count": 2, + "object_processed_count": 2, + "modified_at": 1732601184476, + "author_display_name": "UserA" + } + ], + "last_batch": true +} +---- + +===== Response codes + +[options="header", cols="1,4"] +|==== +|HTTP status code|Description +|**200**|Async TML import task status fetched successfully +|**400**|Invalid request +|**401**|Unauthorized access +|**403**|Forbidden access +|**500**|Unexpected Error +|==== + +[#yamlReimport] +== YAML reimport in REST API v2 Playground +If you are using the REST API Playground to import TML in YAML format, note that copying YAML content directly in the input field will likely result in the `Invalid YAML/JSON syntax in file` error. +When you copy the YAML output from the export TML API response in the Playground, the copied content is wrapped in quotation marks and include escaped newline characters (`\n`). When you paste this content directly in the `metadata_tml` input field, the API Playground double-escapes characters or removes necessary newline (`\n`) characters. Due to improper formatting, the YAML input becomes invalid for import, resulting in the `Invalid YAML/JSON syntax in file` error. + +To work around this issue, follow these steps: + +. After you +++export TML+++ in the Playground, use the `copy to clipboard` option to copy the YAML output from the API response as shown in this video. + ++ + +[div videoContainer] +-- +video::./images/tml-export.mp4[width=100%,options="autoplay,loop"] +-- ++ +The output copied from the API response is enclosed in quotation marks (`"`). +For example, `"guid: a162289a-c1ab-427e-9985-8fb5f7c7e539\nliveboard:\n name: Liveboard 1\n"`. +. Paste the YAML output copied from the export TML API response into a text editor. +. Remove the quotation marks, update the TML, and ensure that the YAML is properly formatted: + +`guid: a162289a-c1ab-427e-9985-8fb5f7c7e539\nliveboard:\n name: Liveboard 1\n` +. When +++importing TML in the Playground+++, do not paste the YAML directly into the `metadata_tmls` input field. Instead, use the JSON editor to add the YAML. +. To open the JSON editor, click *View JSON*. + +In the JSON preview, you'll see the following code: ++ +[source,JSON] +---- +{ + "metadata_tmls": [ + "metadata_tmls3", + "metadata_tmls5", + ], + "import_policy": "PARTIAL", + "create_new": false, + "all_orgs_context": false +} +---- +. Remove the text in the `metadata_tmls` array and paste your YAML content inside the array. If you are importing more than one TML, use a comma after pasting a TML YAML and then add YAML for the other TML. ++ +[source,JSON] +---- +{ + "metadata_tmls": [ + "guid: a162289a-c1ab-427e-9985-8fb5f7c7e539\nliveboard:\n name: Liveboard 1\n" + ], + "import_policy": "PARTIAL", + "create_new": false, + "all_orgs_context": false +} +---- ++ +You may see double-escaped characters in JSON preview. For example, `\\n` instead `\n`. However, these will not be imported in the actual payload. +. To submit the request, click **Try it Out**. + ++ +In the following video, you can see that pasting YAML directly in the `metadata_tmls` form field results in an error due to additional quotation marks and improper formatting. Using the JSON editor, you can paste the YAML inside the array and import TML successfully. ++ + +[div videoContainer] +-- +video::./images/import-tml.mp4[width=100%,options="autoplay,loop"] +-- diff --git a/modules/ROOT/pages/tml.adoc b/modules/ROOT/pages/tml.adoc index 127583da2..c0451c9c9 100644 --- a/modules/ROOT/pages/tml.adoc +++ b/modules/ROOT/pages/tml.adoc @@ -40,494 +40,16 @@ Worksheets are deprecated in ThoughtSpot and replaced by Models from 10.12.0.cl The TML API endpoints allow you to programmatically export, validate, and import scriptable TML files. You can use these API endpoints to automate the change management and deployment processes between your development and production environments. With TML API, you can easily migrate your ThoughtSpot content from one environment to another by automating the entire change management process and thereby reducing the risk of human error. -[NOTE] -==== -If using older versions of TML files for Liveboards, ensure that your TML file has the object name as `liveboard`. Replace any `pinboard` occurrences with `liveboard` before import. -==== - -== Import TML -To import a modified TML object, your account must have the `DATAMANAGEMENT` (*Can manage data*) or `ADMINISTRATION` (*Can administer ThoughtSpot*) privilege. - -You can import single or multiple objects using the `tml/import` API. If you are importing TML files one at a time, include the `fqn` property to distinguish objects that have the same name. If you have multiple connections or tables with the same name and the Connection or Table you reference in your TML does not have a unique name, it can lead to invalid object references. Adding `fqn` helps ThoughtSpot differentiate a Table from another with the same name. - -By default, the `fqn` parameter is not present in the TML file. However, you can export TML with FQNs and use it during the import. - -You can also set the `skip_diff_check` to `true` to skip diff check before processing TMLs for imports. This attribute helps identify the objects that haven’t been changed since the last import or TML update, and eliminates importing redundant objects. - -To import TML representation of the metadata objects into ThoughtSpot, use one of the following API endpoints: - -* +++POST /api/rest/2.0/metadata/tml/import+++ (REST API v2) -* xref:tml-api.adoc#import[POST /tspublic/v1/metadata/tml/import] (REST API v1) - -//While the v1 API accepts a string containing a JSON array of TML objects to upload, in YAML or JSON format, the v2 accepts it only in the JSON format. - -There are multiple kinds of imports possible: - -* `PARTIAL` imports all objects that validate successfully, and ignores objects that do not validate successfully. -* `ALL_OR_NONE` imports the objects that validate successfully. -* `VALIDATE_ONLY` validates the objects but does not import them. -* `PARTIAL_OBJECT` (only applicable to REST API v2) -imports objects that validate successfully and skips the objects that do not validate successfully. If the import fails for a visualization object in a Liveboard TML, the Liveboard will be imported without that visualization object. Similarly, if importing a relationship in a logical table fails, the table TML will be imported with warnings in the API response. - -You can also specify additional parameters to set the Org context and skip CDW validation checks for Table TMLs. - -[NOTE] -==== -If you import only a Model object, it may take some time for the Model to become available in the ThoughtSpot system. You may need to wait for a few seconds to create answers and Liveboards. - -However, if you import a Model along with Liveboards, answers, and other dependent objects in a single API call, the imported objects will be immediately available for use. -==== - -[#personalized-views-portability] -=== Personalized Views portability [earlyAccess eaBackground]#Early Access# - -Personalized Views support improved portability across ThoughtSpot environments. When importing a Personalized View TML set the `enable_personalized_view_upsert` to `true` in the API request to `POST /api/rest/2.0/metadata/tml/import`. ThoughtSpot then checks the target environment for an existing Personalized View with a matching `obj_id`. If a match is found, the import updates the existing view rather than creating a duplicate. If no match is found, a new Personalized View is created. - -To enable this feature for your instance, contact your ThoughtSpot administrator. - -Two new fields are added to the TML, make it easier to migrate Personalized Views between environments without creating duplicates. - -`author`::: -A new `author` field is added to the Personalized View TML during export. This field is used to delegate ownership to another user during import. - -`obj_id`::: -A new `obj_id` field provides stable cross-environment object identity for inter-Org deployments. Use the same `obj_id` value across environments to ensure consistent identity during migrations. - - - -==== Example for a Personalized View TML with Object ID - -[source,yaml] ----- - views: - - view_guid: ff83055b-a867-43e7-978e-106e907e1912 - obj_id: California-LT-ff83855b - name: California - LT - view_filters: - - column: - - Retail Sales - Classic::Store State - oper: in - values: - - California - is_public: false - author: - username: user1 - user_email: user1@thoughtspot.com ----- - -==== Limitation without this feature enabled - -ThoughtSpot's link:https://docs.thoughtspot.com/cloud/latest/personalized-liveboard-views[personalized Liveboard views] let users apply filters and save configurations as named views on a Liveboard. -In multi-environment deployments (for example, a Dev instance and a Prod instance), these user-saved views can be lost when a Liveboard is updated and re-imported using the xref:tml.adoc[TML import API] or the UI *Import TML* option. -If the import is performed by an administrator account, all personalized views saved by end users are removed as part of this replacement. - -Why this happens?:: - -Personalized views are stored as user-owned objects linked to the Liveboard’s GUID. When an admin imports a Liveboard TML that matches an existing GUID, the import operation overwrites the Liveboard, and the associated user views are not carried forward. -+ -This happens because personalized views are created and usually owned by end users in a different environment (likely a Prod instance). They are not included in Liveboard TML files exported from a development or staging environment, so the import has no record of them. - -Workarounds:: -. Import as a non-admin user - -+ -The simplest workaround is to perform the final TML import in the production environment using a *non-admin user account* that has edit access to the Liveboard, rather than an admin account. -Because non-admin users do not have the authority to overwrite user-linked metadata during import, ThoughtSpot preserves the existing personalized views attached to the Liveboard. -. Embed existing saved views in the TML before import - -+ -You can export the current saved views from the production Liveboard, append them to the updated TML, and then import the combined TML. - -== Import TML objects asynchronously -The REST v1 and v2 `metadata/tml/import` APIs import TML objects synchronously. When you try to import large and complex metadata objects, the synchronous import operation takes more time to process data and sometimes can result in a timeout error. - -To allow mutually exclusive import tasks to run in parallel, process TML objects asynchronously, and check import task status, ThoughtSpot provides the following APIs: - -* +++POST /api/rest/2.0/metadata/tml/async/import+++ + -Creates an import TML tasks and processes TMLs asynchronously - -* +++POST /api/rest/2.0/metadata/tml/async/status+++ + -Fetches status of import tasks - -=== Schedule import tasks - -You can import TML objects asynchronously by scheduling TML import tasks via `POST` request to POST `/api/rest/2.0/metadata/tml/async/import` API endpoint. You can send the following parameters in the API request body: - -[width="100%" cols="2,4,1"] -[options='header'] -|==== -|Form parameter|Description| Default -|`metadata_tmls` |__Array of strings__. Array of the TML strings. |__None__ -|`create_new` + -__Optional__ |__Boolean__. To create TML objects with new GUIDs during import, specify `true`. By default, ThoughtSpot updates the existing objects that have the same GUID as the objects you are importing. | `false` -|`all_orgs_context` + -__Optional__ |__Boolean__. Specify if import operation must be run for all Orgs on your instance. - -__Requires Org administration privileges to access TML objects across all Orgs.__| `false` - -|`import_policy` a|__String__. Available from 10.5.0.cl. Policy to follow during import. The allowed values are: - -* `PARTIAL` + -Imports objects that validate successfully. Skips the objects that do not validate successfully and their dependent objects if any. -* `ALL_OR_NONE` + -Imports all objects that validate successfully. If the import fails for one object, no objects will be imported. -* `VALIDATE_ONLY` + -Validates the objects but does not import them. -* `PARTIAL_OBJECT` + -Imports objects that validate successfully and skips the objects that do not validate successfully. If the import fails for a visualization object in a Liveboard TML, the Liveboard will be imported without that visualization object. Similarly, if importing a relationship in a logical table fails, the table TML will be imported with warnings in the API response. -| `PARTIAL_OBJECT` - -|`skip_diff_check` + -__Optional__ -|__Boolean__. When set to `true`, skips the diff check before processing TML objects for import. By default, ThoughtSpot compares each TML object against its last imported version and skips objects that have not changed, which reduces unnecessary reimports. Set to `true` to bypass this check and reimport all objects regardless of whether they have changed. |`false` -|`enable_large_metadata_validation` + -__Optional__ - |__Boolean__. Available from 10.5.0.cl. Enables validation for large metadata objects. Set to `true` if the database contains multiple thousands of tables. When enabled, it allows for schema validation of one table at a time and helps circumvent the metadata fetching limitations of the Cloud Data Warehouse (CDW). -|`false` -|==== -//// - - -|`skip_cdw_validation_for_tables` + -__Optional__ |__Boolean__. Skips Cloud Data Warehouse validation for table TML imports. | `false` -//// -==== Example request - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-host}/api/rest/2.0/metadata/tml/async/import' \ - -H 'Accept: application/json' \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {AUTH_TOKEN}' \ - --data-raw '{ - "metadata_tmls": [ - "{\\\"guid\\\": \\\"2ed8192a-1e9d-47d1-810d-52b14cb0e9fe\\\",\\\"liveboard\\\": {\\\"name\\\": \\\"Total Sales\\\",\\\"visualizations\\\": [{\\\"id\\\": \\\"Viz_1\\\",\\\"answer\\\": {\\\"name\\\": \\\"Total quantity purchased, Total sales by region\\\",\\\"description\\\": \\\"test\\\",\\\"tables\\\": [{\\\"id\\\": \\\"(Sample) Retail - Apparel\\\",\\\"name\\\": \\\"(Sample) Retail - Apparel\\\"}],\\\"search_query\\\": \\\"[region] [quantity purchased] [sales]\\\",\\\"answer_columns\\\": [{\\\"name\\\": \\\"Total quantity purchased\\\"},{\\\"name\\\": \\\"Total sales\\\"},{\\\"name\\\": \\\"region\\\"}],\\\"table\\\": {\\\"table_columns\\\": [{\\\"column_id\\\": \\\"Total quantity purchased\\\",\\\"show_headline\\\": false},{\\\"column_id\\\": \\\"Total sales\\\",\\\"show_headline\\\": false},{\\\"column_id\\\": \\\"region\\\",\\\"show_headline\\\": false}],\\\"ordered_column_ids\\\": [\\\"region\\\",\\\"Total quantity purchased\\\",\\\"Total sales\\\"],\\\"client_state\\\": \\\"\\\",\\\"client_state_v2\\\": \\\"{\\\\\\\"tableVizPropVersion\\\\\\\": \\\\\\\"V1\\\\\\\"}\\\"},\\\"chart\\\": {\\\"type\\\": \\\"COLUMN\\\",\\\"chart_columns\\\": [{\\\"column_id\\\": \\\"Total quantity purchased\\\"},{\\\"column_id\\\": \\\"Total sales\\\"},{\\\"column_id\\\": \\\"region\\\"}],\\\"axis_configs\\\": [{\\\"x\\\": [\\\"region\\\"],\\\"y\\\": [\\\"Total quantity purchased\\\",\\\"Total sales\\\"]}],\\\"client_state\\\": \\\"\\\",\\\"client_state_v2\\\": \\\"{\\\\\\\"version\\\\\\\": \\\\\\\"V4DOT2\\\\\\\",\\\\\\\"chartProperties\\\\\\\": {\\\\\\\"responsiveLayoutPreference\\\\\\\": \\\\\\\"AUTO_ON\\\\\\\",\\\\\\\"chartSpecific\\\\\\\": {}},\\\\\\\"axisProperties\\\\\\\": [{\\\\\\\"id\\\\\\\": \\\\\\\"f6701821-5630-49cd-b26f-f98bebb4e98e\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"Y\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"Total quantity purchased\\\\\\\"],\\\\\\\"isOpposite\\\\\\\": false}},{\\\\\\\"id\\\\\\\": \\\\\\\"1e086aef-236d-4cf0-8909-9e04e04a1ac4\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"Y\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"Total sales\\\\\\\"],\\\\\\\"isOpposite\\\\\\\": true}},{\\\\\\\"id\\\\\\\": \\\\\\\"7be648d3-c791-43e4-bb13-63fea808f326\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"X\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"region\\\\\\\"]}}],\\\\\\\"systemSeriesColors\\\\\\\": [{\\\\\\\"serieName\\\\\\\": \\\\\\\"Total quantity purchased\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#48D1E0\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"Total sales\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#2E75F0\\\\\\\"}]}\\\"},\\\"display_mode\\\": \\\"CHART_MODE\\\"},\\\"viz_guid\\\": \\\"b8b38851-5980-40a1-bd88-608b7a9c6e86\\\"},{\\\"id\\\": \\\"Viz_2\\\",\\\"answer\\\": {\\\"name\\\": \\\"Total sales in a year\\\",\\\"tables\\\": [{\\\"id\\\": \\\"(Sample) Retail - Apparel\\\",\\\"name\\\": \\\"(Sample) Retail - Apparel\\\"}],\\\"search_query\\\": \\\"[sales] [store] [date].monthly [date].'\''this year'\''\\\",\\\"answer_columns\\\": [{\\\"name\\\": \\\"Month(date)\\\"},{\\\"name\\\": \\\"Total sales\\\"},{\\\"name\\\": \\\"store\\\"}],\\\"table\\\": {\\\"table_columns\\\": [{\\\"column_id\\\": \\\"Month(date)\\\",\\\"show_headline\\\": false},{\\\"column_id\\\": \\\"Total sales\\\",\\\"show_headline\\\": false},{\\\"column_id\\\": \\\"store\\\",\\\"show_headline\\\": false}],\\\"ordered_column_ids\\\": [\\\"store\\\",\\\"Month(date)\\\",\\\"Total sales\\\"],\\\"client_state\\\": \\\"\\\",\\\"client_state_v2\\\": \\\"{\\\\\\\"tableVizPropVersion\\\\\\\": \\\\\\\"V1\\\\\\\"}\\\"},\\\"chart\\\": {\\\"type\\\": \\\"LINE\\\",\\\"chart_columns\\\": [{\\\"column_id\\\": \\\"Month(date)\\\"},{\\\"column_id\\\": \\\"Total sales\\\"},{\\\"column_id\\\": \\\"store\\\"}],\\\"axis_configs\\\": [{\\\"x\\\": [\\\"Month(date)\\\"],\\\"y\\\": [\\\"Total sales\\\"],\\\"color\\\": [\\\"store\\\"]}],\\\"client_state\\\": \\\"\\\",\\\"client_state_v2\\\": \\\"{\\\\\\\"version\\\\\\\": \\\\\\\"V4DOT2\\\\\\\",\\\\\\\"chartProperties\\\\\\\": {\\\\\\\"responsiveLayoutPreference\\\\\\\": \\\\\\\"AUTO_ON\\\\\\\",\\\\\\\"chartSpecific\\\\\\\": {}},\\\\\\\"axisProperties\\\\\\\": [{\\\\\\\"id\\\\\\\": \\\\\\\"feb33c4a-614b-4623-9d12-1c4cf2250801\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"Y\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"Total sales\\\\\\\"],\\\\\\\"isOpposite\\\\\\\": false}},{\\\\\\\"id\\\\\\\": \\\\\\\"e89293cb-d10a-40d5-b787-81be33cc8b81\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"X\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"Month(date)\\\\\\\"]}}],\\\\\\\"systemSeriesColors\\\\\\\": [{\\\\\\\"serieName\\\\\\\": \\\\\\\"6a4acb32-9036-4d4c-a830-f2b06966a322\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#48D1E0\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"39e5242e-43d0-4ef7-8673-73b12433e0c5\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#2E75F0\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"arizona (85226)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#2E75F0\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"arizona (86001)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#48D1E0\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"california (91006)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#FCC838\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"california (94702)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#06BF7F\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"colorado (80301)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#8C62F5\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"colorado (80920)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#FF8142\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"connecticut (06110)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#ABC7F9\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"connecticut (06854)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#B5ECF2\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"delaware (19702)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#FDE9AF\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"georgia (30022)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#9BE5CB\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"georgia (30329)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#D1C0FB\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"idaho (83704)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#FFCCB3\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"illinois (60062)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#2359B6\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"illinois (60642)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#369FAA\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"indiana (46250)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#BF982A\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"iowa (50266)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#049160\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"maryland (21045)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#6A4ABA\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"massachusetts (01701)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#C26232\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"massachusetts (02215)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#71A1F4\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"michigan (48103)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#82DFE9\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"michigan (49512)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#FCD977\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"minnesota (55369)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#56D3A8\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"minnesota (55420)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#B094F8\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"missouri (63144)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#FFA97E\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"montana (59106)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#163772\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"montana (59718)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#22636B\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"nevada (89052)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#785F1A\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"nevada (89145)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#025B3C\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"new hampshire (03860)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#422E75\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"new jersey (07936)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#7A3D1F\\\\\\\"}]}\\\"},\\\"display_mode\\\": \\\"CHART_MODE\\\"},\\\"viz_guid\\\": \\\"7efc7b0e-e680-44a4-ba9c-3bd5d7272367\\\"},{\\\"id\\\": \\\"Viz_3\\\",\\\"answer\\\": {\\\"name\\\": \\\"Total sales by item type and region\\\",\\\"tables\\\": [{\\\"id\\\": \\\"(Sample) Retail - Apparel\\\",\\\"name\\\": \\\"(Sample) Retail - Apparel\\\"}],\\\"search_query\\\": \\\"[sales] [item type] [region]\\\",\\\"answer_columns\\\": [{\\\"name\\\": \\\"Total sales\\\"},{\\\"name\\\": \\\"item type\\\"},{\\\"name\\\": \\\"region\\\"}],\\\"table\\\": {\\\"table_columns\\\": [{\\\"column_id\\\": \\\"Total sales\\\",\\\"show_headline\\\": false},{\\\"column_id\\\": \\\"item type\\\",\\\"show_headline\\\": false},{\\\"column_id\\\": \\\"region\\\",\\\"show_headline\\\": false}],\\\"ordered_column_ids\\\": [\\\"item type\\\",\\\"region\\\",\\\"Total sales\\\"],\\\"client_state\\\": \\\"\\\",\\\"client_state_v2\\\": \\\"{\\\\\\\"tableVizPropVersion\\\\\\\": \\\\\\\"V1\\\\\\\"}\\\"},\\\"chart\\\": {\\\"type\\\": \\\"STACKED_COLUMN\\\",\\\"chart_columns\\\": [{\\\"column_id\\\": \\\"Total sales\\\"},{\\\"column_id\\\": \\\"item type\\\"},{\\\"column_id\\\": \\\"region\\\"}],\\\"axis_configs\\\": [{\\\"x\\\": [\\\"item type\\\"],\\\"y\\\": [\\\"Total sales\\\"],\\\"color\\\": [\\\"region\\\"]}],\\\"client_state\\\": \\\"\\\",\\\"client_state_v2\\\": \\\"{\\\\\\\"version\\\\\\\": \\\\\\\"V4DOT2\\\\\\\",\\\\\\\"chartProperties\\\\\\\": {\\\\\\\"responsiveLayoutPreference\\\\\\\": \\\\\\\"AUTO_ON\\\\\\\",\\\\\\\"chartSpecific\\\\\\\": {}},\\\\\\\"axisProperties\\\\\\\": [{\\\\\\\"id\\\\\\\": \\\\\\\"a330db6d-3714-4b5f-aed7-cca5ab679502\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"Y\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"Total sales\\\\\\\"],\\\\\\\"isOpposite\\\\\\\": false}},{\\\\\\\"id\\\\\\\": \\\\\\\"96ac1ce3-7efd-455e-a569-2cd0792b5f95\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"X\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"item type\\\\\\\"]}}],\\\\\\\"systemSeriesColors\\\\\\\": [{\\\\\\\"serieName\\\\\\\": \\\\\\\"Total sales\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#48D1E0\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"92153012-664c-458e-9a74-6138c5030838\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#2E75F0\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"east\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#06BF7F\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"midwest\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#FCC838\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"south\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#48D1E0\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"southwest\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#71A1F4\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"west\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#2E75F0\\\\\\\"}]}\\\"},\\\"display_mode\\\": \\\"CHART_MODE\\\"},\\\"viz_guid\\\": \\\"9de47a0e-6f20-40ba-9a52-3374ee530f09\\\"},{\\\"id\\\": \\\"Viz_4\\\",\\\"answer\\\": {\\\"name\\\": \\\"Total sales by state\\\",\\\"tables\\\": [{\\\"id\\\": \\\"(Sample) Retail - Apparel\\\",\\\"name\\\": \\\"(Sample) Retail - Apparel\\\"}],\\\"search_query\\\": \\\"[state] [store] [sales]\\\",\\\"answer_columns\\\": [{\\\"name\\\": \\\"Total sales\\\"},{\\\"name\\\": \\\"state\\\"},{\\\"name\\\": \\\"store\\\"}],\\\"table\\\": {\\\"table_columns\\\": [{\\\"column_id\\\": \\\"Total sales\\\",\\\"show_headline\\\": false},{\\\"column_id\\\": \\\"state\\\",\\\"show_headline\\\": false},{\\\"column_id\\\": \\\"store\\\",\\\"show_headline\\\": false}],\\\"ordered_column_ids\\\": [\\\"state\\\",\\\"store\\\",\\\"Total sales\\\"],\\\"client_state\\\": \\\"\\\",\\\"client_state_v2\\\": \\\"{\\\\\\\"tableVizPropVersion\\\\\\\": \\\\\\\"V1\\\\\\\"}\\\"},\\\"chart\\\": {\\\"type\\\": \\\"GEO_AREA\\\",\\\"chart_columns\\\": [{\\\"column_id\\\": \\\"Total sales\\\"},{\\\"column_id\\\": \\\"state\\\"},{\\\"column_id\\\": \\\"store\\\"}],\\\"axis_configs\\\": [{\\\"x\\\": [\\\"state\\\"],\\\"y\\\": [\\\"Total sales\\\"]}],\\\"client_state\\\": \\\"\\\",\\\"client_state_v2\\\": \\\"{\\\\\\\"version\\\\\\\": \\\\\\\"V4DOT2\\\\\\\",\\\\\\\"chartProperties\\\\\\\": {\\\\\\\"chartSpecific\\\\\\\": {}},\\\\\\\"axisProperties\\\\\\\": [{\\\\\\\"id\\\\\\\": \\\\\\\"e4943da4-f159-470c-836b-7c6c55d59c2f\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"Y\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"Total sales\\\\\\\"],\\\\\\\"isOpposite\\\\\\\": false}},{\\\\\\\"id\\\\\\\": \\\\\\\"b99d582a-b215-4381-89ad-280c451979e3\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"X\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"state\\\\\\\"]}}],\\\\\\\"systemMultiColorSeriesColors\\\\\\\": [{\\\\\\\"serieName\\\\\\\": \\\\\\\"Total sales\\\\\\\",\\\\\\\"colorMap\\\\\\\": [{\\\\\\\"serieName\\\\\\\": \\\\\\\"state\\\\\\\",\\\\\\\"color\\\\\\\": [\\\\\\\"#ffffb2\\\\\\\",\\\\\\\"#fddd87\\\\\\\",\\\\\\\"#fba35d\\\\\\\",\\\\\\\"#f75534\\\\\\\",\\\\\\\"#f9140a\\\\\\\",\\\\\\\"#d70315\\\\\\\",\\\\\\\"#b10026\\\\\\\"]}]}]}\\\"},\\\"display_mode\\\": \\\"CHART_MODE\\\"},\\\"viz_guid\\\": \\\"4ab1ed61-2930-46d4-af6f-778279d7414a\\\"}],\\\"filters\\\": [{\\\"column\\\": [\\\"region\\\"],\\\"oper\\\": \\\"in\\\",\\\"values\\\": [\\\"Midwest\\\"],\\\"is_mandatory\\\": false,\\\"is_single_value\\\": false,\\\"display_name\\\": \\\"region\\\"}],\\\"layout\\\": {\\\"tabs\\\": [{\\\"name\\\": \\\"Tab 1\\\",\\\"description\\\": \\\"\\\",\\\"tiles\\\": [{\\\"visualization_id\\\": \\\"Viz_1\\\",\\\"x\\\": 0,\\\"y\\\": 0,\\\"height\\\": 8,\\\"width\\\": 6},{\\\"visualization_id\\\": \\\"Viz_4\\\",\\\"x\\\": 6,\\\"y\\\": 0,\\\"height\\\": 8,\\\"width\\\": 6}],\\\"id\\\": \\\"2c4014b5-a606-4639-8ad0-01032ff3fc13\\\"},{\\\"name\\\": \\\"Tab 2\\\",\\\"description\\\": \\\"\\\",\\\"tiles\\\": [{\\\"visualization_id\\\": \\\"Viz_2\\\",\\\"x\\\": 0,\\\"y\\\": 0,\\\"height\\\": 8,\\\"width\\\": 6},{\\\"visualization_id\\\": \\\"Viz_3\\\",\\\"x\\\": 6,\\\"y\\\": 0,\\\"height\\\": 8,\\\"width\\\": 6}],\\\"id\\\": \\\"185b4875-e7c5-43d2-a9bc-0a404107a3ec\\\"}]}}}\", \"info\": { \"filename\": \"Copy of Total Sales.liveboard.tml\", \"name\": \"Copy of Total Sales\", \"id\": \"2ed8192a-1e9d-47d1-810d-52b14cb0e9fe\", \"type\": \"liveboard\", \"status\": { \"status_code\": \"OK\" } }" - ], - "create_new": true, - "all_orgs_context": false, -}' ----- - -==== Example response - -If the API request is successful, ThoughtSpot schedules an import task, and returns the task name and ID in the API response: - -[source,JSON] ----- -{ - "tenant_id": "default-tenant-id", - "org_id": 0, - "task_id": "075c322f-b000-4776-9c44-89e13420980c", - "task_name": "ASYNC_TML_26:Nov:2024-06:06:24", - "import_response": null, - "task_status": "IN_QUEUE", - "author_id": "08c6b203-ff6e-4ed8-b923-35ebbbfef27b", - "import_policy": "PARTIAL_OBJECT", - "created_at": null, - "in_progress_at": null, - "completed_at": null, - "total_object_count": 2, - "object_processed_count": null, - "modified_at": null, - "author_display_name": "UserA" -} ----- - -===== Response codes - -[options="header", cols="1,4"] -|==== -|HTTP status code|Description -|**200**|Async TML Import Task submitted successfully -|**400**|Invalid request -|**401**|Unauthorized access -|**403**|Forbidden access -|**500**|Unexpected Error -|==== - -=== Fetch status of the TML import task - -To fetch the status of a scheduled import task, send a `POST` request to the `POST /api/rest/2.0/metadata/tml/async/status` API endpoint. - -In the request body, include the following attributes: - -[width="100%" cols="2,4,1"] -[options='header'] -|==== -|Form parameter|Description| Default -|`task_ids` |__Array of strings__. Task IDs assigned to the scheduled TML async import operations. | __None__ -| `task_status` | __Array of strings__. Status of the scheduled import tasks to filter on. The following options are available: + - -* `COMPLETED` + -* `IN_QUEUE` + -* `IN_PROGRESS` + -* `FAILED` -| __None__ -|`author_identifier` + -__Optional__ |__String__. GUID of the author who initiated the import request. | __None__ -|`include_import_response` + -__Optional__ |__Boolean__. Specify whether to include import response in the task status objects.| `false` -|`record_offset` + -__Optional__ |__Integer__. The offset point, starting from where the task status should -be included in the response. | `0` -|`record_size` + -__Optional__ a|__Integer__. The number of task statuses to include in the -response starting from offset position. - -[NOTE] -==== -The maximum limit for the `record_size` that user can pass in an API request is 50. If the `record_size` exceeds this threshold, the API returns a bad request error. To extend the `record_size` limit, contact ThoughtSpot Support. -==== -| `5` -|`include_import_response`|__Boolean__. Specify whether to include the import response when fetching status for the import task. - -|==== - -[IMPORTANT] -==== -You can poll up to 100 API requests per minute to get details of your TML import tasks. The API returns an error if you exceed this rate limit. -==== - -==== Example request - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-host}/api/rest/2.0/metadata/tml/async/status' \ - -H 'Accept: application/json' \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {AUTH_TOKEN}' \ - --data-raw '{ - "record_offset": 0, - "record_size": 5, - "include_import_response": true, - "task_ids": [ - "c8c8c4da-0bc8-4460-8039-cfa7fd598335" - ], - "task_status": [ - "COMPLETED" - ], - "author_identifier": "95ac814f-eb01-4625-93c7-c7624b29d226" -}' ----- - -==== Example response - -If the API request is successful, ThoughtSpot returns the status details of the TML async import tasks. -If Orgs are enabled on your instance, the API returns task status only for objects within the current Org context. - -[source,JSON] ----- -{ - "status_list": [ - { - "tenant_id": "default-tenant-id", - "org_id": 0, - "task_id": "c8c8c4da-0bc8-4460-8039-cfa7fd598335", - "task_name": "ASYNC_TML_26:Nov:2024-06:06:24", - "import_response": { - "object": [ - { - "filename": "tml_0", - "zip_filename": "zip_tml_0", - "response": { - "status": { - "status_code": "ERROR", - "error_message": "Invalid YAML/JSON syntax in file." - } - }, - "request_index": 0 - }, - { - "filename": "tml_1", - "zip_filename": "zip_tml_1", - "response": { - "status": { - "status_code": "ERROR", - "error_message": "Invalid YAML/JSON syntax in file." - } - }, - "request_index": 1 - } - ], - "status": { - "status_code": "OK", - "error_code": 0, - "error_message": "" - } - }, - "task_status": "COMPLETED", - "author_id": "08c6b203-ff6e-4ed8-b923-35ebbbfef27b", - "import_policy": "PARTIAL_OBJECT", - "created_at": 1732601184212, - "in_progress_at": 1732601184255, - "completed_at": 1732601184476, - "total_object_count": 2, - "object_processed_count": 2, - "modified_at": 1732601184476, - "author_display_name": "UserA" - } - ], - "last_batch": true -} ----- - -===== Response codes - -[options="header", cols="1,4"] -|==== -|HTTP status code|Description -|**200**|Async TML import task status fetched successfully -|**400**|Invalid request -|**401**|Unauthorized access -|**403**|Forbidden access -|**500**|Unexpected Error -|==== - - -== Export a TML -To export the TML data, your account must have the `DATAMANAGEMENT` (Can manage data) or `ADMINISTRATION` (Can administer ThoughtSpot) privilege. - -The default format to export the objects is YAML is v1, and JSON in v2 APIs. To export the TML representation of the metadata objects from ThoughtSpot in JSON or YAML format, use one of the following endpoints: - -* link:https://developers.thoughtspot.com/docs/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fmetadata%2Fexport-metadata-tml[**POST** /api/rest/2.0/metadata/tml/export] (REST API v2) -* xref:tml-api.adoc#export[**POST** /tspublic/v1/metadata/tml/export] (REST API v1) - -To export the TML representation of the metadata objects in a *batch*, use one of the following endpoints: - -* link:https://developers.thoughtspot.com/docs/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fmetadata%2Fexport-metadata-tml-batched[**POST** /api/rest/2.0/metadata/tml/export/batch] (REST API v2) -* xref:tml-api.adoc#BatchExport[**POST** /tspublic/v1/metadata/tml/export/batch] (REST API v1) - -There are several export options available with these APIs: - -=== Metadata specification for Answers -To export a specific metadata object, specify the name or ID of the object. - -For Answer objects, the `identifier` is optional, and you can define parameters such as `session_identifier` and `generation_number` instead. These attributes can be used to export unsaved Answers generated from Spotter queries or Answers that do not have the name and ID assigned. - -=== Export associated objects - -To export associated objects, set the following attributes: - -* `export_associated` + -When set to `true`, exports the associated objects for the `export_ids` specified in the API request. The API exports any underlying Models, tables, or views for a given object. By default, the API does not export these underlying objects. -* `export_dependent` + -Specifies if the Tables of the referenced Connection object must be included in the export. -* `export_connection_as_dependent` + -Specifies if a Connection object must be included as a dependent object when exporting a Table, Model, Answer, or Liveboard TML. - -=== Export FQNs - -When `export_fqn=true`, the API exports the FQNs of the referenced objects in the TML data. For example, if you are exporting a Liveboard and its associated objects, the API returns the Liveboard TML data with the FQNs of the referenced Model. -Note that the FQN of a referenced object is the same as the GUID of that object. - -ThoughtSpot recommends adding the fqn property before importing the TML objects into the system, because only the name of a referenced object is not sufficient to identify the referenced object during TML import. For example, if your ThoughtSpot instance has two Models with the same name, the TML import for a Liveboard that uses one of these Models would fail unless the Liveboard TML includes the FQN of the referenced object. -The `export_fqn` attribute is useful when ThoughtSpot has multiple objects with the same name and you want to eliminate ambiguity during TML import. The `export_fqn=true` property adds the FQNs of the referenced objects in the TML export API response and saves the manual effort of adding FQNs for TML import. - -=== Export schema - -Specifies the schema version to use during TML export. For link:https://docs.thoughtspot.com/cloud/latest/models[Models, window=_blank], set `export_schema_version` to v2. -The v1 schema is used for Worksheet objects (Deprecated). - -=== Additional export options for REST API v2 -Following are some additional attributes which can be set for exporting objects: - -* `include_obj_id_ref` + -When set to `true`, exports the object ID of the referenced object. This flag will work only when the object ID feature is enabled. Contact ThoughtSpot Support to enable the feature. - -* `include_guid` + -When set to `true`, exports the guid of the object. This flag will work only when the object ID feature is enabled. Contact ThoughtSpot Support to enable the feature. -* `include_obj_id` + -When set to `true`, exports the object ID of the object. This flag will work only when the object ID feature is enabled. Contact ThoughtSpot Support to enable the feature. -* `export_with_associated_feedbacks` + -When set to `true`, exports the TML of an object along with all feedback, such as Spotter or Sage feedback, associated with that object. No feedback file will be exported if there are no feedback entries associated with the object -* `export_column_security_rules` [beta betaBackground]^Beta^ + -When set to `true`, exports the column-level security rules defined on the object. Contact ThoughtSpot Support to enable the feature. -* `export_with_column_aliases` [beta betaBackground]^Beta^ + -When set to `true`, export column aliases of the Model if the data Model includes any link:https://docs.thoughtspot.com/cloud/latest/column-aliases[column aliases, window=_blank]. - -=== Export in a batch -This API operation supports exporting User, User Group, and Role objects only. -To export objects in a batch, set the following additional attributes: - -* `batch_size` + -Exports the specified number of objects in a single API request. A batch size of up to 200 objects is allowed for a single API operation. - -* `batch_offset` + -Offsets the API response by the specified number. Batch offset value defines the starting position of the records for the results returned by the API. - -For more information, see the API documentation in REST API v2 Playground and xref:tml-api.adoc[Export a TML object using REST API v1]. - +* xref:tml-import.adoc[Import TML] +* xref:tml-export.adoc[Export TML] == TML modification -ThoughtSpot offers a lot of flexibility within its set of xref:intro-thoughtspot-objects.adoc[data objects], and there is no particular hierarchy to TML files, but rather just some rules. Visit this page for detailed information on xref:modify-tml.adoc[TML modification]. +Visit this page for detailed information on xref:modify-tml.adoc[TML modification]. == Limitations of working with TML files There are certain limitations to the changes you can apply by editing a ThoughtSpot object through TML. Visit link:https://docs.thoughtspot.com/cloud/latest/tml#_limitations_of_working_with_tml_files[Limitations of working with TML files, window=_blank] for detailed information. -[#yamlReimport] -=== YAML reimport in REST API v2 Playground -If you are using the REST API Playground to import TML in YAML format, note that copying YAML content directly in the input field will likely result in the `Invalid YAML/JSON syntax in file` error. -When you copy the YAML output from the export TML API response in the Playground, the copied content is wrapped in quotation marks and include escaped newline characters (`\n`). When you paste this content directly in the `metadata_tml` input field, the API Playground double-escapes characters or removes necessary newline (`\n`) characters. Due to improper formatting, the YAML input becomes invalid for import, resulting in the `Invalid YAML/JSON syntax in file` error. - -To work around this issue, follow these steps: - -. After you +++export TML+++ in the Playground, use the `copy to clipboard` option to copy the YAML output from the API response as shown in this video. - -+ - -[div videoContainer] --- -video::./images/tml-export.mp4[width=100%,options="autoplay,loop"] --- -+ -The output copied from the API response is enclosed in quotation marks (`"`). -For example, `"guid: a162289a-c1ab-427e-9985-8fb5f7c7e539\nliveboard:\n name: Liveboard 1\n"`. -. Paste the YAML output copied from the export TML API response into a text editor. -. Remove the quotation marks, update the TML, and ensure that the YAML is properly formatted: + -`guid: a162289a-c1ab-427e-9985-8fb5f7c7e539\nliveboard:\n name: Liveboard 1\n` -. When +++importing TML in the Playground+++, do not paste the YAML directly into the `metadata_tmls` input field. Instead, use the JSON editor to add the YAML. -. To open the JSON editor, click *View JSON*. + -In the JSON preview, you'll see the following code: -+ -[source,JSON] ----- -{ - "metadata_tmls": [ - "metadata_tmls3", - "metadata_tmls5", - ], - "import_policy": "PARTIAL", - "create_new": false, - "all_orgs_context": false -} ----- -. Remove the text in the `metadata_tmls` array and paste your YAML content inside the array. If you are importing more than one TML, use a comma after pasting a TML YAML and then add YAML for the otehr TML. -+ -[source,JSON] ----- -{ - "metadata_tmls": [ - "guid: a162289a-c1ab-427e-9985-8fb5f7c7e539\nliveboard:\n name: Liveboard 1\n" - ], - "import_policy": "PARTIAL", - "create_new": false, - "all_orgs_context": false -} ----- -+ -You may see double-escaped characters in JSON preview. For example, `\\n` instead `\n`. However, these will not be imported in the actual payload. -. To submit the request, click **Try it Out**. - -+ -In the following video, you can see that pasting YAML directly in the `metadata_tmls` form field results in an error due to additional quotation marks and improper formatting. Using the JSON editor, you can paste the YAML inside the array and import TML successfully. -+ - -[div videoContainer] --- -video::./images/import-tml.mp4[width=100%,options="autoplay,loop"] --- - == Deployment and version control of TML objects For information about version control and TML deployment, see the following pages: @@ -545,5 +67,4 @@ ThoughtSpot instances act as a constantly running service, so deployment only in But this changed with the link:https://developers.thoughtspot.com/docs/git-integration[Git integration] feature. ThoughtSpot now allows you to connect your deployment instance to a Git repository, push TML files to CI/CD pipelines, and deploy commits from your Git repository to your production environment. However, ThoughtSpot’s Git integration does not support moving objects within the same Org or application instance. For example, it does not support moving objects in an environment where xref:multitenancy-without-orgs[multi-tenancy is implemented using groups]. -/// - +//// diff --git a/modules/ROOT/pages/whats-new.adoc b/modules/ROOT/pages/whats-new.adoc index c0cec74b8..157dc8543 100644 --- a/modules/ROOT/pages/whats-new.adoc +++ b/modules/ROOT/pages/whats-new.adoc @@ -97,7 +97,7 @@ Two new fields have been added to the TML for Personalized Views: * A new `author` field is added to the Personalized View TML during export. This field is used to assign ownership during import. * Personalized Views now support `obj_id` for stable cross-environment object identity. -For more information, see xref:tml.adoc#personalized-views-portability[Personalized Views portability]. +For more information, see xref:tml-import.adoc#personalized-views-portability[Personalized Views portability]. --- diff --git a/src/components/SecondaryHeader/index.tsx b/src/components/SecondaryHeader/index.tsx index e472489b4..b645275a1 100644 --- a/src/components/SecondaryHeader/index.tsx +++ b/src/components/SecondaryHeader/index.tsx @@ -99,6 +99,7 @@ export const CATEGORY_PAGEIDS: Record = { ], 'rest-api': [ 'rest-apis', 'api-user-management', 'rbac', 'spotter-api', 'audit-logs', 'tml', + 'tml-import', 'tml-export', 'collections', 'connections', 'connection-config', 'rest-apiv2-getstarted', 'api-authv2', 'rest-apiv2-js', 'rest-apiv2-search', 'rest-apiv2-users-search', 'rest-apiv2-groups-search', 'rest-apiv2-metadata-search', diff --git a/src/configs/doc-configs.js b/src/configs/doc-configs.js index d5e37c73f..209ea45ef 100644 --- a/src/configs/doc-configs.js +++ b/src/configs/doc-configs.js @@ -125,7 +125,7 @@ module.exports = { 'session-api', 'user-api', 'group-api', 'role-api', 'security-api', 'admin-api', 'database-api', 'orgs-api', 'search-data-api', 'materialization-api', 'liveboard-data-api', 'liveboard-export-api', 'push-data', 'logs-api', - 'audit-logs', 'tml', 'collections', 'connections', + 'audit-logs', 'tml', 'tml-import', 'tml-export', 'collections', 'connections', 'connection-config', 'connections-api', 'api-user-management', 'rbac', 'webhooks-rest-api', 'rest-v2-changelog', 'rest-v1-changelog', ], From 28304b06919e98dc773e4e396f339f473efbd20f Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Wed, 19 Aug 2026 20:20:50 +0530 Subject: [PATCH 076/154] cleaned up for v1 apis --- modules/ROOT/pages/catalog-and-audit.adoc | 2 +- modules/ROOT/pages/deploy-with-tml-apis.adoc | 2 +- .../ROOT/pages/feature-matrix-license.adoc | 2 +- .../pages/multi-tenancy-best-practices.adoc | 2 +- modules/ROOT/pages/rest-apiv2-changelog.adoc | 2 +- modules/ROOT/pages/tml-export.adoc | 32 +++++++++++++++---- modules/ROOT/pages/tml-import.adoc | 27 +++++++++------- 7 files changed, 45 insertions(+), 24 deletions(-) diff --git a/modules/ROOT/pages/catalog-and-audit.adoc b/modules/ROOT/pages/catalog-and-audit.adoc index a945884b4..ebaab6156 100644 --- a/modules/ROOT/pages/catalog-and-audit.adoc +++ b/modules/ROOT/pages/catalog-and-audit.adoc @@ -24,7 +24,7 @@ The `/metadata/listobjectheaders` API is paginated by default. You can return th The REST API provides a xref:metadata-api.adoc#metadata-details[metadata/details] endpoint that returns very complex objects with all the metadata available. For purposes of cataloging, it may be easier to use a combination of the metadata list methods and the TML APIs to build a picture of what is available. -For example, to know the columns and data types of a table, you can get the table's GUID from the `metadata/listobjectheaders` endpoint, then request the TML for the table using the xref:tml-api.adoc[TML APIs]. If you need more complex data of how ThoughtSpot stores the columns internally, then use the `metadata/details` endpoint. +For example, to know the columns and data types of a table, you can get the table's GUID from the `metadata/listobjectheaders` endpoint, then request the TML for the table using the xref:tml-export.adoc[TML export API]. If you need more complex data of how ThoughtSpot stores the columns internally, then use the `metadata/details` endpoint. == Retrieve object access (sharing) diff --git a/modules/ROOT/pages/deploy-with-tml-apis.adoc b/modules/ROOT/pages/deploy-with-tml-apis.adoc index 2425adcf9..48ec1e6da 100644 --- a/modules/ROOT/pages/deploy-with-tml-apis.adoc +++ b/modules/ROOT/pages/deploy-with-tml-apis.adoc @@ -255,7 +255,7 @@ if 'edoc' in yaml_tml[0]: [#linkImportRelease] == TML Import with obj_id and variables -The xref:tml-api.adoc#import[/metadata/tml/import] REST API endpoint is used to upload any number of TML files at one time. +The xref:tml-import.adoc#import-tml[/metadata/tml/import] REST API endpoint is used to upload any number of TML files at one time. All details of the objects to be created or modified are specified *within the uploaded TML file*, matching first on `obj_id` and then on `guid` if `obj_id` is not present. diff --git a/modules/ROOT/pages/feature-matrix-license.adoc b/modules/ROOT/pages/feature-matrix-license.adoc index deac379e5..ca190f7bc 100644 --- a/modules/ROOT/pages/feature-matrix-license.adoc +++ b/modules/ROOT/pages/feature-matrix-license.adoc @@ -217,7 +217,7 @@ a|xref:metadata-api.adoc[Metadata] + __Query APIs only__ -a|xref:tml-api.adoc[TML] + +a|xref:tml.adoc[TML] + //// __Require `DATAMANAGEMENT` privilege__ diff --git a/modules/ROOT/pages/multi-tenancy-best-practices.adoc b/modules/ROOT/pages/multi-tenancy-best-practices.adoc index 5e3401841..43233dfcd 100644 --- a/modules/ROOT/pages/multi-tenancy-best-practices.adoc +++ b/modules/ROOT/pages/multi-tenancy-best-practices.adoc @@ -77,7 +77,7 @@ Remember to share the Model as *READ_ONLY* along with the Liveboards and answers link:https://docs.thoughtspot.com/cloud/latest/security-data-object#cls[Column level security, window=_blank] (CLS) can be configured at the individual table level through sharing. As with row-level security (RLS) groups, the best practice is to create separate groups specifically for the CLS groups. == Best practices for multi-tenant database and single-tenant database models -There are two basic architectures for storing different tenants' data within cloud data warehouses. The following sections describe a best practice starting point for deploying in ThoughtSpot depending on which of the architectures you have chosen for your CDW. REST APIs are available to deploy these patterns at scale. You can xref:group-api.adoc#create-group[create groups], xref:user-api.adoc#create-user[create users], xref:group-api.adoc#add-user-to-group[add users to groups], xref:tml-api.adoc[publish content from TML objects], and xref:security-api.adoc#share-object[share that content with the appropriate groups]. +There are two basic architectures for storing different tenants' data within cloud data warehouses. The following sections describe a best practice starting point for deploying in ThoughtSpot depending on which of the architectures you have chosen for your CDW. REST APIs are available to deploy these patterns at scale. You can xref:group-api.adoc#create-group[create groups], xref:user-api.adoc#create-user[create users], xref:group-api.adoc#add-user-to-group[add users to groups], xref:tml-import.adoc[publish content from TML objects], and xref:security-api.adoc#share-object[share that content with the appropriate groups]. === Multi-tenant database model The "multi-tenant database model" is designed on the following principles: diff --git a/modules/ROOT/pages/rest-apiv2-changelog.adoc b/modules/ROOT/pages/rest-apiv2-changelog.adoc index f21342428..405cabf21 100644 --- a/modules/ROOT/pages/rest-apiv2-changelog.adoc +++ b/modules/ROOT/pages/rest-apiv2-changelog.adoc @@ -302,7 +302,7 @@ This allows you to retrieve the full list of Personalized Views associated with For more information, see xref:rest-api-v2-metadata-search.adoc#_include_personalised_views[Search metadata API]. === TML API enhancements -The previous limit of 100 Personalized Views per Liveboard on TML import has been removed. You can now import all associated Personalized Views of a Liveboard without any views being dropped. For more information, see the xref:tml-api.adoc[TML API documentation]. +The previous limit of 100 Personalized Views per Liveboard on TML import has been removed. You can now import all associated Personalized Views of a Liveboard without any views being dropped. For more information, see the xref:tml-import.adoc[TML import documentation]. == Version 26.4.0.cl, April 2026 diff --git a/modules/ROOT/pages/tml-export.adoc b/modules/ROOT/pages/tml-export.adoc index bdaf32488..7bfd58583 100644 --- a/modules/ROOT/pages/tml-export.adoc +++ b/modules/ROOT/pages/tml-export.adoc @@ -10,15 +10,13 @@ [#export-tml] To export the TML data, your account must have the `DATAMANAGEMENT` (Can manage data) or `ADMINISTRATION` (Can administer ThoughtSpot) privilege. -The default format to export the objects is YAML in v1, and JSON in v2 APIs. To export the TML representation of the metadata objects from ThoughtSpot in JSON or YAML format, use one of the following endpoints: +The default format to export the objects is JSON. To export the TML representation of the metadata objects from ThoughtSpot in JSON or YAML format, use the following endpoint: -* link:https://developers.thoughtspot.com/docs/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fmetadata%2Fexport-metadata-tml[**POST** /api/rest/2.0/metadata/tml/export] (REST API v2) -* xref:tml-api.adoc#export[**POST** /tspublic/v1/metadata/tml/export] (REST API v1) +* link:https://developers.thoughtspot.com/docs/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fmetadata%2Fexport-metadata-tml[**POST** /api/rest/2.0/metadata/tml/export] -To export the TML representation of the metadata objects in a *batch*, use one of the following endpoints: +To export the TML representation of the metadata objects in a *batch*, use the following endpoint: -* link:https://developers.thoughtspot.com/docs/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fmetadata%2Fexport-metadata-tml-batched[**POST** /api/rest/2.0/metadata/tml/export/batch] (REST API v2) -* xref:tml-api.adoc#BatchExport[**POST** /tspublic/v1/metadata/tml/export/batch] (REST API v1) +* link:https://developers.thoughtspot.com/docs/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fmetadata%2Fexport-metadata-tml-batched[**POST** /api/rest/2.0/metadata/tml/export/batch] There are several export options available with these APIs: @@ -46,6 +44,14 @@ Note that the FQN of a referenced object is the same as the GUID of that object. ThoughtSpot recommends adding the fqn property before importing the TML objects into the system, because only the name of a referenced object is not sufficient to identify the referenced object during TML import. For example, if your ThoughtSpot instance has two Models with the same name, the TML import for a Liveboard that uses one of these Models would fail unless the Liveboard TML includes the FQN of the referenced object. The `export_fqn` attribute is useful when ThoughtSpot has multiple objects with the same name and you want to eliminate ambiguity during TML import. The `export_fqn=true` property adds the FQNs of the referenced objects in the TML export API response and saves the manual effort of adding FQNs for TML import. +// PORTED from tml-api.adoc (v1) lines 235-239 — was commented out on the v1 page; confirm why before publishing. +// RENAMED for v2: `force_create` -> `create_new`. Worksheet -> Model. +[NOTE] +==== +When you import multiple objects in bulk and create objects using the `create_new` attribute, the new object may refer to an existing object with the same FQN in the ThoughtSpot system instead of the other objects provided in the TML import request. For example, when you upload a TML representation of a Liveboard and the associated Model with the FQNs obtained from the TML export API, the imported Liveboard may refer to an existing Model with the same FQN in the ThoughtSpot system instead of the new Model created during the TML import. + +If you want the new objects created during the TML import to refer to the other associated objects created during the same import operation, set the `export_fqn` attribute to `false` during TML export or remove the FQNs manually before the TML import. +==== + For more information about using FQNs during import, see xref:tml-import.adoc#import-tml[Import TML]. == Export schema @@ -74,10 +80,22 @@ When set to `true`, export column aliases of the Model if the data Model include This API operation supports exporting User, User Group, and Role objects only. To export objects in a batch, set the following additional attributes: +// PORTED from tml-api.adoc (v1) line 342-347 — parameter name and allowed values were undocumented here. +* `metadata_type` + +Type of the metadata object to export. Use one of the following values: `USER`, `USER_GROUP`, or `ROLE`. The `ROLE` value applies only to instances on which xref:roles.adoc[Role-based access control] is enabled. + * `batch_size` + Exports the specified number of objects in a single API request. A batch size of up to 200 objects is allowed for a single API operation. +// PORTED from tml-api.adoc (v1) line 340 — VERIFY FOR v2: v1 default was `20`. +The default batch size is 20. * `batch_offset` + Offsets the API response by the specified number. Batch offset value defines the starting position of the records for the results returned by the API. +// PORTED from tml-api.adoc (v1) line 341 — VERIFY FOR v2: v1 default was `0`. +The default batch offset is 0. + +// PORTED from tml-api.adoc (v1) line 348 — batch-export semantics differ from the `export_dependent` documented under "Export associated objects" above. +* `export_dependent` + +Specifies if the dependent objects must be exported. For example, the user groups to which user objects are assigned, or the sub-groups of a user group. To get full details of the dependent objects, the API call initiator must have view or edit access to the dependent object. -For more information, see the API documentation in REST API v2 Playground and xref:tml-api.adoc[Export a TML object using REST API v1]. +For more information, see the API documentation in REST API v2 Playground. diff --git a/modules/ROOT/pages/tml-import.adoc b/modules/ROOT/pages/tml-import.adoc index 562ae15f7..f0640b695 100644 --- a/modules/ROOT/pages/tml-import.adoc +++ b/modules/ROOT/pages/tml-import.adoc @@ -21,19 +21,16 @@ By default, the `fqn` parameter is not present in the TML file. However, you can You can also set the `skip_diff_check` to `true` to skip diff check before processing TMLs for imports. This attribute helps identify the objects that haven’t been changed since the last import or TML update, and eliminates importing redundant objects. -To import TML representation of the metadata objects into ThoughtSpot, use one of the following API endpoints: +To import TML representation of the metadata objects into ThoughtSpot, use the following API endpoint: -* +++POST /api/rest/2.0/metadata/tml/import+++ (REST API v2) -* xref:tml-api.adoc#import[POST /tspublic/v1/metadata/tml/import] (REST API v1) - -//While the v1 API accepts a string containing a JSON array of TML objects to upload, in YAML or JSON format, the v2 accepts it only in the JSON format. +* +++POST /api/rest/2.0/metadata/tml/import+++ There are multiple kinds of imports possible: * `PARTIAL` imports all objects that validate successfully, and ignores objects that do not validate successfully. * `ALL_OR_NONE` imports the objects that validate successfully. * `VALIDATE_ONLY` validates the objects but does not import them. -* `PARTIAL_OBJECT` (only applicable to REST API v2) +* `PARTIAL_OBJECT` imports objects that validate successfully and skips the objects that do not validate successfully. If the import fails for a visualization object in a Liveboard TML, the Liveboard will be imported without that visualization object. Similarly, if importing a relationship in a logical table fails, the table TML will be imported with warnings in the API response. You can also specify additional parameters to set the Org context and skip CDW validation checks for Table TMLs. @@ -45,6 +42,15 @@ If you import only a Model object, it may take some time for the Model to become However, if you import a Model along with Liveboards, answers, and other dependent objects in a single API call, the imported objects will be immediately available for use. ==== +// PORTED from tml-api.adoc (v1) line 68 — was attached to the v1 `force_create` parameter. +// VERIFY FOR v2: v1 returned `id_guid` in the RESPONSE HEADERS. The v2 endpoint most likely +// returns the new GUID in the response body instead — confirm the property and location +// before publishing, or drop this note. +[NOTE] +==== +To know the GUID assigned to a new object created from the TML import, check the `id_guid` property in the response headers. +==== + [#personalized-views-portability] == Personalized Views portability [earlyAccess eaBackground]#Early Access# @@ -104,7 +110,7 @@ Because non-admin users do not have the authority to overwrite user-linked metad You can export the current saved views from the production Liveboard, append them to the updated TML, and then import the combined TML. == Import TML objects asynchronously -The REST v1 and v2 `metadata/tml/import` APIs import TML objects synchronously. When you try to import large and complex metadata objects, the synchronous import operation takes more time to process data and sometimes can result in a timeout error. +The `metadata/tml/import` API imports TML objects synchronously. When you try to import large and complex metadata objects, the synchronous import operation takes more time to process data and sometimes can result in a timeout error. To allow mutually exclusive import tasks to run in parallel, process TML objects asynchronously, and check import task status, ThoughtSpot provides the following APIs: @@ -149,13 +155,10 @@ __Optional__ __Optional__ |__Boolean__. Available from 10.5.0.cl. Enables validation for large metadata objects. Set to `true` if the database contains multiple thousands of tables. When enabled, it allows for schema validation of one table at a time and helps circumvent the metadata fetching limitations of the Cloud Data Warehouse (CDW). |`false` -|==== -//// - - |`skip_cdw_validation_for_tables` + __Optional__ |__Boolean__. Skips Cloud Data Warehouse validation for table TML imports. | `false` -//// +|==== + ==== Example request [source,cURL] From 1091302cb59222bee62f76adc973cb22b4c260b3 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Thu, 20 Aug 2026 07:43:31 +0530 Subject: [PATCH 077/154] API updates --- modules/ROOT/pages/api-changelog.adoc | 41 +---------------- .../ROOT/pages/semantic-integrations-api.adoc | 45 +++---------------- modules/ROOT/pages/whats-new.adoc | 5 +-- 3 files changed, 9 insertions(+), 82 deletions(-) diff --git a/modules/ROOT/pages/api-changelog.adoc b/modules/ROOT/pages/api-changelog.adoc index 110feaf28..7b61550e8 100644 --- a/modules/ROOT/pages/api-changelog.adoc +++ b/modules/ROOT/pages/api-changelog.adoc @@ -16,13 +16,8 @@ This page documents the changes introduced in each release of the Visual Embed S [discrete] ===== Browser history management in full application embedding +To override the browser history behavior for embedding application users and prevent users from getting trapped in back-button loops inside the embedded iframe environment, you can now set `overrideHistoryState` in the Visual Embed SDK. -// SOURCE: SCAL-317516 -// SOURCE: thoughtspot/visual-embed-sdk/src/types.ts (master) - -ThoughtSpot 26.9.0.cl introduces the `overrideHistoryState` configuration parameter for `AppEmbed`. When embedding ThoughtSpot in a host application, every internal ThoughtSpot navigation event (for example, switching between Liveboards or Answers) pushes a new entry onto the browser's history stack. This causes the browser *Back* button to step through ThoughtSpot's internal navigation before returning to the host application's prior page. - -Setting `overrideHistoryState: true` converts all ThoughtSpot internal `pushState` calls to `replaceState`, preventing ThoughtSpot navigation from polluting the host application's browser history stack. //// [source,JavaScript] @@ -45,46 +40,12 @@ embed.render(); <1> When set to `true`, ThoughtSpot replaces rather than pushes browser history entries during internal navigation. //// -[NOTE] -==== -`overrideHistoryState` is available on `AppEmbed` only. It is not supported on `LiveboardEmbed`, `SearchEmbed`, or `SpotterEmbed`. Validate behavior across Chrome, Firefox, and Safari before enabling in production. -==== - -For more information, see xref:full-app-embed.adoc[Full application embedding]. - |[tag greenBackground]#NEW FEATURE# a| [discrete] ===== Collections in left navigation panel - -// SOURCE: SCAL-314461 - The `HomeLeftNavItem.Collections` enum value is now available in the Visual Embed SDK. Embed developers can include *Collections* as a selectable navigation option in the embedded left navigation panel for full application embeds. When enabled, end users of the embedded application can navigate to *Collections* from the left navigation panel. -//// -[source,JavaScript] ----- -import { AppEmbed, HomeLeftNavItem, init, AuthType } from '@thoughtspot/visual-embed-sdk'; -init({ - thoughtSpotHost: 'https://.thoughtspot.cloud', - authType: AuthType.TrustedAuthToken, - getAuthToken: () => fetch('/ts-token').then(r => r.json()).then(d => d.token), -}); - -const embed = new AppEmbed('#embed-container', { - frameParams: { width: '100%', height: '100%' }, - leftNavOrder: [ - HomeLeftNavItem.Home, - HomeLeftNavItem.Liveboards, - HomeLeftNavItem.Answers, - HomeLeftNavItem.Collections, // <1> - ], -}); - -embed.render(); ----- -<1> Include `HomeLeftNavItem.Collections` in the `leftNavOrder` array to show Collections in the embedded left navigation panel. -//// For more information, see xref:full-app-customize.adoc[Customize full application embedding]. |==== diff --git a/modules/ROOT/pages/semantic-integrations-api.adoc b/modules/ROOT/pages/semantic-integrations-api.adoc index 4fc5ead75..0a9f80a9e 100644 --- a/modules/ROOT/pages/semantic-integrations-api.adoc +++ b/modules/ROOT/pages/semantic-integrations-api.adoc @@ -6,14 +6,9 @@ :page-pageid: semantic-integrations-api :page-description: Use the ThoughtSpot REST API v2.0 endpoints to create, search, import, and delete Snowflake Semantic View integration configurations programmatically. -// SOURCE: SCAL-309867 -// SOURCE: scaligent/prism/src/public-apis/semantic-integrations.graphql (master) -// SOURCE: scaligent/prism/src/public-apis/docs/descriptions/semantic-integrations/ (master) - -ThoughtSpot 26.9.0.cl introduces REST API v2.0 endpoints for managing Snowflake Semantic View integrations. These APIs allow administrators and data managers to create, search, import, and delete semantic integration configurations programmatically, without using the ThoughtSpot UI. +ThoughtSpot provides the Semantic View integrations REST API v2.0 endpoints to create, search, import, and delete semantic integration configurations programmatically. == Overview - Snowflake Semantic Views provide a governed semantic layer for data in Snowflake, including named measures, dimensions, and business-logic formulas. When you create a semantic integration in ThoughtSpot, the platform reads the semantic view definition from Snowflake and generates a corresponding ThoughtSpot data model (Worksheet). The model inherits the column names, descriptions, and formula definitions from the Snowflake Semantic View. You can use the semantic integration APIs to automate the following tasks: @@ -36,10 +31,7 @@ To use these APIs, the authenticated user must have one of the following privile * `ADMINISTRATION` (*Can administer ThoughtSpot*) * `DATAMANAGEMENT` (*Can manage data*) -If Role-Based Access Control (RBAC) is enabled on your instance, the user must also have: - -* `CAN_CREATE_OR_EDIT_CONNECTIONS` (*Can create/edit Connections*) -* *Can manage data models* +If Role-Based Access Control (RBAC) is enabled on your instance, the user requires `CAN_CREATE_OR_EDIT_CONNECTIONS` (*Can create/edit Connections*) privilege. == API endpoints @@ -55,14 +47,8 @@ If Role-Based Access Control (RBAC) is enabled on your instance, the user must a [#create-semantic-integration] == Create a semantic integration +To create a new semantic integration by reading the specified Snowflake Semantic View and generating a corresponding ThoughtSpot data model, use the `/api/rest/2.0/semantic-integrations/create` API endpoint. On success, the response includes the integration GUID, the generated model GUID, and a per-formula import report. -`POST /api/rest/2.0/semantic-integrations/create` - -Creates a new semantic integration by reading the specified Snowflake Semantic View and generating a corresponding ThoughtSpot data model. On success, the response includes the integration GUID, the generated model GUID, and a per-formula import report. - -=== Required privileges - -`ADMINISTRATION` or `DATAMANAGEMENT`. If RBAC is enabled: `CAN_CREATE_OR_EDIT_CONNECTIONS` and *Can manage data models*. === Request parameters @@ -179,13 +165,7 @@ curl -X POST \ [#search-semantic-integrations] == Search semantic integrations -`POST /api/rest/2.0/semantic-integrations/search` - -Returns a paginated list of semantic integrations matching the specified criteria. Returns all integrations if no filters are specified. - -=== Required privileges - -`ADMINISTRATION` or `DATAMANAGEMENT`. If RBAC is enabled: `CAN_CREATE_OR_EDIT_CONNECTIONS` and *Can manage data models*. +To fetch a paginated list of semantic integrations matching the specified criteria, use the `/api/rest/2.0/semantic-integrations/search` API endpoint. Returns all integrations if no filters are specified. === Request parameters @@ -258,10 +238,7 @@ curl -X POST \ [#import-semantic-integration] == Import a semantic integration - -`POST /api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/import` - -Re-imports semantic updates from the Snowflake CDW source for an existing integration, and rebuilds the corresponding ThoughtSpot data model. Use this endpoint after the source Snowflake Semantic View has been updated (formulas added, removed, or modified) to bring the ThoughtSpot model back in line with the CDW definition. +To re-import semantic updates from the Snowflake CDW source for an existing integration, and rebuild the corresponding ThoughtSpot data model, send a `POST` request to the `/api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/import` API endpoint. Send this API request, after the source Snowflake Semantic View has been updated (formulas added, removed, or modified) to bring the ThoughtSpot model back in line with the CDW definition. [NOTE] ==== @@ -273,9 +250,6 @@ The import operation: * Preserves the integration GUID, name, and `model_id`. Only the formula set is refreshed. * Returns the same `semantic_report` response as create, with an additional `change_status` per formula indicating whether each formula is `NEW`, `UPDATED`, or `UNCHANGED` since the previous import. -=== Required privileges - -`ADMINISTRATION` or `DATAMANAGEMENT`. If RBAC is enabled: `CAN_CREATE_OR_EDIT_CONNECTIONS` and *Can manage data models*. === Path parameters @@ -353,20 +327,13 @@ curl -X POST \ [#delete-semantic-integration] == Delete a semantic integration - -`POST /api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/delete` - -Permanently deletes the specified semantic integration and its generated ThoughtSpot data model from the system. +To permanently delete the specified semantic integration and its generated ThoughtSpot data model from the system, use the `/api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/delete` API endpoint. [WARNING] ==== Deletion is permanent and cannot be undone. If you need to restore the integration, use the `create` endpoint to re-import the Snowflake Semantic View. ==== -=== Required privileges - -`ADMINISTRATION` or `DATAMANAGEMENT`. If RBAC is enabled: `CAN_CREATE_OR_EDIT_CONNECTIONS` and *Can manage data models*. - === Path parameters [width="100%"] diff --git a/modules/ROOT/pages/whats-new.adoc b/modules/ROOT/pages/whats-new.adoc index 1688c82dc..255551f87 100644 --- a/modules/ROOT/pages/whats-new.adoc +++ b/modules/ROOT/pages/whats-new.adoc @@ -36,9 +36,8 @@ a| a| [discrete] -==== Browser history management in full application embedding [.version-badge.new]#New# - -The Visual Embed SDK 1.52.0 introduces the `overrideHistoryState` configuration parameter for `AppEmbed`. When ThoughtSpot is embedded in a host application, every internal navigation event pushes a new entry onto the browser history stack, causing the browser *Back* button to step through ThoughtSpot's internal pages before returning to the host application. Setting `overrideHistoryState: true` converts ThoughtSpot's internal `pushState` calls to `replaceState`, preventing internal navigation from polluting the host application's browser history stack. For more information, see xref:full-app-embed.adoc[Full application embedding]. +==== Browser history management in full application embedding +When ThoughtSpot is embedded in a host application, internal navigation pushes new entries onto the browser history stack, causing the browser *Back* button to step through ThoughtSpot's internal pages before returning to the host application. To override the browser history behavior for embedding application users and prevent users from getting trapped in back-button loops inside the embedded iframe environment, set `overrideHistoryState` in the Visual Embed SDK. --- From 773dbd06328459f588d08057a4ac058f785685fe Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Fri, 21 Aug 2026 11:19:01 +0530 Subject: [PATCH 078/154] SCAL-333914 --- modules/ROOT/pages/rest-api-csharp-sdk.adoc | 2 +- modules/ROOT/pages/rest-api-java-sdk.adoc | 32 +++++---- modules/ROOT/pages/rest-api-python-sdk.adoc | 2 +- .../ROOT/pages/rest-api-sdk-typescript.adoc | 70 +++++++++---------- 4 files changed, 52 insertions(+), 54 deletions(-) diff --git a/modules/ROOT/pages/rest-api-csharp-sdk.adoc b/modules/ROOT/pages/rest-api-csharp-sdk.adoc index 52269c2ea..28200e803 100644 --- a/modules/ROOT/pages/rest-api-csharp-sdk.adoc +++ b/modules/ROOT/pages/rest-api-csharp-sdk.adoc @@ -323,7 +323,7 @@ await api.ApplyConfigurationAsync(newConfig); [options="header"] |==== |ThoughtSpot release|Recommended SDK version -|ThoughtSpot Cloud 26.8.0.cl|v2.27.0 or later +|ThoughtSpot Cloud 26.8.0.cl|v2.27.1 or later |==== diff --git a/modules/ROOT/pages/rest-api-java-sdk.adoc b/modules/ROOT/pages/rest-api-java-sdk.adoc index e4285cb47..2ce0cee7e 100644 --- a/modules/ROOT/pages/rest-api-java-sdk.adoc +++ b/modules/ROOT/pages/rest-api-java-sdk.adoc @@ -277,24 +277,26 @@ The SDK raises an exception when an API request fails. Inspect the HTTP status c Note the recommendation of Java SDK: -[width="100%" cols="2,4"] +[width="100%" cols="2,2"] [options='header'] |==== |ThoughtSpot release version|Supported SDK version -a|ThoughtSpot Cloud: 26.8.0.cl | v2.27.0 or later -a|ThoughtSpot Cloud: 26.7.0.cl | v2.26.0 or later -a|ThoughtSpot Cloud: 26.6.0.cl | v2.25.0 or later -a|ThoughtSpot Cloud: 26.5.0.cl | v2.24.0 or later -a|ThoughtSpot Cloud: 26.4.0.cl | v2.23.0 or later -a|ThoughtSpot Cloud: 26.3.0.cl | v2.22.0 or later -a|ThoughtSpot Cloud: 26.2.0.cl | v2.21.0 or later -a|ThoughtSpot Cloud: 10.15.0.cl | v2.20.0 or later -a|ThoughtSpot Cloud: 10.14.0.cl | v2.19.0 or later -a|ThoughtSpot Cloud: 10.13.0.cl | v2.18.0 or later -a|ThoughtSpot Cloud: 10.12.0.cl | v2.17.0 or later -a|ThoughtSpot Cloud: 10.11.0.cl | v2.16.0 or later -a|ThoughtSpot Cloud: 10.10.0.cl | v2.15.1 or later -a|ThoughtSpot Cloud: 10.9.0.cl | v2.14.0 or later +|ThoughtSpot Cloud: 26.8.0.cl|v2.27.1 or later +|ThoughtSpot Cloud: 26.7.0.cl|v2.26.0 or later +|ThoughtSpot Cloud: 26.6.0.cl|v2.25.0 or later +|ThoughtSpot Cloud: 26.5.0.cl|v2.24.0 or later +|ThoughtSpot Cloud: 26.4.0.cl|v2.23.0 or later +|ThoughtSpot Cloud: 26.3.0.cl|v2.22.0 or later +|ThoughtSpot Software: 26.3.0.sw|v2.22.0 or later +|ThoughtSpot Cloud: 26.2.0.cl|v2.21.0 or later +|ThoughtSpot Cloud: 10.15.0.cl|v2.20.0 or later +|ThoughtSpot Cloud: 10.14.0.cl|v2.19.0 or later +|ThoughtSpot Cloud: 10.13.0.cl|v2.18.0 or later +|ThoughtSpot Cloud: 10.12.0.cl|v2.17.0 or later +|ThoughtSpot Cloud: 10.11.0.cl|v2.16.0 or later +|ThoughtSpot Cloud: 10.10.0.cl|v2.15.1 or later +|ThoughtSpot Software: 10.10.0.sw|v2.15.1 or later +|ThoughtSpot Cloud: 10.9.0.cl|v2.14.0 or later |==== == SDK Reference diff --git a/modules/ROOT/pages/rest-api-python-sdk.adoc b/modules/ROOT/pages/rest-api-python-sdk.adoc index a2567bc18..183851120 100644 --- a/modules/ROOT/pages/rest-api-python-sdk.adoc +++ b/modules/ROOT/pages/rest-api-python-sdk.adoc @@ -373,7 +373,7 @@ on every request. [options='header'] |==== |ThoughtSpot release version|Recommended SDK version -a|ThoughtSpot Cloud: 26.8.0.cl | v2.27.0 or later +a|ThoughtSpot Cloud: 26.8.0.cl | v2.27.1 or later a|ThoughtSpot Cloud: 26.7.0.cl | v2.26.0 or later |==== diff --git a/modules/ROOT/pages/rest-api-sdk-typescript.adoc b/modules/ROOT/pages/rest-api-sdk-typescript.adoc index 12744fa42..3710ff63d 100644 --- a/modules/ROOT/pages/rest-api-sdk-typescript.adoc +++ b/modules/ROOT/pages/rest-api-sdk-typescript.adoc @@ -196,47 +196,43 @@ const test = async () => { ---- == Supported versions - -Note the version recommendations for your ThoughtSpot instances: - + [width="100%" cols="2,2"] [options='header'] |==== |ThoughtSpot release version|Recommended SDK version -a|ThoughtSpot Cloud: 26.8.0.cl | v2.27.0 or later -a|ThoughtSpot Cloud: 26.7.0.cl | v2.26.0 or later -a|ThoughtSpot Cloud: 26.6.0.cl | v2.25.0 or later -a|ThoughtSpot Cloud: 26.5.0.cl | v2.24.0 or later -a|ThoughtSpot Cloud: 26.4.0.cl | v2.23.0 or later -a|ThoughtSpot Cloud: 26.3.0.cl | v2.22.0 or later -a|ThoughtSpot Cloud: 26.2.0.cl | v2.21.0 or later -a|ThoughtSpot Cloud: 10.15.0.cl | v2.20.0 or later -a|ThoughtSpot Cloud: 10.14.0.cl | v2.19.0 or later -a|ThoughtSpot Cloud: 10.13.0.cl | v2.18.0 or later -a|ThoughtSpot Cloud: 10.12.0.cl | v2.17.0 or later -a|ThoughtSpot Cloud: 10.11.0.cl | v2.16.0 or later -a|ThoughtSpot Cloud: 10.10.0.cl | v2.15.1 or later -a|ThoughtSpot Cloud: 10.9.0.cl | v2.14.0 or later -a|ThoughtSpot Cloud: 10.8.0.cl | v2.13.1 or later -a|ThoughtSpot Cloud: 10.6.0.cl | v2.12.1 or later -a|* ThoughtSpot Cloud release versions: + -** 9.12.0.cl + -** 9.12.5.cl + -** 10.1.0.cl + -** 10.3.0.cl + -** 10.4.0.cl + -** 10.5.0.cl + -* ThoughtSpot Software: 10.1.0.sw -| v2.11.1 or later -a|* ThoughtSpot Cloud: 9.10.5.cl | v2.4.1 or later -a|* ThoughtSpot Cloud: 9.10.0.cl | v2.4.0 or later -a|* ThoughtSpot Cloud: 9.8.0.cl + -* ThoughtSpot Software: 9.8.0.sw | v2.2.0 or later -a|* ThoughtSpot Cloud: 9.7.0.cl + -* ThoughtSpot Software: 9.8.0.sw | v2.1.0 or later -a|* ThoughtSpot Cloud: 9.6.0.cl + -* ThoughtSpot Software: 9.8.0.sw | v2.0.2 or later - +|ThoughtSpot Cloud: 26.8.0.cl|v2.27.1 or later +|ThoughtSpot Cloud: 26.7.0.cl|v2.26.0 or later +|ThoughtSpot Cloud: 26.6.0.cl|v2.25.0 or later +|ThoughtSpot Cloud: 26.5.0.cl|v2.24.0 or later +|ThoughtSpot Cloud: 26.4.0.cl|v2.23.0 or later +|ThoughtSpot Cloud: 26.3.0.cl|v2.22.0 or later +|ThoughtSpot Software: 26.3.0.sw|v2.22.0 or later +|ThoughtSpot Cloud: 26.2.0.cl|v2.21.0 or later +|ThoughtSpot Cloud: 10.15.0.cl|v2.20.0 or later +|ThoughtSpot Cloud: 10.14.0.cl|v2.19.0 or later +|ThoughtSpot Cloud: 10.13.0.cl|v2.18.0 or later +|ThoughtSpot Cloud: 10.12.0.cl|v2.17.0 or later +|ThoughtSpot Cloud: 10.11.0.cl|v2.16.0 or later +|ThoughtSpot Cloud: 10.10.0.cl|v2.15.1 or later +|ThoughtSpot Cloud: 10.9.0.cl|v2.14.0 or later +|ThoughtSpot Cloud: 10.8.0.cl|v2.13.1 or later +|ThoughtSpot Cloud: 10.6.0.cl|v2.12.1 or later +|ThoughtSpot Cloud: 9.12.0.cl|v2.11.1 or later +|ThoughtSpot Cloud: 9.12.5.cl|v2.11.1 or later +|ThoughtSpot Cloud: 10.1.0.cl|v2.11.1 or later +|ThoughtSpot Cloud: 10.3.0.cl|v2.11.1 or later +|ThoughtSpot Cloud: 10.4.0.cl|v2.11.1 or later +|ThoughtSpot Cloud: 10.5.0.cl|v2.11.1 or later +|ThoughtSpot Software: 10.1.0.sw|v2.11.1 or later +|ThoughtSpot Cloud: 9.10.5.cl|v2.4.1 or later +|ThoughtSpot Cloud: 9.10.0.cl|v2.4.0 or later +|ThoughtSpot Cloud: 9.8.0.cl|v2.2.0 or later +|ThoughtSpot Software: 9.8.0.sw|v2.2.0 or later +|ThoughtSpot Cloud: 9.7.0.cl|v2.1.0 or later +|ThoughtSpot Software: 9.8.0.sw|v2.1.0 or later +|ThoughtSpot Cloud: 9.6.0.cl|v2.0.2 or later +|ThoughtSpot Software: 9.8.0.sw|v2.0.2 or later |==== For information about new features, breaking changes, and deprecated parameters, see xref:rest-apiv2-changelog.adoc[API changelog]. From 6c85211bd8bf759debb62c9e0d3f7dd47c75869f Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Fri, 21 Aug 2026 16:55:11 +0530 Subject: [PATCH 079/154] SCAL-333737 --- modules/ROOT/pages/security-settings.adoc | 38 +++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/modules/ROOT/pages/security-settings.adoc b/modules/ROOT/pages/security-settings.adoc index a0a1a3131..1d4cbd94e 100644 --- a/modules/ROOT/pages/security-settings.adoc +++ b/modules/ROOT/pages/security-settings.adoc @@ -21,6 +21,44 @@ To avoid this issue, ThoughtSpot recommends the following: * If you are using a ThoughtSpot Cloud instance, set up your instance to the same domain as your host application. For more information, see link:https://docs.thoughtspot.com/cloud/latest/custom-domains[Custom domain configuration, window=_blank]. * If you are using authentication methods that rely on cookies, xref:_enable_partitioned_cookies[enable partitioned cookies]. +[#network-access-requirements] +== Network access requirements + +If your organization uses a firewall or Content Delivery Network (CDN) with domain-level access controls, you must allowlist the following domains before provisioning a new ThoughtSpot cluster or modifying an existing firewall configuration. Without access to the critical domains, ThoughtSpot will not load. + +=== Critical domains + +Allowlist the following domains to ensure ThoughtSpot loads correctly. If any of these are blocked, ThoughtSpot will not function. + +[options="header",cols="2,3"] +|=== +|Domain |Purpose +|`+*.thoughtspot.cloud+` |ThoughtSpot application and APIs +|`+*.thoughtspotartifacts.cloud+` |Static assets and build artifacts +|`+*.thoughtspotlogin.cloud+` |Authentication and login flows +|`+ok14static.oktacdn.com+` |Okta authentication assets +|`+*.cloudfront.net+` |CDN-served ThoughtSpot resources +|`+cdn.skypack.dev+` |JavaScript module delivery +|`+cdn.jsdelivr.net+` |Open-source library assets +|`+cdnjs.cloudflare.com+` |Open-source library assets +|`+code.jquery.com+` |jQuery library +|=== + +=== Optional domains + +Allowlist the following domains if you use the corresponding ThoughtSpot features. + +[options="header",cols="2,3"] +|=== +|Domain |Feature +|`+cdn.mxpnl.com+` |Mixpanel product analytics +|`+app.pendo.io+` |Pendo in-app guidance +|`+cdn.pendo.io+` |Pendo in-app guidance +|`+fonts.googleapis.com+` |Google Fonts +|`+js.intercomcdn.com+` |Intercom in-app support +|`+fast.wistia.com+` |Wistia embedded video content +|=== + == Configure security settings Users with administration privileges can configure security settings on the Security settings page of the ThoughtSpot UI, or by sending a request to the `POST /api/rest/2.0/system/security-settings/configure` API endpoint. Note that the following settings on the **Security Settings** page will appear as locked for ThoughtSpot Analytics application users and will require an embedding license: From 90555e546a39d756004b043d79ed3c144dd387c8 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Mon, 24 Aug 2026 11:30:19 +0530 Subject: [PATCH 080/154] Spotter API chunking --- .../pages/common/nav-in-product-help.adoc | 5 + modules/ROOT/pages/common/nav-rest-api.adoc | 5 + modules/ROOT/pages/rest-apiv2-changelog.adoc | 4 +- modules/ROOT/pages/spotter-agent-apis.adoc | 1417 +---------------- .../spotter-agent-conversation-apis.adoc | 385 +++++ .../spotter-agent-conversation-mgmt-apis.adoc | 4 +- .../spotter-agent-data-literacy-apis.adoc | 190 +++ .../spotter-agent-process-results-apis.adoc | 46 + .../pages/spotter-agent-sharing-apis.adoc | 155 ++ .../pages/spotter-agent-streaming-apis.adoc | 664 ++++++++ modules/ROOT/pages/spotter-apis.adoc | 5 + modules/ROOT/pages/whats-new.adoc | 4 +- 12 files changed, 1496 insertions(+), 1388 deletions(-) create mode 100644 modules/ROOT/pages/spotter-agent-conversation-apis.adoc create mode 100644 modules/ROOT/pages/spotter-agent-data-literacy-apis.adoc create mode 100644 modules/ROOT/pages/spotter-agent-process-results-apis.adoc create mode 100644 modules/ROOT/pages/spotter-agent-sharing-apis.adoc create mode 100644 modules/ROOT/pages/spotter-agent-streaming-apis.adoc diff --git a/modules/ROOT/pages/common/nav-in-product-help.adoc b/modules/ROOT/pages/common/nav-in-product-help.adoc index 73d3dedd9..46f7187b8 100644 --- a/modules/ROOT/pages/common/nav-in-product-help.adoc +++ b/modules/ROOT/pages/common/nav-in-product-help.adoc @@ -224,6 +224,11 @@ REST APIs ** link:{{navprefix}}/fetch-data-and-report-apis[Data and Report APIs] ** link:{{navprefix}}/spotter-api[Spotter APIs] *** link:{{navprefix}}/spotter-agent-apis[AI APIs (Spotter Agent and Spotter 3)] +*** link:{{navprefix}}/spotter-agent-conversation-apis[Spotter agent conversation APIs] +*** link:{{navprefix}}/spotter-agent-streaming-apis[Spotter agent streaming APIs] +*** link:{{navprefix}}/spotter-agent-process-results-apis[Process Spotter agent conversation results] +*** link:{{navprefix}}/spotter-agent-data-literacy-apis[Spotter agent data literacy APIs] +*** link:{{navprefix}}/spotter-agent-sharing-apis[Spotter agent conversation sharing APIs] *** link:{{navprefix}}/spotter-agent-instructions[Spotter AI agent instructions] *** link:{{navprefix}}/spotter-agent-conversation-mgmt-apis[APIs for managing saved conversations] *** link:{{navprefix}}/spotter-memory-migration[Spotter memory migration API] diff --git a/modules/ROOT/pages/common/nav-rest-api.adoc b/modules/ROOT/pages/common/nav-rest-api.adoc index 3ab94642e..d18328927 100644 --- a/modules/ROOT/pages/common/nav-rest-api.adoc +++ b/modules/ROOT/pages/common/nav-rest-api.adoc @@ -23,6 +23,11 @@ REST APIs ** link:{{navprefix}}/runtime-sort[Runtime sorting] ** link:{{navprefix}}/spotter-api[Spotter APIs] *** link:{{navprefix}}/spotter-agent-apis[AI APIs (Spotter Agent and Spotter 3)] +*** link:{{navprefix}}/spotter-agent-conversation-apis[Spotter agent conversation APIs] +*** link:{{navprefix}}/spotter-agent-streaming-apis[Spotter agent streaming APIs] +*** link:{{navprefix}}/spotter-agent-process-results-apis[Process Spotter agent conversation results] +*** link:{{navprefix}}/spotter-agent-data-literacy-apis[Spotter agent data literacy APIs] +*** link:{{navprefix}}/spotter-agent-sharing-apis[Spotter agent conversation sharing APIs] *** link:{{navprefix}}/spotter-agent-instructions[Spotter AI agent instructions] *** link:{{navprefix}}/spotter-agent-conversation-mgmt-apis[APIs for managing saved conversations] *** link:{{navprefix}}/spotter-memory-migration[Spotter memory migration API] diff --git a/modules/ROOT/pages/rest-apiv2-changelog.adoc b/modules/ROOT/pages/rest-apiv2-changelog.adoc index b5325b191..dbf3eca3b 100644 --- a/modules/ROOT/pages/rest-apiv2-changelog.adoc +++ b/modules/ROOT/pages/rest-apiv2-changelog.adoc @@ -79,7 +79,7 @@ This changelog lists the features and enhancements introduced in REST API v2.0. | `GET` | `/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info` | Returns sharing metadata — the list of principals the conversation is shared with and their access levels. The `is_shared_content_outdated` flag indicates if the shared snapshot is stale. |===== - For more information, see xref:spotter-agent-apis.adoc#_sharing_spotter_conversations[Sharing Spotter conversations]. + For more information, see xref:spotter-agent-sharing-apis.adoc[Sharing Spotter conversations]. === KPI Sparkline setting in metadata search response @@ -290,7 +290,7 @@ Stop in-progress agent response:: * `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response` + Stops a Spotter agent response that is currently in progress for a given conversation session. -For more information, see xref:spotter-agent-apis.adoc#_stop_an_in_progress_agent_response[Stop an in-progress agent response]. +For more information, see xref:spotter-agent-conversation-apis.adoc#_stop_an_in_progress_agent_response[Stop an in-progress agent response]. === Authentication The following new endpoints allow searching for the authentication configuration at the cluster or Org level, and also allow enabling and disabling authentication. These endpoints currently support only trusted authentication. diff --git a/modules/ROOT/pages/spotter-agent-apis.adoc b/modules/ROOT/pages/spotter-agent-apis.adoc index b9a909ee3..383af675b 100644 --- a/modules/ROOT/pages/spotter-agent-apis.adoc +++ b/modules/ROOT/pages/spotter-agent-apis.adoc @@ -19,62 +19,61 @@ The key capabilities of the Spotter APIs include the following: * Recommending relevant datasets or data sources * Decomposing complex user queries -== API endpoints - -The AI REST API endpoints listed in the following table provide all the functionality necessary to implement a Spotter 3 conversational experience in your application, from data source discovery through to streaming query responses. +== Supported API endpoints The API endpoints introduced for Spotter 2 also support Spotter 3 capabilities as of version 26.2.0.cl. Some of these API endpoints are deprecated in 26.5.0.cl; ThoughtSpot recommends using the new API endpoints instead. Initialize session:: -Call the create agent conversation API (`/api/rest/2.0/ai/agent/conversation/create`) with a data source ID to establish the session context. When auto mode is enabled, and no data source ID is specified in the API request, Spotter will automatically identify the appropriate data source. +Call the create agent conversation API (`/api/rest/2.0/ai/agent/conversation/create`) with a data source ID to establish the session context. When auto mode is enabled, and no data source ID is specified in the API request, Spotter will automatically identify the appropriate data source. See xref:spotter-agent-conversation-apis.adoc[Spotter agent conversation APIs]. Execute queries:: -To execute queries and generate a standard response synchronously, use the Send agent conversation message API (`/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send`). The send agent message API (`/api/rest/2.0/ai/agent/{conversation_identifier}/converse`) is deprecated in 26.5.0.cl and later versions. +To execute queries and generate a standard response synchronously, use the Send agent conversation message API (`/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send`). The send agent message API (`/api/rest/2.0/ai/agent/{conversation_identifier}/converse`) is deprecated in 26.5.0.cl and later versions. See xref:spotter-agent-conversation-apis.adoc[Spotter agent conversation APIs]. Real-time output (streaming):: -To stream responses to the application UI in real-time, use the `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream`. The legacy streaming API (`/api/rest/2.0/ai/agent/converse/sse`) is deprecated in 26.5.0.cl and later versions. +To stream responses to the application UI in real-time, use the `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream`. The legacy streaming API (`/api/rest/2.0/ai/agent/converse/sse`) is deprecated in 26.5.0.cl and later versions. See xref:spotter-agent-streaming-apis.adoc[Spotter agent streaming APIs]. + +Share a conversation:: +Share a saved Spotter conversation with other users or groups as read-only content. See xref:spotter-agent-sharing-apis.adoc[Spotter agent conversation sharing APIs]. -=== Supported API endpoints [width="100%" cols="1"] |===== a|`POST /api/rest/2.0/ai/agent/conversation/create` + -xref:spotter-agent-apis.adoc#_create_a_conversation_session_with_spotter_agent[Creates a conversation session with the Spotter agent] to generate Answers for the specified data context. +xref:spotter-agent-conversation-apis.adoc#_create_a_conversation_session_with_spotter_agent[Creates a conversation session with the Spotter agent] to generate Answers for the specified data context. __Available on ThoughtSpot Cloud instances from 10.13.0.cl onwards. Breaking changes introduced in 26.5.0.cl.__ a| `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send` [.version-badge.new]#New# + -xref:spotter-agent-apis.adoc#_send_queries_to_a_conversation_session[Sends natural language messages] to an existing Spotter agent conversation and returns the complete response synchronously. +xref:spotter-agent-conversation-apis.adoc#_send_queries_to_a_conversation_session[Sends natural language messages] to an existing Spotter agent conversation and returns the complete response synchronously. __Replaces /api/rest/2.0/ai/agent/{conversation_identifier}/converse__. a|`POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream` [.version-badge.new]#New# + -xref:spotter-agent-apis.adoc#_send_a_query_to_agent_and_get_streaming_responses[Sends one or more natural language messages] to an existing Spotter agent conversation and returns the response as a real-time Server-Sent Events (SSE) stream. +xref:spotter-agent-streaming-apis.adoc[Sends one or more natural language messages] to an existing Spotter agent conversation and returns the response as a real-time Server-Sent Events (SSE) stream. __Replaces /api/rest/2.0/ai/agent/converse/sse__. a|`POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response` [.version-badge.new]#New# + -xref:spotter-agent-apis.adoc#_stop_an_in_progress_agent_response[Stops an in-progress Spotter agent response] for a given conversation session. The conversation session remains active after the response stops. + +xref:spotter-agent-conversation-apis.adoc#_stop_an_in_progress_agent_response[Stops an in-progress Spotter agent response] for a given conversation session. The conversation session remains active after the response stops. + __Available on ThoughtSpot Cloud instances from 26.6.0.cl onwards.__ a| `POST /api/rest/2.0/ai/data-source-suggestions` [beta betaBackground]^Beta^ + -xref:spotter-agent-apis.adoc#_get_data_source_suggestions[Returns a list of relevant data sources], such as Models, based on a query and thus helping users and agents choose the most appropriate data source for analytics. + +xref:spotter-agent-data-literacy-apis.adoc#_get_data_source_suggestions[Returns a list of relevant data sources], such as Models, based on a query and thus helping users and agents choose the most appropriate data source for analytics. + __Available on ThoughtSpot Cloud instances from 10.15.0.cl onwards__. a| `POST /api/rest/2.0/ai/relevant-questions/` [beta betaBackground]^Beta^ + -xref:spotter-agent-apis.adoc#_get_relevant_questions[Decomposes a user query] into relevant sub-questions. Guides users to explore data more deeply for a comprehensive analysis. + +xref:spotter-agent-data-literacy-apis.adoc#_get_relevant_questions[Decomposes a user query] into relevant sub-questions. Guides users to explore data more deeply for a comprehensive analysis. + __Available on ThoughtSpot Cloud instances from 10.13.0.cl onwards__. +a| `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` [.version-badge.new]#New# + +xref:spotter-agent-sharing-apis.adoc#_share_a_conversation[Shares a saved Spotter conversation] with one or more users or groups. Use `grant` and `revoke` arrays to manage access. Shared conversations are `READ_ONLY`. + +__Available on ThoughtSpot Cloud instances from 26.9.0.cl onwards.__ - a| `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` [.version-badge.new]#New# + - xref:spotter-agent-apis.adoc#_share_a_conversation[Shares a saved Spotter conversation] with one or more users or groups. Use `grant` and `revoke` arrays to manage access. Shared conversations are `READ_ONLY`. + - __Available on ThoughtSpot Cloud instances from 26.9.0.cl onwards.__ - - a| `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content` [.version-badge.new]#New# + - xref:spotter-agent-apis.adoc#_get_shared_content[Returns the shared content] of a Spotter conversation, including messages and associated answers. + - __Available on ThoughtSpot Cloud instances from 26.9.0.cl onwards.__ +a| `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content` [.version-badge.new]#New# + +xref:spotter-agent-sharing-apis.adoc#_get_shared_content[Returns the shared content] of a Spotter conversation, including messages and associated answers. + +__Available on ThoughtSpot Cloud instances from 26.9.0.cl onwards.__ - a| `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info` [.version-badge.new]#New# + - xref:spotter-agent-apis.adoc#_get_share_information[Returns sharing metadata] for a Spotter conversation — the list of principals it is shared with and whether the shared content is outdated. + - __Available on ThoughtSpot Cloud instances from 26.9.0.cl onwards.__ +a| `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info` [.version-badge.new]#New# + +xref:spotter-agent-sharing-apis.adoc#_get_share_information[Returns sharing metadata] for a Spotter conversation — the list of principals it is shared with and whether the shared content is outdated. + +__Available on ThoughtSpot Cloud instances from 26.9.0.cl onwards.__ - a| `POST /api/rest/2.0/ai/agent/converse/sse` [.version-badge.deprecated]#Deprecated# + +a| `POST /api/rest/2.0/ai/agent/converse/sse` [.version-badge.deprecated]#Deprecated# + Legacy API endpoint for streaming responses, including tokens and visualizations, for a specific conversation context. __Deprecated in 26.5.0.cl__. @@ -83,1365 +82,19 @@ Legacy API endpoint to send natural language queries to a conversation session w __Deprecated in 26.5.0.cl__. |===== -== Create a conversation session with Spotter Agent - -The `/api/rest/2.0/ai/agent/conversation/create` API endpoint creates a new conversation session with Spotter Agent for a specific or multi-data context and returns a conversation ID. - -=== Request parameters -The request body must include the `metadata_context`. REST API clients must have at least view access to the data source objects specified in the API request to create a conversation session and use it for subsequent queries. - -[width="100%" cols="2,4"] -[options='header'] -|===== -|Form parameter| Description -|`metadata_context` a| Defines the data context for the conversation. - -* `type` + -Metadata context type. The context type is mandatory. Select one of the following values: - -** `AUTO_MODE` to allow Spotter Agent to automatically discover and select the most relevant datasets for users' queries. -** `DATA_SOURCE` to set a specific data source as the data context. You must specify `data_source_context` and data source IDs. + -To set a specific data source object, use `data_source_identifier`. + -To set multi-data context, use `data_source_identifiers`. -** `data_source` [.version-badge.deprecated]#Deprecated# + -This option is deprecated in 26.5.0.cl. ThoughtSpot recommends using the `DATA_SOURCE` with `data_source_context` and data source IDs instead. - -|`conversation_settings` a|__Optional__. Defines additional parameters for the conversation context. You can set any of the following attributes as needed: - -* `enable_contextual_change_analysis` + -__Boolean__. When enabled, Spotter analyzes how context changes over time, that is, comparing results from different queries. Enabled by default in 26.2.0.cl and later versions. -* `enable_natural_language_answer_generation` + -__Boolean__. Allows sending natural language queries to the conversation session. Enabled by default in 26.2.0.cl and later versions. -* `enable_reasoning` + -__Boolean__. Allows Spotter to use reasoning for deep analysis and precise responses. Enabled by default in 26.2.0.cl and later versions. -* `enable_save_chat` + -When set to `true`, adds the conversation to chat history. -|===== - -=== Example request - -With AUTO_MODE for metadata context:: - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/create' \ - -H 'Accept: application/json' \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {AUTH_TOKEN}' \ - --data-raw '{ - "metadata_context": { - "type": "AUTO_MODE" - }, - "conversation_settings": { - "enable_save_chat": true - } -}' ----- - -For a single data source as the data context:: - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/create' \ - -H 'Accept: application/json' \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {AUTH_TOKEN}' \ - --data-raw '{ - "metadata_context": { - "type": "DATA_SOURCE", - "data_source_context": { - "data_source_identifier": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" - } - }, - "conversation_settings": {} -}' ----- - -For multi-data source context:: - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/create' \ - -H 'Accept: application/json' \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {AUTH_TOKEN}' \ - --data-raw '{ - "metadata_context": { - "type": "DATA_SOURCE", - "data_source_context": { - "data_source_identifiers": [ - "a1b2c3d4-e5f6-7890-abcd-ef1234567890", - "b2c3d4e5-f6a7-8901-bcde-f12345678901" - ] - } - }, - "conversation_settings": { - "enable_save_chat": true - } -}' ----- - -=== API response - -If the API request is successful, the API returns the conversation ID and identifier in the response body. - -[source,JSON] ----- -{ - "conversation_id": "wwHQ5j8O8dQC", - "conversation_identifier": "wwHQ5j8O8dQC" -} ----- - -* `conversation_identifier` + -Use this for all subsequent message calls. -* `conversation_id` [.version-badge.deprecated]#Deprecated# + -Returns the same value as `conversation_identifier`. - -== Send queries to a conversation session - -To send queries to an ongoing conversation session with the Spotter agent and receive a response synchronously, use the `/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send` API endpoint. - -This API operation requires the conversation ID obtained from the conversation creation API endpoint (`/api/rest/2.0/ai/agent/conversation/create`). The user making the API request must have access to the conversation session. The API request body must include at least one message in natural language format. - -=== Request parameters - -[width="100%" cols="2,2,4"] -[options='header'] -|===== -|Parameter|Type| Description -|`conversation_identifier`|Path parameter|__String__. Required. Specify the conversation ID received from the xref:spotter-agent-apis.adoc#_create_a_conversation_session_with_spotter_agent[POST /api/rest/2.0/ai/agent/conversation/create] API call. -|`messages`|Form parameter|_Array of strings_. Required. Specify at least one query in natural language. For example, `total sales of jackets last month`. -|===== - - -//// -|`settings` |__Optional__. Defines additional parameters for the conversation context. You can set any of the following attributes as needed: - -* `enable_contextual_change_analysis` + -__Boolean__. When enabled, Spotter analyzes how the context changes over time, that is comparing results from different queries. -* `enable_natural_language_answer_generation` + -__Boolean__. Allows sending natural language queries to the conversation session. -* `enable_reasoning` + -__Boolean__. Allows Spotter to use reasoning for deep analysis and precise responses. -//// - -=== Request and response examples - -The following example sends a data comparison query to a conversation session. The conversation ID is specified in the request URL as a path parameter. - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send' \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {AUTH_TOKEN}' \ - --data-raw '{ - "messages": [ - "Sales in 2025 vs 2024" - ] -}' ----- - -If the request is successful, the API returns an array of objects in the response. The messages in the API response include the following parts: - -[source,JSON] ----- -[ - { - "type": "text", - "text": "\n\nI'll compare sales between 2025 and 2024. First, let me get the dataset context.", - "metadata": {}, - "internal": {}, - "agent_context": "" - }, - { - "type": "text", - "text": "```json\n{\"dataset_name\":\"(Sample) Retail - Apparel\",\"columns\":[{\"name\":\"sales\",\"type\":\"MEASURE\"},{\"name\":\"date\",\"type\":\"ATTRIBUTE\"}]}\n```", - "metadata": {}, - "internal": {}, - "agent_context": "" - }, - { - "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", - "metadata": { - "output": "", - "worksheet_id": "cd252e5c-b552-49a8-821d-3eadaa049cca", - "chart_type": "KPI", - "interrupted": false, - "data_awareness_enabled": true - }, - "internal": {} - }, - { - "type": "text", - "text": "\n\nThe visualization shows year-over-year comparison. You can identify growth or decline trends.", - "metadata": {}, - "internal": {}, - "agent_context": "" - } -] ----- - -The following example sends a follow-up question to the same conversation session. - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send' \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {AUTH_TOKEN}' \ - --data-raw '{ - "messages": [ - "Now break that down by product category" - ] -}' ----- - -If the request is successful, the agent returns the response for the follow-up question: - -[source,JSON] ----- -[{ - "type": "text", - "text": "I'll add product category to the comparison.", - "metadata": {}, - "internal": {}, - "agent_context": "" - }, - { - "type": "answer", - "title": "Sales by Product Category: 2025 vs 2024", - "session_id": "9abc1234-0000-0000-0000-000000000005", - "gen_no": 3, - "sage_query": "[sales] [product category] [date] = '2025' vs [date] = '2024'", - "tml_tokens": ["[sales]", "[product category]", "[date] = '2025' vs [date] = '2024'"], - "formulas": [], - "parameters": [], - "subqueries": [], - "viz_suggestion": "", - "metadata": { - "chart_type": "BAR", - "worksheet_id": "cd252e5c-b552-49a8-821d-3eadaa049cca" - }, - "internal": {} - }] ----- - -In each response, the agent returns the following information: - -* `type` + -Type of the message, such as text, answer, or error. -* `text` + -Response message generated for the query. -* `metadata` + -Additional information based on the message type. For example, answer metadata, chart type, or the data source ID. -* `tml_tokens` + -Query string broken down as TML tokens. - -In case of errors, the response returns the error details: - -[source,JSON] ----- -[{ - "type": "error", - "message": "The conversation session has expired. Please create a new conversation.", - "code": "SESSION_EXPIRED" -}] ----- - - - -//// -The following example shows the response text contents for the `answer` message type. - -[source,JSON] ----- -[ - { - "id": "r24X7D99SROD", - "type": "answer", - "group_id": "o8dQ9SAWdtrL", - "metadata": { - "sage_query": "[sales] [item type] = [item type].'jackets'", - "session_id": "b321b404-cbf1-4905-9b0c-b93ad4eedf89", - "gen_no": 1, - "transaction_id": "6874259d-13b1-478c-83cb-b3ed52628850", - "generation_number": 1, - "warning_details": null, - "ambiguous_phrases": null, - "query_intent": null, - "assumptions": "You want to see the total sales amount for jackets item type.", - "tml_phrases": [ - "[sales]", - "[item type] = [item type].'jackets'" - ], - "cached": false, - "sub_queries": null, - "title": "Net sales of Jackets", - "worksheet_id": "cd252e5c-b552-49a8-821d-3eadaa049cca" - }, - "title": "Net sales of Jackets" - } -] ----- - -The session ID and generation number serve as the data context for the Answer. You can use this information to create a new conversation session using `/api/rest/2.0/ai/agent/conversation/create`, or download the answer via the `/api/rest/2.0/report/answer` API endpoint. - - -* The tokens and TML phrases returned in the response can be used as inputs for the search data API call to get an Answer. -//// - -== Send a query to agent and get streaming responses - -To send queries to an ongoing conversation session with Spotter agent and receive streaming responses, use the `/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream` API endpoint. This API endpoint uses the SSE protocol to deliver data incrementally in real time, rather than waiting for the entire response to be generated before sending it to the client. - -The `/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream` API can be used as an integrated tool for real-time streaming of conversational interactions between agents and the ThoughtSpot backend. - -=== Request parameters - -[width="100%" cols="2,4"] -[options='header'] -|===== -|Parameter| Description -|`conversation_identifier` |__String__. Specify the conversation ID received from the xref:spotter-agent-apis.adoc#_create_a_conversation_session_with_spotter_agent[POST /api/rest/2.0/ai/agent/conversation/create] API call. -|`messages`|_Array of strings_. Include at least one natural language query. For example, `Sales data for Jackets`, `Top performing products in the west coast`. -|===== - -=== Example request - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream' \ - -H 'Accept: application/json' \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {AUTH_TOKEN}' \ - --data-raw '{ - "conversation_identifier": "h2I_pTGaRQof", - "messages": [ - "Net sales of Jackets" - ] -}' ----- - -=== API response - -If the API request is successful, the response includes a stream of events, each containing a partial or complete message from the AI agent, rather than a single JSON object. - -Each event is a simple text-based message in a specific format, `data: \n\n`; `\n\n` means that each message sent from the server to the client is prefixed with the `data:` keyword, followed by the actual payload (``), and ends with two newline characters (`\n\n`). - -The API uses this format so that the clients can reconstruct the AI-generated response as it streams in, chunk by chunk, and show the responses in real-time. In agentic workflows, the receiving client or agent listens to the SSE stream, parses each event, and assembles the full response for its users. - -==== Example response -If the request is valid, the API returns SSE streams. Each line has the form `data: [{"type": "...", ...}]`, a JSON array of event objects. - -[source,JSON] ----- -data: [{"type":"ack","node_id":"aGxzcFVrtom8"}] - -data: [{"type":"conv_title","title":"Sales 2025 vs 2024","conv_id":"-XIi04l5rrof"}] - -data: [{"type":"notification","group_id":"cDEsAQbSnd3J","metadata":{"type":"thinking","tool_title":"Analyzing Sales Performance: 2025 vs 2024"},"code":"TOOL_CALL_NOTIFICATION"}] - -data: [{"id":"mNAdvy-NK2l6","type":"text-chunk","group_id":"cDEsAQbSnd3J","metadata":{"format":"markdown","type":"thinking"},"content":"\n\nI need to compare sales performance between 2025 and 2024."}] - -data: [{"type":"notification","group_id":"m1MTvttEUa7o","code":"nls_start"}] - -data: [{"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"}] - -data: [{"type":"notification","code":"FINAL_RESPONSE_NOTIFICATION"}] ----- -For the complete response in one payload, use the xref:spotter-agent-apis.adoc#_send_queries_to_a_conversation_session[`/send` endpoint] instead. - -//// -[source,] ----- -data: [{"type": "ack", "node_id": "BRxCtJ-aGt8l"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": "I"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " understand"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " you're"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " interested"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " in"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " the"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " net"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " sales"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " of"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " Jackets"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": "."}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " I'll"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " retrieve"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " the"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " relevant"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " data"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " for"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " you"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": "."}] - -data: [{"type": "notification", "group_id": "o8dQ9SAWdtrL", "metadata": {"title": "Net sales of Jackets"}, "code": "nls_start"}] - -data: [{"type": "notification", "group_id": "o8dQ9SAWdtrL", "code": "QH", "message": "Fetching Worksheet Data"}] - -data: [{"type": "notification", "group_id": "o8dQ9SAWdtrL", "code": "TML_GEN", "message": "Translating your query with the Reasoning Engine"}] - -data: [{"type": "notification", "group_id": "o8dQ9SAWdtrL", "code": "ANSWER_GEN", "message": "Verifying results with the Trust Layer"}] - -data: [{"id": "r24X7D99SROD", "type": "answer", "group_id": "o8dQ9SAWdtrL", "metadata": {"sage_query": "[sales] [item type] = [item type].'jackets'", "session_id": "b321b404-cbf1-4905-9b0c-b93ad4eedf89", "gen_no": 1, "transaction_id": "6874259d-13b1-478c-83cb-b3ed52628850", "generation_number": 1, "warning_details": null, "ambiguous_phrases": null, "query_intent": null, "assumptions": "You want to see the total sales amount for jackets item type.", "tml_phrases": ["[sales]", "[item type] = [item type].'jackets'"], "cached": false, "sub_queries": null, "title": "Net sales of Jackets", "worksheet_id": "cd252e5c-b552-49a8-821d-3eadaa049cca"}, "title": "Net sales of Jackets"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "The"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " net"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " sales"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " for"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " Jackets"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " have"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " been"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " visual"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "ized"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " for"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " you"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "."}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " This"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " analysis"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " specifically"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " filtered"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " for"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " the"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " item"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " type"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "jackets"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "\""}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " and"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " calculated"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " the"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " total"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " sales"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " amount"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " associated"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " with"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " those"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " products"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ".\n\n"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "**"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "Summary"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " &"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " Insights"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ":"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "**\n"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "-"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " The"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " visualization"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " shows"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " the"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " total"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " net"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " sales"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " for"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " all"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " jacket"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " transactions"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " in"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " your"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " apparel"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " dataset"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ".\n"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "-"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " The"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " calculation"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " uses"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " only"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " sales"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " amounts"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " where"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " the"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " item"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " type"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " is"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " \""}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "J"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "ackets"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ".\"\n"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "-"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " This"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " information"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " is"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " useful"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " for"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " understanding"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " the"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " revenue"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " contribution"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " of"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " jackets"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " within"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " your"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " product"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " mix"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ".\n\n"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "If"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " you'd"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " like"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " to"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " see"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " a"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " breakdown"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " by"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " region"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ","}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " state"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ","}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " time"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " period"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ","}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " or"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " compare"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " jacket"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " sales"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " to"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " other"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " product"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " types"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ","}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " please"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " let"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " me"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " know"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "!"}] ----- -//// - -==== SSE event types -The SSE event types streamed in the API response include: - -* `ack` + -Confirms receipt of the request. For example, the type in the first message `data: [{"type": "ack", "node_id": "BRxCtJ-aGt8l"}]`, which indicates that the server has received the client's request and is acknowledging it. -* `conv_title` + -A conversation title (`title`, `conv_id`). -* `notification` + -Progress or status update (`group_id`, `metadata`, `code`). For example, `TOOL_CALL_NOTIFICATION`, `nls_start`, `FINAL_RESPONSE_NOTIFICATION`. -* `type` + -Type can be `thinking`, `text`. -* `text` + -Complete text block in markdown format. -* `text-chunk` + -Text fragments in incremental streaming, often in markdown (`id`, `group_id`, `metadata` with `format`) -* `content` + -The actual text content sent incrementally. For example, `"I"`, `"understand"`, `"you're"`, `"interested"`, `"in"`, `"the"`, `"net"`, `"sales"`, and so on. -* `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` and more) -* `error` + -In case of failures. -* `*-interrupt` + -If the generation was stopped mid-stream. -* `group_id` + -Groups related chunks together. - -For more information and examples, see xref:spotter-agent-apis.adoc#_sse_event_payload_reference[SSE event payload reference]. - -=== Thinking versus output events -Spotter responses have two phases: - -* A *thinking phase*, where the AI reasons through the query and calls internal tools, followed by an *output phase* containing the final response delivered to the user. + - -Events in the thinking phase carry `"metadata": { "type": "thinking" }`. All other events are final output. - -Every event includes a `group_id`. Events sharing the same `group_id` belong together. During the thinking phase, each tool call gets its own `group_id`. A `FINAL_RESPONSE_NOTIFICATION` notification marks the boundary between the thinking and output phases. - -[listing] ----- -THINKING PHASE -─────────────────────────────────────────────────────────── -ack - -┌─ group_id: g1 ── Tool Call 1 ("Searching data") ─────────┐ -│ notification (thinking, TOOL_CALL_NOTIFICATION) │ -│ text-chunk (thinking) │ -│ answer (thinking) │ -└──────────────────────────────────────────────────────────┘ - -┌─ group_id: g2 ── Tool Call 2 ("Running code") ───────────┐ -│ notification (thinking, TOOL_CALL_NOTIFICATION) │ -│ text-chunk (thinking) │ -│ text-chunk (thinking) │ -└──────────────────────────────────────────────────────────┘ - -notification (FINAL_RESPONSE_NOTIFICATION) ←── boundary -──────────────────────────────────────────────────────────── - -OUTPUT PHASE -──────────────────────────────────────────────────────────── -┌─ group_id: g3 ────────────────────────────────────────────┐ -│ text "Here are the results:" │ -│ answer (final visualization) │ -└───────────────────────────────────────────────────────────┘ -[stream closes] ----- - -==== Notification codes reference - -[width="100%" cols="2,4"] -[options='header'] -|===== -|Code| When it appears -|`QH`|Query handling started -|`TML_GEN` / `TML_GEN_RETRY`|Generating or retrying TML -|`ANSWER_GEN`|Generating an answer -|`IDENTIFYING_ATTRIBUTES`|Identifying data attributes -|`PERFORMING_CHANGE_ANALYSIS`|Running change analysis -|`PERFORMING_FORECASTING_ANALYSIS`|Running forecasting -|`SUMMARIZING_RESULTS`|Summarizing results -|`TOOL_CALL_NOTIFICATION`|Tool invocation (during thinking phase) -|`FINAL_RESPONSE_NOTIFICATION`|Marks the transition from thinking to output -|`search_datasets_start` / `search_datasets_end`|Data source discovery in progress or complete -|`approval_required`|An external tool requires user permission before proceeding -|===== - -=== SSE event payload reference - -==== ack - -[source,JSON] ----- -data: { - "type": "ack", - "group_id": "a1b2c3", - "id": "evt-001", - "node_id": "resp-node-abc" -} ----- - -==== notification (thinking — tool call) - -[source,JSON] ----- -data: { - "type": "notification", - "group_id": "g1", - "id": "evt-002", - "code": "TOOL_CALL_NOTIFICATION", - "message": "Searching for relevant data", - "metadata": { - "type": "thinking", - "tool_title": "Searching sales data", - "tool_code": "RUNNING_CODE_EXECUTION", - "tool_name": "code_interpreter" - } -} ----- - -==== notification (thinking - external tool with MCP integration) - -[source,JSON] ----- -data: { - "type": "notification", - "group_id": "g2", - "id": "evt-003", - "code": "TOOL_CALL_NOTIFICATION", - "message": "Querying Salesforce", - "metadata": { - "type": "thinking", - "tool_title": "Salesforce: Get Opportunities", - "tool_name": "get_opportunities", - "integration_id": "int-sf-123", - "integration_name": "Salesforce" - } -} ----- - -==== notification (approval required) -Sent when an external MCP tool requires explicit user permission before proceeding. Your application should prompt the user to approve or deny the action before continuing. - -[source,JSON] ----- -data: { - "type": "notification", - "group_id": "g2", - "id": "evt-005", - "code": "approval_required", - "metadata": { - "request_id": "perm-req-789", - "integration_id": "int-sf-123", - "integration_name": "Salesforce", - "tool_name": "get_opportunities", - "annotated_title": "Access Salesforce Opportunities" - } -} ----- - -==== notification (FINAL_RESPONSE_NOTIFICATION) - -[source,JSON] ----- -data: { - "type": "notification", - "group_id": "g1", - "id": "evt-004", - "code": "FINAL_RESPONSE_NOTIFICATION", - "message": "" -} ----- - -==== text - -[source,JSON] ----- -data: { - "type": "text", - "group_id": "g3", - "id": "evt-007", - "content": "Here is the total revenue breakdown by region for Q4 2025:\n\n- **North America:** $4.2M\n- **EMEA:** $2.8M\n- **APAC:** $1.5M" -} ----- - -==== text-chunk -Multiple chunks sharing the same `id` should be appended together to reconstruct the full text item. - -[source,JSON] ----- -data: { "type": "text-chunk", "group_id": "g3", "id": "evt-009", "content": "Based on the analysis, " } -data: { "type": "text-chunk", "group_id": "g3", "id": "evt-009", "content": "revenue grew 12% quarter-over-quarter." } ----- - -==== answer -When an `answer` event is received, the `session_id` and `gen_no` fields are returned. You can export the visualization data using the Export Answer Report API to process the results. This allows users to download the answer as a PDF, PNG, CSV, or XLSX file. - -[source,JSON] ----- -data: { - "type": "answer", - "group_id": "g3", - "id": "evt-010", - "title": "Revenue by Region Q4 2025", - "metadata": { - "session_id": "sess-abc-123", - "gen_no": 1, - "transaction_id": "txn-456", - "worksheet_id": "ws-def-789", - "cached": false, - "is_hidden": false - } -} ----- - -==== search_datasets -Emitted as a start/end pair during Auto mode data source discovery. - - -[source,JSON] ----- -data: { "type": "search_datasets", "group_id": "g0", "id": "evt-012", "code": "search_datasets_start", "metadata": {} } - -data: { - "type": "search_datasets", - "group_id": "g0", - "id": "evt-013", - "code": "search_datasets_end", - "metadata": { - "data_sources": [ - { "worksheet_id": "ws-1", "worksheet_name": "Sales Data", "confidence": "high", "reasoning": "Contains revenue columns" }, - { "worksheet_id": "ws-2", "worksheet_name": "Marketing Data", "confidence": "low", "reasoning": "No revenue columns" } - ], - "auto_selected": { "worksheet_id": "ws-1", "worksheet_name": "Sales Data", "confidence": "high", "reasoning": "Best match" } - } -} ----- -==== file - -[source,JSON] ----- -data: { - "type": "file", - "group_id": "g3", - "id": "evt-014", - "files": [ - { "ts_file_id": "file-abc-001", "display_name": "quarterly_report.csv", "file_type": "csv", "created_at": "2025-11-15T10:30:00Z" }, - { "ts_file_id": "file-abc-002", "display_name": "chart.png", "file_type": "png", "created_at": "2025-11-15T10:30:01Z" } - ], - "metadata": { "conv_id": "conv-123" } -} ----- -==== conv_title - -[source,JSON] ----- -data: { - "type": "conv_title", - "group_id": "g0", - "id": "evt-015", - "title": "Revenue Analysis Q4 2025", - "conv_id": "conv-123" -} ----- - -==== error - -[source,JSON] ----- -data: { - "type": "error", - "group_id": "g3", - "id": "evt-016", - "code": "RATE_LIMIT_EXCEEDED", - "message": "Too many requests", - "display_message": "You've exceeded the rate limit. Please try again in a few minutes." -} ----- -==== agent-interrupt - -[source,JSON] ----- -Sent when generation is stopped mid-stream. -data: { - "type": "notification", - "group_id": "g3", - "id": "evt-017", - "code": "agent-interrupt", - "message": "Generation stopped" -} ----- - -[#_stop_an_in_progress_agent_response] -== Stop an in-progress agent response - -The `/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response` API endpoint stops a Spotter agent response that is currently in progress for a given conversation session. - -Use this endpoint when you want to cancel a long-running Spotter response before it completes. The conversation session remains active after you stop a response, so you can send a new query to the same session immediately. - -=== Request parameters - -[width="100%", cols="2,2,4"] -[options='header'] -|===== -|Parameter|Type| Description -|`conversation_identifier`|Path parameter|__String__. Required. The identifier of the active conversation session. Use the value returned by the xref:spotter-agent-apis.adoc#_create_a_conversation_session_with_spotter_agent[create conversation] API endpoint. -|===== - -This endpoint does not require a request body. - -=== Example request - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response' \ - -H 'Accept: application/json' \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {AUTH_TOKEN}' ----- - -=== Example response - -If the API request is successful, ThoughtSpot stops the in-progress response and returns a 204 response code. - -If the conversation session is not found or has expired, the API returns an error: - -[source,JSON] ----- -{ - "error_code": "CONVERSATION_NOT_FOUND", - "message": "The specified conversation session does not exist or has expired." -} ----- - -[#process_results] -== Process results generated from a conversation session -To export or download the Answer data generated by the Spotter APIs, use the xref:data-report-v2-api.adoc#exportSpotterData[Answer report] API. - -The `session_id` and `gen_no` values from the `answer` event metadata are required to identify the answer to export. - -NOTE: Requires at least view access to the Answer. - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \ - -H 'Authorization: Bearer {Bearer_token}' \ - -H 'Accept: application/octet-stream' \ - -H 'Content-Type: application/json' \ - --data-raw '{ - "session_identifier": "sess-abc-123", - "generation_number": 1, - "file_format": "CSV" -}' ----- -The `file_format` parameter accepts `PDF`, `PNG`, `CSV`, or `XLSX`. - -[NOTE] -==== -Using tokens generated by the Spotter API in a xref:data-report-v2-api.adoc#_search_data_api[Search Data API] request can return invalid column errors, because these tokens may reference formulas or columns not present in the data model. Instead, use the xref:data-report-v2-api.adoc#exportSpotterData[Answer report] API and include the session ID and generation number obtained from the Spotter API in your API request to retrieve the data. -==== - - -== Data literacy and query assistance -The query assistance APIs help users find the appropriate dataset for a given query string, suggest what questions can be asked, and return example questions. These APIs are specifically designed to improve data literacy for users who may not be familiar with the underlying data, making it easier for them to explore and analyze data effectively. - -=== Get data source suggestions - -The `POST /api/rest/2.0/ai/data-source-suggestions` API provides relevant data source recommendations for a user-submitted natural language query. To use this API, you must have at least view access to the underlying metadata object referenced in the response. - -==== Request parameters - -[width="100%" cols="2,4"] -[options='header'] -|==== -|Parameter| Description -|`metadata_context` a| Required. Specify one of the following attributes to set the metadata context: - -* `data_source_identifiers` + -__Array of strings__. IDs of the data source object such as Models. -* `answer_identifiers` + -__Array of strings__. GUIDs of the Answer objects that you want to use as metadata. -* `conversation_identifier` + -__String__. ID of the conversation session. -* `liveboard_identifiers` + -__Array of strings__. GUIDs of the Liveboards that you want to use as metadata. - -| `query` |__String__. Required parameter. Specify the query string that needs to be decomposed into smaller, analytical sub-questions. -|`limit_relevant_questions` + -__Optional__ | __Integer__. Sets a limit on the number of sub-questions to return in the response. Default is 5. -|`bypass_cache` + -__Optional__| __Boolean__. When set to `true`, disables cache and forces fresh computation. -|`ai_context` + -__Optional__. a| Additional context to guide the response. Define the following attributes as needed: -|==== - -==== Example request - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/data-source-suggestions' \ - -H 'Accept: application/json' \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {AUTH_TOKEN}' \ - --data-raw '{ - "metadata_context": { - "data_source_identifiers": [ - "cd252e5c-b552-49a8-821d-3eadaa049cca" - ] - }, - "query": "Net sales of Jackets in west coast", - "limit_relevant_questions": 3 -}' ----- - -==== API response -If the API request is successful, ThoughtSpot returns a ranked list of data sources, each annotated with relevant reasoning. - -[source,JSON] ----- -{ - "relevant_questions": [ - { - "query": "What is the trend of sales by type over time?", - "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", - "data_source_name": "(Sample) Retail - Apparel" - }, - { - "query": "Sales by item", - "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", - "data_source_name": "(Sample) Retail - Apparel" - }, - { - "query": "Sales across regions", - "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", - "data_source_name": "(Sample) Retail - Apparel" - } - ] -} ----- - -The returned results include metadata such as: - -* `confidence` + -A float indicating the Model's confidence in the relevance of each recommendation. -* `details` + -The data source ID, name, and description for each recommended data source. -* `reasoning` + -Reason provided by the LLM to explain why each data source was recommended. - -=== Get relevant questions - -The `/api/rest/2.0/ai/relevant-questions/` API endpoint breaks down a user-submitted query into relevant sub-questions. It accepts the original query and optional additional context, then generates a set of related questions to help users explore their data comprehensively. - -During agentic interactions, this API can be used as an integrated tool to decompose user queries and suggest relevant questions for a specific data context. REST clients can also call this API directly to fetch relevant questions via a `POST` request. - -==== Request parameters - -[width="100%" cols="2,4"] -[options='header'] -|===== -|Parameter| Description -|`metadata_context` a| Required. Specify one of the following attributes to set the metadata context: - -* `data_source_identifiers` + -__Array of strings__. IDs of the data source object such as Models. -* `answer_identifiers` + -__Array of strings__. GUIDs of the Answer objects that you want to use as metadata. -* `conversation_identifier` + -__String__. ID of the conversation session. -* `liveboard_identifiers` + -__Array of strings__. GUIDs of the Liveboards that you want to use as metadata. - -| `query` |__String__. Required parameter. Specify the query string that needs to be decomposed into smaller, analytical sub-questions. -|`limit_relevant_questions` + -__Optional__ | __Integer__. Sets a limit on the number of sub-questions to return in the response. Default is 5. -|`bypass_cache` + -__Optional__| __Boolean__. When set to `true`, disables cache and forces fresh computation. -|`ai_context` + -__Optional__. a| Additional context to guide the response. Define the following attributes as needed: - -* `instructions` + -__Array of strings__. Custom user instructions to influence how the AI interprets and processes the query. -* `content` + -__Array of strings__. Additional input such as raw text or CSV-formatted data to enhance context and answer quality. -|===== - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/relevant-questions/' \ - -H 'Accept: application/json' \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {AUTH_TOKEN}' \ - --data-raw '{ - "metadata_context": { - "data_source_identifiers": [ - "cd252e5c-b552-49a8-821d-3eadaa049cca" - ] - }, - "query": "Net sales of Jackets in west coast", - "limit_relevant_questions": 3 -}' ----- - -==== Example response -If the request is successful, the API returns a set of questions related to the query and metadata context in the `relevant_questions` array. Each object in the `relevant_questions` array contains the following fields: - -* `query` + -A string containing the natural language (NL) sub-question. -* `data_source_identifier` + -GUID of the data source object. -* `data_source_name` + -Name of the associated data source object. - -[source,JSON] ----- -{ - "relevant_questions": [ - { - "query": "What is the trend of sales by type over time?", - "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", - "data_source_name": "(Sample) Retail - Apparel" - }, - { - "query": "Sales by item", - "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", - "data_source_name": "(Sample) Retail - Apparel" - }, - { - "query": "Sales across regions", - "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", - "data_source_name": "(Sample) Retail - Apparel" - } - ] -} ----- - == Additional resources +* xref:spotter-agent-conversation-apis.adoc[Spotter agent conversation APIs] + +Create conversation sessions, send synchronous queries, and stop in-progress responses. +* xref:spotter-agent-streaming-apis.adoc[Spotter agent streaming APIs] + +Send queries and receive real-time Server-Sent Events (SSE) responses from the Spotter agent. +* xref:spotter-agent-process-results-apis.adoc[Process Spotter agent conversation results] + +Export or download Answers generated by a Spotter agent conversation session. +* xref:spotter-agent-data-literacy-apis.adoc[Spotter agent data literacy APIs] + +Get data source suggestions and decompose a user query into relevant sub-questions. +* xref:spotter-agent-sharing-apis.adoc[Spotter agent conversation sharing APIs] + +Share saved Spotter conversations with other users and groups. +* xref:spotter-agent-conversation-mgmt-apis.adoc[APIs for managing saved conversations] + +Retrieve, update, and delete saved Spotter 3 conversations and their messages. * Visit the +++REST API v2.0 Playground+++ to view the API endpoints and verify the request and response workflows. * For information about MCP tools, see xref:mcp-integration.adoc[MCP server integration]. - - [#_sharing_spotter_conversations] - == Sharing Spotter conversations - - // SOURCE: SCAL-306173 (aug.26.mt) - // SOURCE: prism/src/public-apis/nl-to-answer.graphql (master) - - ThoughtSpot provides REST API v2.0 endpoints to share saved Spotter agent conversations with other users or groups. Shared conversations are always `READ_ONLY` — recipients can view conversation messages and associated answers but cannot send new queries or modify the conversation. - - === Supported endpoints - - [width="100%" cols="1"] - |===== - a| `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` [.version-badge.new]#New# + - xref:spotter-agent-apis.adoc#_share_a_conversation[Shares a saved Spotter conversation] with one or more users or groups. + - __Available on ThoughtSpot Cloud instances from 26.9.0.cl onwards.__ - - a| `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content` [.version-badge.new]#New# + - xref:spotter-agent-apis.adoc#_get_shared_content[Returns the shared content] of a Spotter conversation, including messages and associated answers. + - __Available on ThoughtSpot Cloud instances from 26.9.0.cl onwards.__ - - a| `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info` [.version-badge.new]#New# + - xref:spotter-agent-apis.adoc#_get_share_information[Returns sharing metadata] for a Spotter conversation — the list of principals it is shared with. + - __Available on ThoughtSpot Cloud instances from 26.9.0.cl onwards.__ - |===== - - [#_share_a_conversation] - === Share a conversation - - Use `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` to share a saved Spotter conversation with one or more principals. - - ==== Path parameters - - [width="100%" cols="2,4"] - [options="header"] - |===== - | Parameter | Description - | `conversation_identifier` | The GUID of the saved Spotter conversation to share. - |===== - - ==== Request body parameters - - [width="100%" cols="2,1,4"] - [options="header"] - |===== - | Parameter | Required | Description - | `grant` | No | Array of principal identifiers to grant access. Each entry is a `user_identifier` (username or GUID) or `group_identifier` (group name or GUID). All shared access is `READ_ONLY`. - | `revoke` | No | Array of principal identifiers to revoke access from. - | `refresh_shared_content` | No | Boolean. When `true`, regenerates the shared content snapshot. Default: `false`. - | `notify_on_share` | No | Boolean. When `true`, sends an in-app notification to principals receiving access. Default: `true`. Available from 26.10.0.cl. - |===== - - ==== Example request - - [source,cURL] - ---- - curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share' \ - -H 'Authorization: Bearer {access-token}' \ - -H 'Accept: application/json' \ - -H 'Content-Type: application/json' \ - --data-raw '{ - "grant": [ - {"user_identifier": "user@example.com"}, - {"group_identifier": "analysts-group"} - ], - "revoke": [], - "refresh_shared_content": false - }' - ---- - - [#_get_shared_content] - === Get shared content - - Use `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content` to retrieve the content of a shared Spotter conversation. - - ==== Path parameters - - [width="100%" cols="2,4"] - [options="header"] - |===== - | Parameter | Description - | `conversation_identifier` | The GUID of the shared Spotter conversation. - |===== - - ==== Response fields - - [width="100%" cols="2,4"] - [options="header"] - |===== - | Field | Description - | `conversation_id` | GUID of the original conversation. - | `shared_conversation_id` | GUID of the shared conversation snapshot. - | `messages` | Array of conversation messages included in the shared snapshot. - | `data_sources` | Array of data source identifiers used in the conversation. - | `code_execution_files` | Array of files generated by code execution steps, if any. - |===== - - ==== Example request - - [source,cURL] - ---- - curl -X GET \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content' \ - -H 'Authorization: Bearer {access-token}' \ - -H 'Accept: application/json' - ---- - - [#_get_share_information] - === Get share information - - Use `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info` to retrieve sharing metadata for a Spotter conversation. - - ==== Path parameters - - [width="100%" cols="2,4"] - [options="header"] - |===== - | Parameter | Description - | `conversation_identifier` | The GUID of the Spotter conversation. - |===== - - ==== Response fields - - [width="100%" cols="2,4"] - [options="header"] - |===== - | Field | Description - | `is_shared_content_outdated` | Boolean. `true` if the shared content snapshot is stale. Use the share endpoint with `refresh_shared_content: true` to regenerate. - | `principals` | Array of principal objects the conversation is shared with. Each entry includes the principal identifier and their access level (always `READ_ONLY`). - |===== - - ==== Example request - - [source,cURL] - ---- - curl -X GET \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info' \ - -H 'Authorization: Bearer {access-token}' \ - -H 'Accept: application/json' - ---- - \ No newline at end of file diff --git a/modules/ROOT/pages/spotter-agent-conversation-apis.adoc b/modules/ROOT/pages/spotter-agent-conversation-apis.adoc new file mode 100644 index 000000000..1e094a6aa --- /dev/null +++ b/modules/ROOT/pages/spotter-agent-conversation-apis.adoc @@ -0,0 +1,385 @@ += Spotter agent conversation APIs +:toc: true +:toclevels: 2 + +:page-title: Spotter agent conversation APIs +:page-pageid: spotter-agent-conversation-apis +:page-description: Use the Spotter agent conversation REST APIs to create conversation sessions, send natural language queries, and stop in-progress responses. + +ThoughtSpot's Spotter agent conversation APIs allow you to create a conversation session with the Spotter agent, send natural language queries to it, and stop an in-progress response. + +For information about receiving responses as a real-time event stream, see xref:spotter-agent-streaming-apis.adoc[Spotter agent streaming APIs]. For information about exporting Answers generated by a conversation, see xref:spotter-agent-process-results-apis.adoc[Process Spotter agent conversation results]. For information about the data source and question suggestion APIs, see xref:spotter-agent-data-literacy-apis.adoc[Spotter agent data literacy APIs]. For information about sharing saved conversations, see xref:spotter-agent-sharing-apis.adoc[Spotter agent conversation sharing APIs]. + +== Create a conversation session with Spotter Agent + +The `/api/rest/2.0/ai/agent/conversation/create` API endpoint creates a new conversation session with Spotter Agent for a specific or multi-data context and returns a conversation ID. + +=== Request parameters +The request body must include the `metadata_context`. REST API clients must have at least view access to the data source objects specified in the API request to create a conversation session and use it for subsequent queries. + +[width="100%" cols="2,4"] +[options='header'] +|===== +|Form parameter| Description +|`metadata_context` a| Defines the data context for the conversation. + +* `type` + +Metadata context type. The context type is mandatory. Select one of the following values: + +** `AUTO_MODE` to allow Spotter Agent to automatically discover and select the most relevant datasets for users' queries. +** `DATA_SOURCE` to set a specific data source as the data context. You must specify `data_source_context` and data source IDs. + +To set a specific data source object, use `data_source_identifier`. + +To set multi-data context, use `data_source_identifiers`. +** `data_source` [.version-badge.deprecated]#Deprecated# + +This option is deprecated in 26.5.0.cl. ThoughtSpot recommends using the `DATA_SOURCE` with `data_source_context` and data source IDs instead. + +|`conversation_settings` a|__Optional__. Defines additional parameters for the conversation context. You can set any of the following attributes as needed: + +* `enable_contextual_change_analysis` + +__Boolean__. When enabled, Spotter analyzes how context changes over time, that is, comparing results from different queries. Enabled by default in 26.2.0.cl and later versions. +* `enable_natural_language_answer_generation` + +__Boolean__. Allows sending natural language queries to the conversation session. Enabled by default in 26.2.0.cl and later versions. +* `enable_reasoning` + +__Boolean__. Allows Spotter to use reasoning for deep analysis and precise responses. Enabled by default in 26.2.0.cl and later versions. +* `enable_save_chat` + +When set to `true`, adds the conversation to chat history. +|===== + +=== Example request + +With AUTO_MODE for metadata context:: + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/create' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "metadata_context": { + "type": "AUTO_MODE" + }, + "conversation_settings": { + "enable_save_chat": true + } +}' +---- + +For a single data source as the data context:: + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/create' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "metadata_context": { + "type": "DATA_SOURCE", + "data_source_context": { + "data_source_identifier": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + } + }, + "conversation_settings": {} +}' +---- + +For multi-data source context:: + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/create' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "metadata_context": { + "type": "DATA_SOURCE", + "data_source_context": { + "data_source_identifiers": [ + "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "b2c3d4e5-f6a7-8901-bcde-f12345678901" + ] + } + }, + "conversation_settings": { + "enable_save_chat": true + } +}' +---- + +=== API response + +If the API request is successful, the API returns the conversation ID and identifier in the response body. + +[source,JSON] +---- +{ + "conversation_id": "wwHQ5j8O8dQC", + "conversation_identifier": "wwHQ5j8O8dQC" +} +---- + +* `conversation_identifier` + +Use this for all subsequent message calls. +* `conversation_id` [.version-badge.deprecated]#Deprecated# + +Returns the same value as `conversation_identifier`. + +== Send queries to a conversation session + +To send queries to an ongoing conversation session with the Spotter agent and receive a response synchronously, use the `/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send` API endpoint. + +This API operation requires the conversation ID obtained from the conversation creation API endpoint (`/api/rest/2.0/ai/agent/conversation/create`). The user making the API request must have access to the conversation session. The API request body must include at least one message in natural language format. + +=== Request parameters + +[width="100%" cols="2,2,4"] +[options='header'] +|===== +|Parameter|Type| Description +|`conversation_identifier`|Path parameter|__String__. Required. Specify the conversation ID received from the xref:spotter-agent-conversation-apis.adoc#_create_a_conversation_session_with_spotter_agent[POST /api/rest/2.0/ai/agent/conversation/create] API call. +|`messages`|Form parameter|_Array of strings_. Required. Specify at least one query in natural language. For example, `total sales of jackets last month`. +|===== + + +//// +|`settings` |__Optional__. Defines additional parameters for the conversation context. You can set any of the following attributes as needed: + +* `enable_contextual_change_analysis` + +__Boolean__. When enabled, Spotter analyzes how the context changes over time, that is comparing results from different queries. +* `enable_natural_language_answer_generation` + +__Boolean__. Allows sending natural language queries to the conversation session. +* `enable_reasoning` + +__Boolean__. Allows Spotter to use reasoning for deep analysis and precise responses. +//// + +=== Request and response examples + +The following example sends a data comparison query to a conversation session. The conversation ID is specified in the request URL as a path parameter. + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "messages": [ + "Sales in 2025 vs 2024" + ] +}' +---- + +If the request is successful, the API returns an array of objects in the response. The messages in the API response include the following parts: + +[source,JSON] +---- +[ + { + "type": "text", + "text": "\n\nI'll compare sales between 2025 and 2024. First, let me get the dataset context.", + "metadata": {}, + "internal": {}, + "agent_context": "" + }, + { + "type": "text", + "text": "```json\n{\"dataset_name\":\"(Sample) Retail - Apparel\",\"columns\":[{\"name\":\"sales\",\"type\":\"MEASURE\"},{\"name\":\"date\",\"type\":\"ATTRIBUTE\"}]}\n```", + "metadata": {}, + "internal": {}, + "agent_context": "" + }, + { + "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", + "metadata": { + "output": "", + "worksheet_id": "cd252e5c-b552-49a8-821d-3eadaa049cca", + "chart_type": "KPI", + "interrupted": false, + "data_awareness_enabled": true + }, + "internal": {} + }, + { + "type": "text", + "text": "\n\nThe visualization shows year-over-year comparison. You can identify growth or decline trends.", + "metadata": {}, + "internal": {}, + "agent_context": "" + } +] +---- + +The following example sends a follow-up question to the same conversation session. + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "messages": [ + "Now break that down by product category" + ] +}' +---- + +If the request is successful, the agent returns the response for the follow-up question: + +[source,JSON] +---- +[{ + "type": "text", + "text": "I'll add product category to the comparison.", + "metadata": {}, + "internal": {}, + "agent_context": "" + }, + { + "type": "answer", + "title": "Sales by Product Category: 2025 vs 2024", + "session_id": "9abc1234-0000-0000-0000-000000000005", + "gen_no": 3, + "sage_query": "[sales] [product category] [date] = '2025' vs [date] = '2024'", + "tml_tokens": ["[sales]", "[product category]", "[date] = '2025' vs [date] = '2024'"], + "formulas": [], + "parameters": [], + "subqueries": [], + "viz_suggestion": "", + "metadata": { + "chart_type": "BAR", + "worksheet_id": "cd252e5c-b552-49a8-821d-3eadaa049cca" + }, + "internal": {} + }] +---- + +In each response, the agent returns the following information: + +* `type` + +Type of the message, such as text, answer, or error. +* `text` + +Response message generated for the query. +* `metadata` + +Additional information based on the message type. For example, answer metadata, chart type, or the data source ID. +* `tml_tokens` + +Query string broken down as TML tokens. + +In case of errors, the response returns the error details: + +[source,JSON] +---- +[{ + "type": "error", + "message": "The conversation session has expired. Please create a new conversation.", + "code": "SESSION_EXPIRED" +}] +---- + + + +//// +The following example shows the response text contents for the `answer` message type. + +[source,JSON] +---- +[ + { + "id": "r24X7D99SROD", + "type": "answer", + "group_id": "o8dQ9SAWdtrL", + "metadata": { + "sage_query": "[sales] [item type] = [item type].'jackets'", + "session_id": "b321b404-cbf1-4905-9b0c-b93ad4eedf89", + "gen_no": 1, + "transaction_id": "6874259d-13b1-478c-83cb-b3ed52628850", + "generation_number": 1, + "warning_details": null, + "ambiguous_phrases": null, + "query_intent": null, + "assumptions": "You want to see the total sales amount for jackets item type.", + "tml_phrases": [ + "[sales]", + "[item type] = [item type].'jackets'" + ], + "cached": false, + "sub_queries": null, + "title": "Net sales of Jackets", + "worksheet_id": "cd252e5c-b552-49a8-821d-3eadaa049cca" + }, + "title": "Net sales of Jackets" + } +] +---- + +The session ID and generation number serve as the data context for the Answer. You can use this information to create a new conversation session using `/api/rest/2.0/ai/agent/conversation/create`, or download the answer via the `/api/rest/2.0/report/answer` API endpoint. + + +* The tokens and TML phrases returned in the response can be used as inputs for the search data API call to get an Answer. +//// + +[#_stop_an_in_progress_agent_response] +== Stop an in-progress agent response + +The `/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response` API endpoint stops a Spotter agent response that is currently in progress for a given conversation session. + +Use this endpoint when you want to cancel a long-running Spotter response before it completes. The conversation session remains active after you stop a response, so you can send a new query to the same session immediately. + +=== Request parameters + +[width="100%", cols="2,2,4"] +[options='header'] +|===== +|Parameter|Type| Description +|`conversation_identifier`|Path parameter|__String__. Required. The identifier of the active conversation session. Use the value returned by the xref:spotter-agent-conversation-apis.adoc#_create_a_conversation_session_with_spotter_agent[create conversation] API endpoint. +|===== + +This endpoint does not require a request body. + +=== Example request + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' +---- + +=== Example response + +If the API request is successful, ThoughtSpot stops the in-progress response and returns a 204 response code. + +If the conversation session is not found or has expired, the API returns an error: + +[source,JSON] +---- +{ + "error_code": "CONVERSATION_NOT_FOUND", + "message": "The specified conversation session does not exist or has expired." +} +---- + +== Additional resources + +* See also xref:spotter-agent-apis.adoc[Spotter Agent APIs] +* xref:spotter-agent-streaming-apis.adoc[Spotter agent streaming APIs] +* xref:spotter-agent-process-results-apis.adoc[Process Spotter agent conversation results] +* xref:spotter-agent-data-literacy-apis.adoc[Spotter agent data literacy APIs] +* xref:spotter-agent-sharing-apis.adoc[Spotter agent conversation sharing APIs] +* Visit the +++REST API v2.0 Playground+++ to view the API endpoints and verify the request and response workflows. diff --git a/modules/ROOT/pages/spotter-agent-conversation-mgmt-apis.adoc b/modules/ROOT/pages/spotter-agent-conversation-mgmt-apis.adoc index 371233233..b8b4a1dda 100644 --- a/modules/ROOT/pages/spotter-agent-conversation-mgmt-apis.adoc +++ b/modules/ROOT/pages/spotter-agent-conversation-mgmt-apis.adoc @@ -42,7 +42,7 @@ __Available on ThoughtSpot Cloud instances from 26.7.0.cl onwards.__ |===== == Saving a conversation -To save a conversation, set the `enable_save_chat` parameter to `true` when sending a xref:spotter-agent-apis.adoc#_create_a_conversation_session_with_spotter_agent[conversation create `POST` request] to the `/api/rest/2.0/ai/agent/conversation/create` API endpoint. +To save a conversation, set the `enable_save_chat` parameter to `true` when sending a xref:spotter-agent-conversation-apis.adoc#_create_a_conversation_session_with_spotter_agent[conversation create `POST` request] to the `/api/rest/2.0/ai/agent/conversation/create` API endpoint. === API request example @@ -308,7 +308,7 @@ Each item in `conversations` represents a saved conversation. [options="header"] |===== |Field|Description -|`conversation_identifier`|__String__. Unique identifier of the conversation. Use this value as input in your API requests to the xref:spotter-agent-apis.adoc#_send_queries_to_a_conversation_session[send message], xref:spotter-agent-conversation-mgmt-apis.adoc#update-conversation[update conversation], xref:spotter-agent-conversation-mgmt-apis.adoc#delete-conversation[delete conversation], xref:spotter-agent-apis.adoc#_stop_an_in_progress_agent_response[stop response], and xref:spotter-agent-conversation-mgmt-apis.adoc#load-answer[load answer] endpoints. +|`conversation_identifier`|__String__. Unique identifier of the conversation. Use this value as input in your API requests to the xref:spotter-agent-conversation-apis.adoc#_send_queries_to_a_conversation_session[send message], xref:spotter-agent-conversation-mgmt-apis.adoc#update-conversation[update conversation], xref:spotter-agent-conversation-mgmt-apis.adoc#delete-conversation[delete conversation], xref:spotter-agent-conversation-apis.adoc#_stop_an_in_progress_agent_response[stop response], and xref:spotter-agent-conversation-mgmt-apis.adoc#load-answer[load answer] endpoints. |`conversation_title` a|__String__. Display name of the conversation. |`created_at`|__String__. Timestamp of when the conversation was created. |`updated_at`|__String__. Timestamp of when the conversation was last updated. diff --git a/modules/ROOT/pages/spotter-agent-data-literacy-apis.adoc b/modules/ROOT/pages/spotter-agent-data-literacy-apis.adoc new file mode 100644 index 000000000..85ab15a91 --- /dev/null +++ b/modules/ROOT/pages/spotter-agent-data-literacy-apis.adoc @@ -0,0 +1,190 @@ += Spotter agent data literacy APIs +:toc: true +:toclevels: 2 + +:page-title: Spotter agent data literacy APIs +:page-pageid: spotter-agent-data-literacy-apis +:page-description: Use the Spotter data literacy REST APIs to get relevant data source suggestions and decompose a user query into relevant sub-questions. + +The query assistance APIs help users find the appropriate dataset for a given query string, suggest what questions can be asked, and return example questions. These APIs are specifically designed to improve data literacy for users who may not be familiar with the underlying data, making it easier for them to explore and analyze data effectively. + +For information about creating a conversation session, see xref:spotter-agent-conversation-apis.adoc[Spotter agent conversation APIs]. + +== Get data source suggestions + +The `POST /api/rest/2.0/ai/data-source-suggestions` API provides relevant data source recommendations for a user-submitted natural language query. To use this API, you must have at least view access to the underlying metadata object referenced in the response. + +=== Request parameters + +[width="100%" cols="2,4"] +[options='header'] +|==== +|Parameter| Description +|`metadata_context` a| Required. Specify one of the following attributes to set the metadata context: + +* `data_source_identifiers` + +__Array of strings__. IDs of the data source object such as Models. +* `answer_identifiers` + +__Array of strings__. GUIDs of the Answer objects that you want to use as metadata. +* `conversation_identifier` + +__String__. ID of the conversation session. +* `liveboard_identifiers` + +__Array of strings__. GUIDs of the Liveboards that you want to use as metadata. + +| `query` |__String__. Required parameter. Specify the query string that needs to be decomposed into smaller, analytical sub-questions. +|`limit_relevant_questions` + +__Optional__ | __Integer__. Sets a limit on the number of sub-questions to return in the response. Default is 5. +|`bypass_cache` + +__Optional__| __Boolean__. When set to `true`, disables cache and forces fresh computation. +|`ai_context` + +__Optional__. a| Additional context to guide the response. Define the following attributes as needed: +|==== + +=== Example request + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/data-source-suggestions' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "metadata_context": { + "data_source_identifiers": [ + "cd252e5c-b552-49a8-821d-3eadaa049cca" + ] + }, + "query": "Net sales of Jackets in west coast", + "limit_relevant_questions": 3 +}' +---- + +=== API response +If the API request is successful, ThoughtSpot returns a ranked list of data sources, each annotated with relevant reasoning. + +[source,JSON] +---- +{ + "relevant_questions": [ + { + "query": "What is the trend of sales by type over time?", + "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", + "data_source_name": "(Sample) Retail - Apparel" + }, + { + "query": "Sales by item", + "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", + "data_source_name": "(Sample) Retail - Apparel" + }, + { + "query": "Sales across regions", + "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", + "data_source_name": "(Sample) Retail - Apparel" + } + ] +} +---- + +The returned results include metadata such as: + +* `confidence` + +A float indicating the Model's confidence in the relevance of each recommendation. +* `details` + +The data source ID, name, and description for each recommended data source. +* `reasoning` + +Reason provided by the LLM to explain why each data source was recommended. + +== Get relevant questions + +The `/api/rest/2.0/ai/relevant-questions/` API endpoint breaks down a user-submitted query into relevant sub-questions. It accepts the original query and optional additional context, then generates a set of related questions to help users explore their data comprehensively. + +During agentic interactions, this API can be used as an integrated tool to decompose user queries and suggest relevant questions for a specific data context. REST clients can also call this API directly to fetch relevant questions via a `POST` request. + +=== Request parameters + +[width="100%" cols="2,4"] +[options='header'] +|===== +|Parameter| Description +|`metadata_context` a| Required. Specify one of the following attributes to set the metadata context: + +* `data_source_identifiers` + +__Array of strings__. IDs of the data source object such as Models. +* `answer_identifiers` + +__Array of strings__. GUIDs of the Answer objects that you want to use as metadata. +* `conversation_identifier` + +__String__. ID of the conversation session. +* `liveboard_identifiers` + +__Array of strings__. GUIDs of the Liveboards that you want to use as metadata. + +| `query` |__String__. Required parameter. Specify the query string that needs to be decomposed into smaller, analytical sub-questions. +|`limit_relevant_questions` + +__Optional__ | __Integer__. Sets a limit on the number of sub-questions to return in the response. Default is 5. +|`bypass_cache` + +__Optional__| __Boolean__. When set to `true`, disables cache and forces fresh computation. +|`ai_context` + +__Optional__. a| Additional context to guide the response. Define the following attributes as needed: + +* `instructions` + +__Array of strings__. Custom user instructions to influence how the AI interprets and processes the query. +* `content` + +__Array of strings__. Additional input such as raw text or CSV-formatted data to enhance context and answer quality. +|===== + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/relevant-questions/' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "metadata_context": { + "data_source_identifiers": [ + "cd252e5c-b552-49a8-821d-3eadaa049cca" + ] + }, + "query": "Net sales of Jackets in west coast", + "limit_relevant_questions": 3 +}' +---- + +=== Example response +If the request is successful, the API returns a set of questions related to the query and metadata context in the `relevant_questions` array. Each object in the `relevant_questions` array contains the following fields: + +* `query` + +A string containing the natural language (NL) sub-question. +* `data_source_identifier` + +GUID of the data source object. +* `data_source_name` + +Name of the associated data source object. + +[source,JSON] +---- +{ + "relevant_questions": [ + { + "query": "What is the trend of sales by type over time?", + "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", + "data_source_name": "(Sample) Retail - Apparel" + }, + { + "query": "Sales by item", + "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", + "data_source_name": "(Sample) Retail - Apparel" + }, + { + "query": "Sales across regions", + "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", + "data_source_name": "(Sample) Retail - Apparel" + } + ] +} +---- + +== Additional resources + +* See also xref:spotter-agent-apis.adoc[Spotter Agent APIs] +* xref:spotter-agent-conversation-apis.adoc[Spotter agent conversation APIs] +* xref:spotter-agent-process-results-apis.adoc[Process Spotter agent conversation results] diff --git a/modules/ROOT/pages/spotter-agent-process-results-apis.adoc b/modules/ROOT/pages/spotter-agent-process-results-apis.adoc new file mode 100644 index 000000000..751e578df --- /dev/null +++ b/modules/ROOT/pages/spotter-agent-process-results-apis.adoc @@ -0,0 +1,46 @@ += Process Spotter agent conversation results +:toc: true +:toclevels: 2 + +:page-title: Process Spotter agent conversation results +:page-pageid: spotter-agent-process-results-apis +:page-description: Export or download the Answer data generated by a Spotter agent conversation session using the Answer report API. + +After the Spotter agent generates an Answer in a conversation session, use the Answer report API to export or download that Answer. + +For information about sending queries to a conversation session, see xref:spotter-agent-conversation-apis.adoc[Spotter agent conversation APIs]. For information about the streaming response format, see xref:spotter-agent-streaming-apis.adoc[Spotter agent streaming APIs]. + +[#process_results] +== Process results generated from a conversation session +To export or download the Answer data generated by the Spotter APIs, use the xref:data-report-v2-api.adoc#exportSpotterData[Answer report] API. + +The `session_id` and `gen_no` values from the `answer` event metadata are required to identify the answer to export. + +NOTE: Requires at least view access to the Answer. + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \ + -H 'Authorization: Bearer {Bearer_token}' \ + -H 'Accept: application/octet-stream' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "session_identifier": "sess-abc-123", + "generation_number": 1, + "file_format": "CSV" +}' +---- +The `file_format` parameter accepts `PDF`, `PNG`, `CSV`, or `XLSX`. + +[NOTE] +==== +Using tokens generated by the Spotter API in a xref:data-report-v2-api.adoc#_search_data_api[Search Data API] request can return invalid column errors, because these tokens may reference formulas or columns not present in the data model. Instead, use the xref:data-report-v2-api.adoc#exportSpotterData[Answer report] API and include the session ID and generation number obtained from the Spotter API in your API request to retrieve the data. +==== + +== Additional resources + +* See also xref:spotter-agent-apis.adoc[Spotter Agent APIs] +* xref:spotter-agent-conversation-apis.adoc[Spotter agent conversation APIs] +* xref:spotter-agent-streaming-apis.adoc[Spotter agent streaming APIs] +* xref:spotter-agent-data-literacy-apis.adoc[Spotter agent data literacy APIs] diff --git a/modules/ROOT/pages/spotter-agent-sharing-apis.adoc b/modules/ROOT/pages/spotter-agent-sharing-apis.adoc new file mode 100644 index 000000000..3b80474b6 --- /dev/null +++ b/modules/ROOT/pages/spotter-agent-sharing-apis.adoc @@ -0,0 +1,155 @@ += Spotter agent conversation sharing APIs +:toc: true +:toclevels: 3 + +:page-title: Spotter agent conversation sharing APIs +:page-pageid: spotter-agent-sharing-apis +:page-description: Use the Spotter agent conversation sharing REST API v2.0 endpoints to share saved Spotter agent conversations with other users or groups. + +// SOURCE: SCAL-306173 (aug.26.mt) +// SOURCE: prism/src/public-apis/nl-to-answer.graphql (master) + +ThoughtSpot provides REST API v2.0 endpoints to share saved Spotter agent conversations with other users or groups. Shared conversations are always `READ_ONLY` — recipients can view conversation messages and associated answers but cannot send new queries or modify the conversation. + +For information about creating and saving a conversation, see xref:spotter-agent-conversation-apis.adoc[Spotter agent conversation APIs] and xref:spotter-agent-conversation-mgmt-apis.adoc[APIs for managing saved conversations]. + +== Supported endpoints + +[width="100%" cols="1"] +|===== +a| `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` [.version-badge.new]#New# + +xref:spotter-agent-sharing-apis.adoc#_share_a_conversation[Shares a saved Spotter conversation] with one or more users or groups. + +__Available on ThoughtSpot Cloud instances from 26.9.0.cl onwards.__ + +a| `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content` [.version-badge.new]#New# + +xref:spotter-agent-sharing-apis.adoc#_get_shared_content[Returns the shared content] of a Spotter conversation, including messages and associated answers. + +__Available on ThoughtSpot Cloud instances from 26.9.0.cl onwards.__ + +a| `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info` [.version-badge.new]#New# + +xref:spotter-agent-sharing-apis.adoc#_get_share_information[Returns sharing metadata] for a Spotter conversation — the list of principals it is shared with. + +__Available on ThoughtSpot Cloud instances from 26.9.0.cl onwards.__ +|===== + +[#_share_a_conversation] +== Share a conversation + +Use `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` to share a saved Spotter conversation with one or more principals. + +=== Path parameters + +[width="100%" cols="2,4"] +[options="header"] +|===== +| Parameter | Description +| `conversation_identifier` | The GUID of the saved Spotter conversation to share. +|===== + +=== Request body parameters + +[width="100%" cols="2,1,4"] +[options="header"] +|===== +| Parameter | Required | Description +| `grant` | No | Array of principal identifiers to grant access. Each entry is a `user_identifier` (username or GUID) or `group_identifier` (group name or GUID). All shared access is `READ_ONLY`. +| `revoke` | No | Array of principal identifiers to revoke access from. +| `refresh_shared_content` | No | Boolean. When `true`, regenerates the shared content snapshot. Default: `false`. +| `notify_on_share` | No | Boolean. When `true`, sends an in-app notification to principals receiving access. Default: `true`. Available from 26.10.0.cl. +|===== + +=== Example request + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "grant": [ + {"user_identifier": "user@example.com"}, + {"group_identifier": "analysts-group"} + ], + "revoke": [], + "refresh_shared_content": false +}' +---- + +[#_get_shared_content] +== Get shared content + +Use `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content` to retrieve the content of a shared Spotter conversation. + +=== Path parameters + +[width="100%" cols="2,4"] +[options="header"] +|===== +| Parameter | Description +| `conversation_identifier` | The GUID of the shared Spotter conversation. +|===== + +=== Response fields + +[width="100%" cols="2,4"] +[options="header"] +|===== +| Field | Description +| `conversation_id` | GUID of the original conversation. +| `shared_conversation_id` | GUID of the shared conversation snapshot. +| `messages` | Array of conversation messages included in the shared snapshot. +| `data_sources` | Array of data source identifiers used in the conversation. +| `code_execution_files` | Array of files generated by code execution steps, if any. +|===== + +=== Example request + +[source,cURL] +---- +curl -X GET \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/json' +---- + +[#_get_share_information] +== Get share information + +Use `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info` to retrieve sharing metadata for a Spotter conversation. + +=== Path parameters + +[width="100%" cols="2,4"] +[options="header"] +|===== +| Parameter | Description +| `conversation_identifier` | The GUID of the Spotter conversation. +|===== + +=== Response fields + +[width="100%" cols="2,4"] +[options="header"] +|===== +| Field | Description +| `is_shared_content_outdated` | Boolean. `true` if the shared content snapshot is stale. Use the share endpoint with `refresh_shared_content: true` to regenerate. +| `principals` | Array of principal objects the conversation is shared with. Each entry includes the principal identifier and their access level (always `READ_ONLY`). +|===== + +=== Example request + +[source,cURL] +---- +curl -X GET \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/json' +---- + +== Additional resources + +* See also xref:spotter-agent-apis.adoc[Spotter Agent APIs] +* xref:spotter-agent-conversation-apis.adoc[Spotter agent conversation APIs] +* xref:spotter-agent-process-results-apis.adoc[Process Spotter agent conversation results] +* xref:spotter-agent-data-literacy-apis.adoc[Spotter agent data literacy APIs] +* xref:spotter-agent-conversation-mgmt-apis.adoc[APIs for managing saved conversations] diff --git a/modules/ROOT/pages/spotter-agent-streaming-apis.adoc b/modules/ROOT/pages/spotter-agent-streaming-apis.adoc new file mode 100644 index 000000000..7c9f6b9b7 --- /dev/null +++ b/modules/ROOT/pages/spotter-agent-streaming-apis.adoc @@ -0,0 +1,664 @@ += Spotter agent streaming API +:toc: true +:toclevels: 3 + +:page-title: Spotter agent streaming APIs +:page-pageid: spotter-agent-streaming-apis +:page-description: Use the Spotter agent streaming REST API to receive real-time Server-Sent Events (SSE) responses for conversational queries sent to the Spotter agent. + +ThoughtSpot's Spotter agent streaming API lets you send natural language queries to an existing conversation session and receive the response as a real-time Server-Sent Events (SSE) stream, instead of waiting for the complete response. + +For information about creating a conversation session and sending queries to it, see xref:spotter-agent-conversation-apis.adoc[Spotter agent conversation APIs]. + +== Send a query to agent and get streaming responses + +To send queries to an ongoing conversation session with Spotter agent and receive streaming responses, use the `/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream` API endpoint. This API endpoint uses the SSE protocol to deliver data incrementally in real time, rather than waiting for the entire response to be generated before sending it to the client. + +The `/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream` API can be used as an integrated tool for real-time streaming of conversational interactions between agents and the ThoughtSpot backend. + +=== Request parameters + +[width="100%" cols="2,4"] +[options='header'] +|===== +|Parameter| Description +|`conversation_identifier` |__String__. Specify the conversation ID received from the xref:spotter-agent-conversation-apis.adoc#_create_a_conversation_session_with_spotter_agent[POST /api/rest/2.0/ai/agent/conversation/create] API call. +|`messages`|_Array of strings_. Include at least one natural language query. For example, `Sales data for Jackets`, `Top performing products in the west coast`. +|===== + +=== Example request + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "conversation_identifier": "h2I_pTGaRQof", + "messages": [ + "Net sales of Jackets" + ] +}' +---- + +=== API response + +If the API request is successful, the response includes a stream of events, each containing a partial or complete message from the AI agent, rather than a single JSON object. + +Each event is a simple text-based message in a specific format, `data: \n\n`; `\n\n` means that each message sent from the server to the client is prefixed with the `data:` keyword, followed by the actual payload (``), and ends with two newline characters (`\n\n`). + +The API uses this format so that the clients can reconstruct the AI-generated response as it streams in, chunk by chunk, and show the responses in real-time. In agentic workflows, the receiving client or agent listens to the SSE stream, parses each event, and assembles the full response for its users. + +==== Example response +If the request is valid, the API returns SSE streams. Each line has the form `data: [{"type": "...", ...}]`, a JSON array of event objects. + +[source,JSON] +---- +data: [{"type":"ack","node_id":"aGxzcFVrtom8"}] + +data: [{"type":"conv_title","title":"Sales 2025 vs 2024","conv_id":"-XIi04l5rrof"}] + +data: [{"type":"notification","group_id":"cDEsAQbSnd3J","metadata":{"type":"thinking","tool_title":"Analyzing Sales Performance: 2025 vs 2024"},"code":"TOOL_CALL_NOTIFICATION"}] + +data: [{"id":"mNAdvy-NK2l6","type":"text-chunk","group_id":"cDEsAQbSnd3J","metadata":{"format":"markdown","type":"thinking"},"content":"\n\nI need to compare sales performance between 2025 and 2024."}] + +data: [{"type":"notification","group_id":"m1MTvttEUa7o","code":"nls_start"}] + +data: [{"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"}] + +data: [{"type":"notification","code":"FINAL_RESPONSE_NOTIFICATION"}] +---- +For the complete response in one payload, use the xref:spotter-agent-conversation-apis.adoc#_send_queries_to_a_conversation_session[`/send` endpoint] instead. + +//// +[source,] +---- +data: [{"type": "ack", "node_id": "BRxCtJ-aGt8l"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": "I"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " understand"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " you're"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " interested"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " in"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " the"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " net"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " sales"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " of"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " Jackets"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": "."}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " I'll"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " retrieve"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " the"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " relevant"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " data"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " for"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " you"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": "."}] + +data: [{"type": "notification", "group_id": "o8dQ9SAWdtrL", "metadata": {"title": "Net sales of Jackets"}, "code": "nls_start"}] + +data: [{"type": "notification", "group_id": "o8dQ9SAWdtrL", "code": "QH", "message": "Fetching Worksheet Data"}] + +data: [{"type": "notification", "group_id": "o8dQ9SAWdtrL", "code": "TML_GEN", "message": "Translating your query with the Reasoning Engine"}] + +data: [{"type": "notification", "group_id": "o8dQ9SAWdtrL", "code": "ANSWER_GEN", "message": "Verifying results with the Trust Layer"}] + +data: [{"id": "r24X7D99SROD", "type": "answer", "group_id": "o8dQ9SAWdtrL", "metadata": {"sage_query": "[sales] [item type] = [item type].'jackets'", "session_id": "b321b404-cbf1-4905-9b0c-b93ad4eedf89", "gen_no": 1, "transaction_id": "6874259d-13b1-478c-83cb-b3ed52628850", "generation_number": 1, "warning_details": null, "ambiguous_phrases": null, "query_intent": null, "assumptions": "You want to see the total sales amount for jackets item type.", "tml_phrases": ["[sales]", "[item type] = [item type].'jackets'"], "cached": false, "sub_queries": null, "title": "Net sales of Jackets", "worksheet_id": "cd252e5c-b552-49a8-821d-3eadaa049cca"}, "title": "Net sales of Jackets"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "The"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " net"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " sales"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " for"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " Jackets"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " have"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " been"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " visual"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "ized"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " for"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " you"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "."}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " This"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " analysis"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " specifically"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " filtered"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " for"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " the"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " item"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " type"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "jackets"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "\""}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " and"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " calculated"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " the"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " total"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " sales"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " amount"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " associated"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " with"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " those"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " products"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ".\n\n"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "**"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "Summary"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " &"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " Insights"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ":"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "**\n"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "-"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " The"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " visualization"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " shows"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " the"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " total"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " net"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " sales"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " for"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " all"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " jacket"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " transactions"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " in"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " your"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " apparel"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " dataset"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ".\n"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "-"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " The"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " calculation"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " uses"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " only"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " sales"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " amounts"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " where"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " the"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " item"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " type"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " is"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " \""}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "J"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "ackets"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ".\"\n"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "-"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " This"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " information"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " is"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " useful"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " for"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " understanding"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " the"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " revenue"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " contribution"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " of"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " jackets"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " within"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " your"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " product"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " mix"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ".\n\n"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "If"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " you'd"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " like"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " to"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " see"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " a"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " breakdown"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " by"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " region"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ","}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " state"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ","}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " time"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " period"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ","}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " or"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " compare"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " jacket"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " sales"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " to"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " other"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " product"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " types"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ","}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " please"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " let"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " me"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " know"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "!"}] +---- +//// + +==== SSE event types +The SSE event types streamed in the API response include: + +* `ack` + +Confirms receipt of the request. For example, the type in the first message `data: [{"type": "ack", "node_id": "BRxCtJ-aGt8l"}]`, which indicates that the server has received the client's request and is acknowledging it. +* `conv_title` + +A conversation title (`title`, `conv_id`). +* `notification` + +Progress or status update (`group_id`, `metadata`, `code`). For example, `TOOL_CALL_NOTIFICATION`, `nls_start`, `FINAL_RESPONSE_NOTIFICATION`. +* `type` + +Type can be `thinking`, `text`. +* `text` + +Complete text block in markdown format. +* `text-chunk` + +Text fragments in incremental streaming, often in markdown (`id`, `group_id`, `metadata` with `format`) +* `content` + +The actual text content sent incrementally. For example, `"I"`, `"understand"`, `"you're"`, `"interested"`, `"in"`, `"the"`, `"net"`, `"sales"`, and so on. +* `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` and more) +* `error` + +In case of failures. +* `*-interrupt` + +If the generation was stopped mid-stream. +* `group_id` + +Groups related chunks together. + +For more information and examples, see xref:spotter-agent-streaming-apis.adoc#_sse_event_payload_reference[SSE event payload reference]. + +=== Thinking versus output events +Spotter responses have two phases: + +* A *thinking phase*, where the AI reasons through the query and calls internal tools, followed by an *output phase* containing the final response delivered to the user. + + +Events in the thinking phase carry `"metadata": { "type": "thinking" }`. All other events are final output. + +Every event includes a `group_id`. Events sharing the same `group_id` belong together. During the thinking phase, each tool call gets its own `group_id`. A `FINAL_RESPONSE_NOTIFICATION` notification marks the boundary between the thinking and output phases. + +[listing] +---- +THINKING PHASE +─────────────────────────────────────────────────────────── +ack + +┌─ group_id: g1 ── Tool Call 1 ("Searching data") ─────────┐ +│ notification (thinking, TOOL_CALL_NOTIFICATION) │ +│ text-chunk (thinking) │ +│ answer (thinking) │ +└──────────────────────────────────────────────────────────┘ + +┌─ group_id: g2 ── Tool Call 2 ("Running code") ───────────┐ +│ notification (thinking, TOOL_CALL_NOTIFICATION) │ +│ text-chunk (thinking) │ +│ text-chunk (thinking) │ +└──────────────────────────────────────────────────────────┘ + +notification (FINAL_RESPONSE_NOTIFICATION) ←── boundary +──────────────────────────────────────────────────────────── + +OUTPUT PHASE +──────────────────────────────────────────────────────────── +┌─ group_id: g3 ────────────────────────────────────────────┐ +│ text "Here are the results:" │ +│ answer (final visualization) │ +└───────────────────────────────────────────────────────────┘ +[stream closes] +---- + +==== Notification codes reference + +[width="100%" cols="2,4"] +[options='header'] +|===== +|Code| When it appears +|`QH`|Query handling started +|`TML_GEN` / `TML_GEN_RETRY`|Generating or retrying TML +|`ANSWER_GEN`|Generating an answer +|`IDENTIFYING_ATTRIBUTES`|Identifying data attributes +|`PERFORMING_CHANGE_ANALYSIS`|Running change analysis +|`PERFORMING_FORECASTING_ANALYSIS`|Running forecasting +|`SUMMARIZING_RESULTS`|Summarizing results +|`TOOL_CALL_NOTIFICATION`|Tool invocation (during thinking phase) +|`FINAL_RESPONSE_NOTIFICATION`|Marks the transition from thinking to output +|`search_datasets_start` / `search_datasets_end`|Data source discovery in progress or complete +|`approval_required`|An external tool requires user permission before proceeding +|===== + +=== SSE event payload reference + +==== ack + +[source,JSON] +---- +data: { + "type": "ack", + "group_id": "a1b2c3", + "id": "evt-001", + "node_id": "resp-node-abc" +} +---- + +==== notification (thinking — tool call) + +[source,JSON] +---- +data: { + "type": "notification", + "group_id": "g1", + "id": "evt-002", + "code": "TOOL_CALL_NOTIFICATION", + "message": "Searching for relevant data", + "metadata": { + "type": "thinking", + "tool_title": "Searching sales data", + "tool_code": "RUNNING_CODE_EXECUTION", + "tool_name": "code_interpreter" + } +} +---- + +==== notification (thinking - external tool with MCP integration) + +[source,JSON] +---- +data: { + "type": "notification", + "group_id": "g2", + "id": "evt-003", + "code": "TOOL_CALL_NOTIFICATION", + "message": "Querying Salesforce", + "metadata": { + "type": "thinking", + "tool_title": "Salesforce: Get Opportunities", + "tool_name": "get_opportunities", + "integration_id": "int-sf-123", + "integration_name": "Salesforce" + } +} +---- + +==== notification (approval required) +Sent when an external MCP tool requires explicit user permission before proceeding. Your application should prompt the user to approve or deny the action before continuing. + +[source,JSON] +---- +data: { + "type": "notification", + "group_id": "g2", + "id": "evt-005", + "code": "approval_required", + "metadata": { + "request_id": "perm-req-789", + "integration_id": "int-sf-123", + "integration_name": "Salesforce", + "tool_name": "get_opportunities", + "annotated_title": "Access Salesforce Opportunities" + } +} +---- + +==== notification (FINAL_RESPONSE_NOTIFICATION) + +[source,JSON] +---- +data: { + "type": "notification", + "group_id": "g1", + "id": "evt-004", + "code": "FINAL_RESPONSE_NOTIFICATION", + "message": "" +} +---- + +==== text + +[source,JSON] +---- +data: { + "type": "text", + "group_id": "g3", + "id": "evt-007", + "content": "Here is the total revenue breakdown by region for Q4 2025:\n\n- **North America:** $4.2M\n- **EMEA:** $2.8M\n- **APAC:** $1.5M" +} +---- + +==== text-chunk +Multiple chunks sharing the same `id` should be appended together to reconstruct the full text item. + +[source,JSON] +---- +data: { "type": "text-chunk", "group_id": "g3", "id": "evt-009", "content": "Based on the analysis, " } +data: { "type": "text-chunk", "group_id": "g3", "id": "evt-009", "content": "revenue grew 12% quarter-over-quarter." } +---- + +==== answer +When an `answer` event is received, the `session_id` and `gen_no` fields are returned. You can export the visualization data using the Export Answer Report API to process the results. This allows users to download the answer as a PDF, PNG, CSV, or XLSX file. + +[source,JSON] +---- +data: { + "type": "answer", + "group_id": "g3", + "id": "evt-010", + "title": "Revenue by Region Q4 2025", + "metadata": { + "session_id": "sess-abc-123", + "gen_no": 1, + "transaction_id": "txn-456", + "worksheet_id": "ws-def-789", + "cached": false, + "is_hidden": false + } +} +---- + +==== search_datasets +Emitted as a start/end pair during Auto mode data source discovery. + + +[source,JSON] +---- +data: { "type": "search_datasets", "group_id": "g0", "id": "evt-012", "code": "search_datasets_start", "metadata": {} } + +data: { + "type": "search_datasets", + "group_id": "g0", + "id": "evt-013", + "code": "search_datasets_end", + "metadata": { + "data_sources": [ + { "worksheet_id": "ws-1", "worksheet_name": "Sales Data", "confidence": "high", "reasoning": "Contains revenue columns" }, + { "worksheet_id": "ws-2", "worksheet_name": "Marketing Data", "confidence": "low", "reasoning": "No revenue columns" } + ], + "auto_selected": { "worksheet_id": "ws-1", "worksheet_name": "Sales Data", "confidence": "high", "reasoning": "Best match" } + } +} +---- +==== file + +[source,JSON] +---- +data: { + "type": "file", + "group_id": "g3", + "id": "evt-014", + "files": [ + { "ts_file_id": "file-abc-001", "display_name": "quarterly_report.csv", "file_type": "csv", "created_at": "2025-11-15T10:30:00Z" }, + { "ts_file_id": "file-abc-002", "display_name": "chart.png", "file_type": "png", "created_at": "2025-11-15T10:30:01Z" } + ], + "metadata": { "conv_id": "conv-123" } +} +---- +==== conv_title + +[source,JSON] +---- +data: { + "type": "conv_title", + "group_id": "g0", + "id": "evt-015", + "title": "Revenue Analysis Q4 2025", + "conv_id": "conv-123" +} +---- + +==== error + +[source,JSON] +---- +data: { + "type": "error", + "group_id": "g3", + "id": "evt-016", + "code": "RATE_LIMIT_EXCEEDED", + "message": "Too many requests", + "display_message": "You've exceeded the rate limit. Please try again in a few minutes." +} +---- +==== agent-interrupt + +[source,JSON] +---- +Sent when generation is stopped mid-stream. +data: { + "type": "notification", + "group_id": "g3", + "id": "evt-017", + "code": "agent-interrupt", + "message": "Generation stopped" +} +---- + +== Additional resources + +* See also xref:spotter-agent-apis.adoc[Spotter Agent APIs] +* xref:spotter-agent-conversation-apis.adoc[Spotter agent conversation APIs] +* xref:spotter-agent-process-results-apis.adoc[Process Spotter agent conversation results] +* xref:spotter-agent-sharing-apis.adoc[Spotter agent conversation sharing APIs] diff --git a/modules/ROOT/pages/spotter-apis.adoc b/modules/ROOT/pages/spotter-apis.adoc index a7ebfc290..4d988b4a0 100644 --- a/modules/ROOT/pages/spotter-apis.adoc +++ b/modules/ROOT/pages/spotter-apis.adoc @@ -25,6 +25,11 @@ For information about supported API operations, see the following pages: * xref:spotter-classic-apis.adoc[APIs for Spotter classic workflow] * xref:spotter-agent-apis.adoc[APIs for Spotter agent workflows] +* xref:spotter-agent-conversation-apis.adoc[APIs for Spotter agent conversations] +* xref:spotter-agent-streaming-apis.adoc[APIs for Spotter agent streaming responses] +* xref:spotter-agent-process-results-apis.adoc[APIs for processing Spotter agent conversation results] +* xref:spotter-agent-data-literacy-apis.adoc[APIs for Spotter agent data literacy] +* xref:spotter-agent-sharing-apis.adoc[APIs for sharing Spotter conversations] * xref:spotter-agent-conversation-mgmt-apis.adoc[APIs for Spotter conversation management] * xref:spotter-nl-instructions.adoc[APIs for Spotter coaching and NL instructions] * xref:spotter-agent-instructions.adoc[APIs for Spotter agent instructions] diff --git a/modules/ROOT/pages/whats-new.adoc b/modules/ROOT/pages/whats-new.adoc index 255551f87..f8004e1c8 100644 --- a/modules/ROOT/pages/whats-new.adoc +++ b/modules/ROOT/pages/whats-new.adoc @@ -93,7 +93,7 @@ ThoughtSpot introduces three new REST API v2.0 endpoints to share Spotter agent * `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content` -- Retrieve the shared messages and answers in a conversation. * `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info` -- Retrieve the list of principals a conversation is shared with and their access levels. -For more information, see xref:spotter-agent-apis.adoc#_sharing_spotter_conversations[Sharing Spotter conversations]. +For more information, see xref:spotter-agent-sharing-apis.adoc[Sharing Spotter conversations]. --- @@ -366,7 +366,7 @@ This release introduces the following enhancements for Spotter AI workflows and Spotter now includes data literacy skills that help users understand the underlying data model. Users can ask Spotter to explain available data sources, fields, and relationships in plain language within a conversation session. * Spotter AI APIs: + //** New REST API endpoints to configure and retrieve persistent behavioral xref:spotter-agent-instructions.adoc[instructions for the Spotter agent]. - New API endpoint xref:spotter-agent-apis.adoc#_stop_an_in_progress_agent_response[stop and cancel a long-running Spotter response]. + New API endpoint xref:spotter-agent-conversation-apis.adoc#_stop_an_in_progress_agent_response[stop and cancel a long-running Spotter response]. --- From ddd72815082038587f633000546e593a56857abb Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Tue, 25 Aug 2026 15:48:28 +0530 Subject: [PATCH 081/154] user-mgmt-page-formatting-fix --- modules/ROOT/pages/api-user-management.adoc | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/modules/ROOT/pages/api-user-management.adoc b/modules/ROOT/pages/api-user-management.adoc index 234232267..5bbdd9347 100644 --- a/modules/ROOT/pages/api-user-management.adoc +++ b/modules/ROOT/pages/api-user-management.adoc @@ -2,7 +2,7 @@ :toc: true :toclevels: 3 -:page-title: Users and group privileges +:page-title: Users and groups :page-pageid: api-user-management :page-description: You can manage users and user groups using REST APIs @@ -101,12 +101,12 @@ To activate an `INACTIVE` user account, use one of these API endpoints: //// There is also a *Unsuspend user* button on the *Users* dashboard of the *Admin* page. This button is available for all users in the SUSPENDED state. -The user’s state will transition from SUSPENDED to ACTIVE or PENDING on clicking *Unsuspend user*. +The user's state will transition from SUSPENDED to ACTIVE or PENDING on clicking *Unsuspend user*. image::./images/unsuspend.png[Unsuspended state] //// -=== User migration to IAMv2 +== User migration to IAMv2 ThoughtSpot is gradually migrating its users to link:https://docs.thoughtspot.com/cloud/latest/okta-iam[Identity and Access Management v2 (IAMv2), window=_blank] to provide a more secure login and authentication experience through internal authentication with Okta. The following are some of the important points to note with this upgrade: @@ -148,12 +148,10 @@ For SSO users, ThoughtSpot derives email address and display name directly from ThoughtSpot automatically reflects the new values when the user next logs in through SSO. Do not use the REST API or the Admin UI to update the email address or display name of an SSO user. - For users who authenticate directly with ThoughtSpot (not through an external IdP), you can update username, email address, and display name using the REST API or Admin UI. No IdP coordination is required for local users. ==== - //// The IAMv2 users also have an additional user state, `SUSPENDED`. With this, the IAMv2 users do not require a password reset when transitioning between states such as `ACTIVE`, `EXPIRED`, or `INACTIVE`. It also supports seamless migration from IAMv1 to IAMv2 for embedded users. @@ -217,7 +215,7 @@ ThoughtSpot also has a default group called `All`. When you create new users in == Roles If Role-Based Access Control (RBAC) is enabled on your instance, administrators can define role privileges and assign them to users via groups. Roles are always scoped to an Org; a role created in one Org cannot be assigned in another. -=== Assign roles to groups via REST API +=== Role assignment to groups via REST API When creating or updating a group using the REST API v2 endpoints, use the `role_identifiers` parameter to assign one or more roles to the group. The parameter accepts an array of role GUIDs or role names. For more information, see: * link:{{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fgroups%2Fcreate-user-group[`POST /api/rest/2.0/groups/create`]: include `role_identifiers` in the request body. From 3ffe396917c33355e9d40d29b4b4edc16922c24a Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Tue, 25 Aug 2026 16:16:14 +0530 Subject: [PATCH 082/154] v2 ref removal, v3 experience update, and formatting fixes --- modules/ROOT/pages/full-app-customize.adoc | 4 ++-- modules/ROOT/pages/set-default-page.adoc | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/modules/ROOT/pages/full-app-customize.adoc b/modules/ROOT/pages/full-app-customize.adoc index c11ee2f23..0b88e834b 100644 --- a/modules/ROOT/pages/full-app-customize.adoc +++ b/modules/ROOT/pages/full-app-customize.adoc @@ -133,7 +133,7 @@ const embed = new AppEmbed("#embed", { //... other embed view configuration attributes }); ---- - +//// ==== Post upgrade checks After you enable the V3 experience: @@ -141,11 +141,11 @@ After you enable the V3 experience: * Verify that all the customization settings are applied correctly. * If you have set up custom routes for navigation within your embedded app, verify navigation workflows and check for breaking changes. + [.bordered] [.widthAuto] image::./images/homepage.png[New home page] -//// === UI customization options and resulting experience The following table summarizes the resulting UI experience for different configuration combinations: diff --git a/modules/ROOT/pages/set-default-page.adoc b/modules/ROOT/pages/set-default-page.adoc index abb62ade6..ee51073cf 100644 --- a/modules/ROOT/pages/set-default-page.adoc +++ b/modules/ROOT/pages/set-default-page.adoc @@ -90,9 +90,9 @@ The `AppEmbed` object includes a `navigateToPage()` method that switches the cur navigateToPage(path: string | number, noReload?: boolean): void ---- -[cols="1,1,3"] +[cols="1,3"] |==== -| Parameter | Description +|Parameter | Description | `path` |__String__. The page to navigate to. Accepts the same string values as the `pageId` or `path` attributes (for example, `'answers'`, `'pinboard/'`, or a `Page` enum value). + From 51abff9e4b63f233cfdb3556a8f7947f56f0138b Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Tue, 25 Aug 2026 22:55:28 +0530 Subject: [PATCH 083/154] SCAL-334699 fix --- modules/ROOT/pages/rest-api-v2-reference.adoc | 4 +- modules/ROOT/pages/rest-apiv2-changelog.adoc | 6 +-- modules/ROOT/pages/spotter-apis.adoc | 2 +- .../ROOT/pages/spotter-nl-instructions.adoc | 41 +++++++++---------- .../ROOT/pages/whats-new-prev-history.adoc | 4 +- modules/ROOT/pages/whats-new.adoc | 6 +-- 6 files changed, 30 insertions(+), 33 deletions(-) diff --git a/modules/ROOT/pages/rest-api-v2-reference.adoc b/modules/ROOT/pages/rest-api-v2-reference.adoc index b55eed3cf..799c77ed2 100644 --- a/modules/ROOT/pages/rest-api-v2-reference.adoc +++ b/modules/ROOT/pages/rest-api-v2-reference.adoc @@ -67,12 +67,12 @@ Stops an in-progress Spotter agent response for a given conversation session. ThoughtSpot Software: __Not available__ a| +++Try it out+++ a|`POST /api/rest/2.0/ai/instructions/set` + -Sets NL instructions on a data model. +Sets data model instructions. |ThoughtSpot Cloud: __10.15.0.cl or later__ + ThoughtSpot Software: __Not available__ a| +++Try it out+++ a|`POST /api/rest/2.0/ai/instructions/get` + -Retrieves NL instructions from a data model. +Retrieves data model instructions. |ThoughtSpot Cloud: __10.15.0.cl or later__ + ThoughtSpot Software: __Not available__ a| +++Try it out+++ diff --git a/modules/ROOT/pages/rest-apiv2-changelog.adoc b/modules/ROOT/pages/rest-apiv2-changelog.adoc index 7b274d0e5..6626f8bb8 100644 --- a/modules/ROOT/pages/rest-apiv2-changelog.adoc +++ b/modules/ROOT/pages/rest-apiv2-changelog.adoc @@ -394,7 +394,7 @@ Administrators and users with edit access to data models can now use `/api/rest/ To fetch object privileges for a data model, user, or group, use the `/api/rest/2.0/security/metadata/fetch-object-privileges` API endpoint. -For more information, see xref:spotter-nl-instructions.adoc#_spotter_data_model_instructions_access[Spotter data model instructions access]. +For more information, see xref:spotter-nl-instructions.adoc#_allowing_access_to_spotter_data_model_instructions[Allowing access to Spotter data model instructions]. === User API enhancements @@ -471,9 +471,9 @@ The `include_variable_values` parameter in the API request allows including vari This release introduces the following Spotter APIs: * `POST /api/rest/2.0/ai/instructions/set` + -Allows configuring natural language (NL) instructions on a data model to define how Spotter interprets queries, handles data nuances, and improves responses. +Allows configuring data model instructions to define how Spotter interprets queries, handles data nuances, and improves responses. * `POST /api/rest/2.0/ai/instructions/get` + -Gets NL instructions that are currently assigned to a model. +Gets data model instructions that are currently assigned to a model. * `POST /api/rest/2.0/ai/data-source-suggestions` + Retrieves a list of recommended data sources based on the specified query string. diff --git a/modules/ROOT/pages/spotter-apis.adoc b/modules/ROOT/pages/spotter-apis.adoc index a7ebfc290..a5759e1b9 100644 --- a/modules/ROOT/pages/spotter-apis.adoc +++ b/modules/ROOT/pages/spotter-apis.adoc @@ -26,7 +26,7 @@ For information about supported API operations, see the following pages: * xref:spotter-classic-apis.adoc[APIs for Spotter classic workflow] * xref:spotter-agent-apis.adoc[APIs for Spotter agent workflows] * xref:spotter-agent-conversation-mgmt-apis.adoc[APIs for Spotter conversation management] -* xref:spotter-nl-instructions.adoc[APIs for Spotter coaching and NL instructions] +* xref:spotter-nl-instructions.adoc[APIs for Spotter coaching and data model instructions] * xref:spotter-agent-instructions.adoc[APIs for Spotter agent instructions] == Locale settings for API requests diff --git a/modules/ROOT/pages/spotter-nl-instructions.adoc b/modules/ROOT/pages/spotter-nl-instructions.adoc index 8062ca369..39337d54f 100644 --- a/modules/ROOT/pages/spotter-nl-instructions.adoc +++ b/modules/ROOT/pages/spotter-nl-instructions.adoc @@ -6,16 +6,16 @@ :page-pageid: spotter-nl-instructions :page-description: Use the data model instructions APIs to set and retrieve natural language instructions at the data model level to guide how Spotter interprets and answers user queries. -Administrators and data owners can guide and refine how Spotter interprets and answers user questions. The natural language (NL) instructions API allows you to set instructions at the data model level. The API provides business context and preferred interpretations for specific queries or terminology, but it does not train or change the underlying LLM. +Administrators and data owners can guide and refine how Spotter interprets and answers user questions. The data model instructions API allows you to set instructions at the data model level. The API provides business context and preferred interpretations for specific queries or terminology, but it doesn't train or change the underlying LLM. -== Set NL instructions +== Setting data model instructions To define how Spotter interprets queries, applies filters, selects columns, handles data nuances, and presents answers using the data from a specific model, you can set global rules in natural language format. Setting data model instructions helps Spotter generate precise and consistent responses for user queries. To set instructions for a Model, send a `POST` request to the `/api/rest/2.0/ai/instructions/set` API endpoint. [NOTE] ==== -To set NL instructions, you need `CAN_MANAGE_SPOTTER` (**Can manage Spotter**) privilege and either edit access or `SPOTTER_COACHING_PRIVILEGE` permission on the data model. Ensure that your bearer token is scoped to the Org where the data model resides. +To set data model instructions, you need `CAN_MANAGE_SPOTTER` (**Can manage Spotter**) privilege and either edit access or `SPOTTER_COACHING_PRIVILEGE` permission on the data model. Ensure that your bearer token is scoped to the Org where the data model resides. ==== === Request parameters @@ -23,13 +23,13 @@ To set NL instructions, you need `CAN_MANAGE_SPOTTER` (**Can manage Spotter**) p [width="100%" cols="2,4"] [options='header'] |===== -|Form parameter| Description +|Form parameter|Description |`data_source_identifier`|__String__. ID of the Model. -|`nl_instructions_info` a|Instructions in the natural language format. +|`nl_instructions_info` a|Instructions in natural language format. * `instructions` + -_Array of strings_. Include the rules that you want to add in the `instructions` array. Ensure that the instructions do not exceed 3000 characters. -* `scope` +_Array of strings_. Include the rules that you want to add in the `instructions` array. Ensure that the instructions don't exceed 3000 characters. +* `scope` + Sets the scope for the rules. By default, the rules are applied globally for all Spotter users who can access the Model specified in the request. |===== @@ -49,7 +49,7 @@ curl -X POST \ "nl_instructions_info": [ { "instructions": [ - "When I ask for last month, use ‘last 30 days’ as a filter.", + "When I ask for last month, use 'last 30 days' as a filter.", "Exclude orders where order_status = '\''CANCELLED-USER'\'' when calculating total revenue" ], "scope": "GLOBAL" @@ -61,9 +61,9 @@ curl -X POST \ === Example response If the API request is successful, ThoughtSpot returns the `{"success":true}` response. -== Retrieve NL instructions assigned to a Model +== Retrieving data model instructions assigned to a Model -To view the NL instructions assigned for a Model, send a `POST` request to the `/api/rest/2.0/ai/instructions/get` API endpoint. +To view the data model instructions assigned for a Model, send a `POST` request to the `/api/rest/2.0/ai/instructions/get` API endpoint. Only Spotter users with view access to the data model can retrieve instructions via API requests. @@ -72,12 +72,12 @@ Only Spotter users with view access to the data model can retrieve instructions [width="100%" cols="2,4"] [options='header'] |===== -|Form parameter| Description +|Form parameter|Description |`data_source_identifier`|__String__. ID of the Model from which you want to fetch instructions. |===== === Example request -The following example shows the request body for retrieving NL instructions configured on a Model: +The following example shows the request body for retrieving data model instructions configured on a Model: [source,cURL] ---- @@ -100,7 +100,7 @@ If the instructions are configured on the Model specified in the API request, Th "nl_instructions_info": [ { "instructions": [ - "When I ask for last month, use ‘last 30 days’ as a filter.", + "When I ask for last month, use 'last 30 days' as a filter.", "Exclude orders where order_status = 'CANCELLED-USER' when calculating total revenue" ], "scope": "GLOBAL" @@ -109,12 +109,11 @@ If the instructions are configured on the Model specified in the API request, Th } ---- +== Allowing access to Spotter data model instructions -== Spotter data model instructions access +ThoughtSpot supports publishing data model instructions to other Orgs. Changes to data model instructions in the primary Org are synchronized with the data models published in secondary Orgs. -ThoughtSpot supports publishing data model instructions to other Orgs. Data model instruction changes from the primary Org are synchronized with the data models published in secondary Orgs. - -=== Assign the data model instructions privilege +=== Assigning privilege To allow users and groups to access data model instructions, assign the `SPOTTER_COACHING_PRIVILEGE` via `POST` request to the `/api/rest/2.0/security/metadata/manage-object-privilege` API endpoint. @@ -146,14 +145,12 @@ curl -X POST \ If the request is successful, the API returns the 204 response code. +=== Retrieving object privilege information for users and groups -=== Get a list of users or groups with the data model instructions privilege - -To get a list of users and groups with the data model instructions privilege (`SPOTTER_COACHING_PRIVILEGE`) for a specific data model or all data models, send a `POST` request to the `/api/rest/2.0/security/metadata/fetch-object-privileges` API endpoint. +To get a list of users or groups with the data model instructions privilege (`SPOTTER_COACHING_PRIVILEGE`) for a specific data model or all data models, send a `POST` request to the `/api/rest/2.0/security/metadata/fetch-object-privileges` API endpoint. In the API request, specify the user or the group for which you want to retrieve the object privilege details. - [source,cURL] ---- curl -X POST \ @@ -210,4 +207,4 @@ If the request is successful, ThoughtSpot returns the object privilege details i == Additional resources * Visit the +++REST API v2.0 Playground+++ to view the API endpoints and verify the request and response workflows. -* For information about MCP tools, see xref:mcp-integration.adoc[MCP server integration]. +* For information about the MCP tools, see xref:mcp-integration.adoc[MCP server integration]. diff --git a/modules/ROOT/pages/whats-new-prev-history.adoc b/modules/ROOT/pages/whats-new-prev-history.adoc index dfb3d083f..e705be462 100644 --- a/modules/ROOT/pages/whats-new-prev-history.adoc +++ b/modules/ROOT/pages/whats-new-prev-history.adoc @@ -43,8 +43,8 @@ For more information, see xref:abac_rls-variables.adoc[ABAC via RLS with variabl ThoughtSpot introduces new REST APIs for the following Spotter workflows: //* To get data source suggestions based on a user's query * To send queries to a conversation session with the Spotter agent -* To set natural language (NL) instructions on a model to coach the Spotter system -* To fetch NL instructions configured on a model +* To set data model instructions on a model to coach the Spotter system +* To fetch data model instructions configured on a model For more information, see xref:spotter-apis.adoc[Spotter APIs]. ==== diff --git a/modules/ROOT/pages/whats-new.adoc b/modules/ROOT/pages/whats-new.adoc index 56a89557d..1900d4119 100644 --- a/modules/ROOT/pages/whats-new.adoc +++ b/modules/ROOT/pages/whats-new.adoc @@ -572,7 +572,7 @@ Administrators and users with edit access to data models can programmatically co Users and groups with `SPOTTER_COACHING_PRIVILEGE` can import and export coaching TML on data models in the source and destination Orgs where the model is published, and can also share these objects with other users and groups. -For more information, see xref:spotter-nl-instructions.adoc#_spotter_data_model_instructions_access[Spotter data model instructions access]. +For more information, see xref:spotter-nl-instructions.adoc#_allowing_access_to_spotter_data_model_instructions[Allowing access to Spotter data model instructions]. --- @@ -727,8 +727,8 @@ For more information, see xref:abac_rls-variables.adoc[ABAC via RLS with variabl ThoughtSpot introduces new REST APIs for the following Spotter workflows: * To send queries to a conversation session with the Spotter agent -* To set natural language (NL) instructions on a model to coach the Spotter system -* To fetch NL instructions configured on a model +* To set data model instructions on a model to coach the Spotter system +* To fetch data model instructions configured on a model For more information, see xref:spotter-apis.adoc[Spotter APIs]. From afd20b085067c9506c27da0026bb880eb6fa056e Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Thu, 27 Aug 2026 16:03:44 +0530 Subject: [PATCH 084/154] minor fix to tutorials summary --- .../build-embed-app-with-spottercode-summary.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/tutorials/pages/spottercode-embed/build-embed-app-with-spottercode-summary.adoc b/modules/tutorials/pages/spottercode-embed/build-embed-app-with-spottercode-summary.adoc index ae0a60fc3..4384be0ee 100644 --- a/modules/tutorials/pages/spottercode-embed/build-embed-app-with-spottercode-summary.adoc +++ b/modules/tutorials/pages/spottercode-embed/build-embed-app-with-spottercode-summary.adoc @@ -18,8 +18,8 @@ Every task follows the same loop: == Next steps * xref:spottercode.adoc[SpotterCode reference] -* xref:embed-spotter.adoc[Embed Spotter]: full reference -* xref:embed-pinboard.adoc[Embed a Liveboard]: full reference +* xref:embed-spotter.adoc[Embed Spotter] +* xref:embed-pinboard.adoc[Embed a Liveboard] * xref:embed-authentication.adoc[Authentication options] * xref:build-data-driven-app-with-tse-intro.adoc[Build a data-driven app with ThoughtSpot Embedded] * link:https://github.com/thoughtspot/developer-examples[Developer examples on GitHub, window=_blank] From 7a7de4a7b02a91ed480837a6f75c932817930079 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Thu, 27 Aug 2026 23:47:27 +0530 Subject: [PATCH 085/154] tutorial typo fix --- modules/ROOT/pages/common/nav-in-product-help.adoc | 4 ++-- modules/ROOT/pages/common/nav-tutorials.adoc | 2 +- modules/ROOT/pages/common/nav.adoc | 4 ++-- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/modules/ROOT/pages/common/nav-in-product-help.adoc b/modules/ROOT/pages/common/nav-in-product-help.adoc index 51fa57b74..90796e4bd 100644 --- a/modules/ROOT/pages/common/nav-in-product-help.adoc +++ b/modules/ROOT/pages/common/nav-in-product-help.adoc @@ -270,7 +270,7 @@ SpotterCode [.sidebar-title] Tutorials -* link:{{navprefix}}/tutorials/tutorials-overview[Embedding tutorials] +* link:{{navprefix}}/tutorials/tutorials-overview[Embedding tutorial] ** link:{{navprefix}}/tutorials/tse-fundamentals/intro[Embedding Fundamentals] *** link:{{navprefix}}/tutorials/tse-fundamentals/lesson-01[01 - Overview] *** link:{{navprefix}}/tutorials/tse-fundamentals/lesson-02[02 - Set up for course] @@ -291,7 +291,7 @@ Tutorials *** link:{{navprefix}}/tutorials/react-components/lesson-04[04 - Event handling] ** link:{{navprefix}}/tutorials/spotter/integrate-into-chatbot[Integrate Spotter into your Chatbot] -* link:{{navprefix}}/tutorials/rest-api/intro[REST API Tutorials] +* link:{{navprefix}}/tutorials/rest-api/intro[REST API tutorial] ** link:{{navprefix}}/tutorials/rest-api/lesson-01[01 - REST API overview] ** link:{{navprefix}}/tutorials/rest-api/lesson-02[02 - Simple Python implementation] ** link:{{navprefix}}/tutorials/rest-api/lesson-03[03 - Complex REST API workflows] diff --git a/modules/ROOT/pages/common/nav-tutorials.adoc b/modules/ROOT/pages/common/nav-tutorials.adoc index 5ebf5d5b7..df23e48da 100644 --- a/modules/ROOT/pages/common/nav-tutorials.adoc +++ b/modules/ROOT/pages/common/nav-tutorials.adoc @@ -32,7 +32,7 @@ UI elements and style customization * link:{{navprefix}}/tutorials/style-customization/step-06[Conclusion] [.sidebar-title] -REST API tutorials +REST API tutorial ** link:{{navprefix}}/tutorials/rest-api/intro[Introduction] ** link:{{navprefix}}/tutorials/rest-api/lesson-01[REST API overview] diff --git a/modules/ROOT/pages/common/nav.adoc b/modules/ROOT/pages/common/nav.adoc index 817197cc7..071a559eb 100644 --- a/modules/ROOT/pages/common/nav.adoc +++ b/modules/ROOT/pages/common/nav.adoc @@ -81,8 +81,8 @@ Deployment guides [.sidebar-title] Tutorials -* link:{{navprefix}}/tutorials/tutorials-overview[Embedding tutorials] -* link:{{navprefix}}/tutorials/rest-api/intro[REST API Tutorials] +* link:{{navprefix}}/tutorials/tutorials-overview[Embedding tutorial] +* link:{{navprefix}}/tutorials/rest-api/intro[REST API tutorial] From 949ef47b7c134a519be0e0db9c4818a81876d3ae Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Fri, 28 Aug 2026 00:00:51 +0530 Subject: [PATCH 086/154] rest api tutorial title update --- modules/ROOT/pages/common/nav-rest-api.adoc | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/modules/ROOT/pages/common/nav-rest-api.adoc b/modules/ROOT/pages/common/nav-rest-api.adoc index 88e4749eb..146aed685 100644 --- a/modules/ROOT/pages/common/nav-rest-api.adoc +++ b/modules/ROOT/pages/common/nav-rest-api.adoc @@ -50,9 +50,10 @@ REST API SDK [.sidebar-title] -REST API Tutorials +REST API tutorial + +* link:{{navprefix}}/tutorials/rest-api/intro[REST API tutorial] -* link:{{navprefix}}/tutorials/rest-api/intro[REST API Tutorials] //// * link:{{navprefix}}/tutorials/rest-api/lesson-01[01 - REST API overview] From 5c898b74a347ef3f96adc6b61fc9a6cddba0db4b Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Fri, 28 Aug 2026 19:50:05 +0530 Subject: [PATCH 087/154] version updates --- src/configs/doc-configs.js | 45 ++++---------------------------------- 1 file changed, 4 insertions(+), 41 deletions(-) diff --git a/src/configs/doc-configs.js b/src/configs/doc-configs.js index 7c28430ca..6c2ebe53b 100644 --- a/src/configs/doc-configs.js +++ b/src/configs/doc-configs.js @@ -22,8 +22,8 @@ module.exports = { // 'https://developers.thoughtspot.com/docs/26.3.0.cl?pageid=whats-new' // - GA: ' /docs/whats-new' //linkHref: '/docs/whats-new', - linkHref: '/docs/26.8.0.cl?pageid=whats-new', - linkText: 'Version 26.8.0.cl', + linkHref: '/docs/26.9.0.cl?pageid=whats-new', + linkText: 'Version 26.9.0.cl', openInNewTab: true, }, TYPE_DOC_PREFIX: 'typedoc', @@ -48,48 +48,11 @@ module.exports = { }, VERSION_DROPDOWN: [ { - label: '26.8.0.cl', + label: '26.9.0.cl', link: ' ', subLabel: 'Cloud (Latest)', - iframeUrl: 'https://developer-docs-26-8-0-cl.vercel.app/docs/', + iframeUrl: 'https://developer-docs-26-9-0-cl.vercel.app/docs/', }, - { - label: '26.7.0.cl', - link: '26.7.0.cl', - subLabel: 'Cloud', - iframeUrl: 'https://developer-docs-26-7-0-cl.vercel.app/docs/', - }, - { - label: '26.6.0.cl', - link: '26.6.0.cl', - subLabel: 'Cloud', - iframeUrl: 'https://developer-docs-26-6-0-cl.vercel.app/docs/', - }, - { - label: '26.5.0.cl', - link: '26.5.0.cl', - subLabel: 'Cloud', - iframeUrl: 'https://developer-docs-26-5-0-cl.vercel.app/docs/', - }, - { - label: '26.3.0.sw', - link: '26.3.0.sw', - subLabel: 'Software (Latest)', - iframeUrl: 'https://visual-embed-sdk-26-3.vercel.app/docs/', - }, - - { - label: '10.10.0.sw', - link: '10.10.0.sw', - subLabel: 'Software', - iframeUrl: 'https://visual-embed-sdk-10-10.vercel.app/docs/', - }, - { - label: '10.1.0.sw', - link: '10.1.0.sw', - subLabel: 'Software', - iframeUrl: 'https://visual-embed-sdk-10-1.vercel.app/docs/', - }, ], CUSTOM_PAGE_ID: { API_PLAYGROUND: 'restV2-playground', From d4de62ffec25531c6277f5638b50225c2fd03ea9 Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Mon, 31 Aug 2026 13:14:03 +0530 Subject: [PATCH 088/154] swarnima's feedback --- modules/ROOT/pages/security-settings.adoc | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/modules/ROOT/pages/security-settings.adoc b/modules/ROOT/pages/security-settings.adoc index 1d4cbd94e..0eda6d3c1 100644 --- a/modules/ROOT/pages/security-settings.adoc +++ b/modules/ROOT/pages/security-settings.adoc @@ -26,6 +26,11 @@ To avoid this issue, ThoughtSpot recommends the following: If your organization uses a firewall or Content Delivery Network (CDN) with domain-level access controls, you must allowlist the following domains before provisioning a new ThoughtSpot cluster or modifying an existing firewall configuration. Without access to the critical domains, ThoughtSpot will not load. +[NOTE] +==== +Contact your network administrator to apply these allowlist rules. ThoughtSpot does not manage your organization's firewall or CDN configuration. +==== + === Critical domains Allowlist the following domains to ensure ThoughtSpot loads correctly. If any of these are blocked, ThoughtSpot will not function. @@ -46,7 +51,7 @@ Allowlist the following domains to ensure ThoughtSpot loads correctly. If any of === Optional domains -Allowlist the following domains if you use the corresponding ThoughtSpot features. +The following domains support third-party services that ThoughtSpot uses for product analytics, in-app guidance, customer support, and content delivery. Allowlist these domains to ensure these services load correctly within your ThoughtSpot instance. [options="header",cols="2,3"] |=== From 56338a36519e46e2b66b64d42205ce5397fe632e Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Fri, 21 Aug 2026 16:55:11 +0530 Subject: [PATCH 089/154] SCAL-333737 --- modules/ROOT/pages/security-settings.adoc | 38 +++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/modules/ROOT/pages/security-settings.adoc b/modules/ROOT/pages/security-settings.adoc index a0a1a3131..1d4cbd94e 100644 --- a/modules/ROOT/pages/security-settings.adoc +++ b/modules/ROOT/pages/security-settings.adoc @@ -21,6 +21,44 @@ To avoid this issue, ThoughtSpot recommends the following: * If you are using a ThoughtSpot Cloud instance, set up your instance to the same domain as your host application. For more information, see link:https://docs.thoughtspot.com/cloud/latest/custom-domains[Custom domain configuration, window=_blank]. * If you are using authentication methods that rely on cookies, xref:_enable_partitioned_cookies[enable partitioned cookies]. +[#network-access-requirements] +== Network access requirements + +If your organization uses a firewall or Content Delivery Network (CDN) with domain-level access controls, you must allowlist the following domains before provisioning a new ThoughtSpot cluster or modifying an existing firewall configuration. Without access to the critical domains, ThoughtSpot will not load. + +=== Critical domains + +Allowlist the following domains to ensure ThoughtSpot loads correctly. If any of these are blocked, ThoughtSpot will not function. + +[options="header",cols="2,3"] +|=== +|Domain |Purpose +|`+*.thoughtspot.cloud+` |ThoughtSpot application and APIs +|`+*.thoughtspotartifacts.cloud+` |Static assets and build artifacts +|`+*.thoughtspotlogin.cloud+` |Authentication and login flows +|`+ok14static.oktacdn.com+` |Okta authentication assets +|`+*.cloudfront.net+` |CDN-served ThoughtSpot resources +|`+cdn.skypack.dev+` |JavaScript module delivery +|`+cdn.jsdelivr.net+` |Open-source library assets +|`+cdnjs.cloudflare.com+` |Open-source library assets +|`+code.jquery.com+` |jQuery library +|=== + +=== Optional domains + +Allowlist the following domains if you use the corresponding ThoughtSpot features. + +[options="header",cols="2,3"] +|=== +|Domain |Feature +|`+cdn.mxpnl.com+` |Mixpanel product analytics +|`+app.pendo.io+` |Pendo in-app guidance +|`+cdn.pendo.io+` |Pendo in-app guidance +|`+fonts.googleapis.com+` |Google Fonts +|`+js.intercomcdn.com+` |Intercom in-app support +|`+fast.wistia.com+` |Wistia embedded video content +|=== + == Configure security settings Users with administration privileges can configure security settings on the Security settings page of the ThoughtSpot UI, or by sending a request to the `POST /api/rest/2.0/system/security-settings/configure` API endpoint. Note that the following settings on the **Security Settings** page will appear as locked for ThoughtSpot Analytics application users and will require an embedding license: From 945f08837c825379b070b288497d25781ac46963 Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Mon, 31 Aug 2026 13:14:03 +0530 Subject: [PATCH 090/154] swarnima's feedback --- modules/ROOT/pages/security-settings.adoc | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/modules/ROOT/pages/security-settings.adoc b/modules/ROOT/pages/security-settings.adoc index 1d4cbd94e..0eda6d3c1 100644 --- a/modules/ROOT/pages/security-settings.adoc +++ b/modules/ROOT/pages/security-settings.adoc @@ -26,6 +26,11 @@ To avoid this issue, ThoughtSpot recommends the following: If your organization uses a firewall or Content Delivery Network (CDN) with domain-level access controls, you must allowlist the following domains before provisioning a new ThoughtSpot cluster or modifying an existing firewall configuration. Without access to the critical domains, ThoughtSpot will not load. +[NOTE] +==== +Contact your network administrator to apply these allowlist rules. ThoughtSpot does not manage your organization's firewall or CDN configuration. +==== + === Critical domains Allowlist the following domains to ensure ThoughtSpot loads correctly. If any of these are blocked, ThoughtSpot will not function. @@ -46,7 +51,7 @@ Allowlist the following domains to ensure ThoughtSpot loads correctly. If any of === Optional domains -Allowlist the following domains if you use the corresponding ThoughtSpot features. +The following domains support third-party services that ThoughtSpot uses for product analytics, in-app guidance, customer support, and content delivery. Allowlist these domains to ensure these services load correctly within your ThoughtSpot instance. [options="header",cols="2,3"] |=== From a2371e01a4eca795519490e19ef723c6e4836a6b Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Mon, 31 Aug 2026 20:45:40 +0530 Subject: [PATCH 091/154] edits --- modules/ROOT/pages/api-changelog.adoc | 225 ++++++++++++++++-- .../ROOT/pages/customize-spotter-embed.adoc | 44 ++++ 2 files changed, 254 insertions(+), 15 deletions(-) diff --git a/modules/ROOT/pages/api-changelog.adoc b/modules/ROOT/pages/api-changelog.adoc index 7b61550e8..d178aed24 100644 --- a/modules/ROOT/pages/api-changelog.adoc +++ b/modules/ROOT/pages/api-changelog.adoc @@ -15,42 +15,237 @@ This page documents the changes introduced in each release of the Visual Embed S |[tag greenBackground]#NEW FEATURE# a| [discrete] -===== Browser history management in full application embedding -To override the browser history behavior for embedding application users and prevent users from getting trapped in back-button loops inside the embedded iframe environment, you can now set `overrideHistoryState` in the Visual Embed SDK. +===== Browser history management in embedded application +To override the browser history behavior for embedding application users, you can now set `overrideHistoryState` in the Visual Embed SDK. Use this setting in your embed when the in-app navigation between objects pushes multiple entries onto the host application's browser history stack. When set to `true`, this feature prevents users from getting trapped in back-button loops inside the embedded iframe. +|[tag greenBackground]#NEW FEATURE# a| + +[discrete] +===== Collections in left navigation panel +The `HomeLeftNavItem.Collections` enum value is now available in the Visual Embed SDK. Embed developers can include *Collections* as a selectable navigation option in the embedded left navigation panel for full application embeds. When enabled, end users of the embedded application can navigate to *Collections* from the left navigation panel. + +For more information, see xref:full-app-customize.adoc[Customize full application embedding]. + +|[tag greenBackground]#NEW FEATURE# a| + +[discrete] +===== Starter prompt configuration for Spotter embed +The SDK introduces starter prompt configuration properties for the embedded Spotter interface. The `StarterPromptsConfig` interface allows you to set or disable specific elements such as quick search, deep analysis, and data literacy pills on the Spotter page. \ + +The `starterPrompts` object allows you to enable + +Customizes the labels and questions of the Spotter starter prompts. Individual pills are hidden or shown with hiddenActions / visibleActions using Action.QuickSearchPill, Action.DeepAnalysisPill and Action.DataLiteracyPill. + + +For more information, see xref:customize-spotter-embed.adoc#_spotter_starter_prompts[Spotter quick starter prompts]. + + + + +|[tag greenBackground]#NEW FEATURE# a| + +[discrete] +===== Spotter starter-prompt pill actions +The SDK introduces the following `Action` IDs to control the visibility of starter prompt pills in the Spotter chat interface. Spotter chat starter-prompt pills. You can use these action IDs to show or hide specific starter-prompt categories in the embedded Spotter interface. + + +The Basic Search starter prompt pill. + +Starter prompt pills are the row of category buttons shown above the Spotter chat input before a conversation starts. They give a new user ready-made questions to click instead of typing one from scratch, and disappear once the conversation begins. There are three, one per action below. + +Clicking this pill opens a card of suggested simple questions; picking one submits it to Spotter right away. Visible by default, and hidden along with the other pills when the surface itself is off + +* `Action.QuickSearchPill` — Controls the *Basic Search* starter-prompt pill shown above the Spotter chat input. +* `Action.DeepAnalysisPill` — Controls the *Deep Analysis* starter-prompt pill. +* `Action.DataLiteracyPill` — Controls the *Data Literacy* starter-prompt pill. This pill submits a fixed prompt describing the connected data source. -//// [source,JavaScript] ---- -import { AppEmbed, init, AuthType } from '@thoughtspot/visual-embed-sdk'; +const spotterEmbed = new SpotterEmbed('#ts-embed', { + // Hide the Deep Analysis pill + disabledActions: [Action.DeepAnalysisPill], + // Alternatively, hide all three: + // disabledActions: [Action.QuickSearchPill, Action.DeepAnalysisPill, Action.DataLiteracyPill], +}); + +spotterEmbed.render(); +---- + +These action IDs can be passed in `disabledActions`, `hiddenActions`, or `visibleActions` on any embed type where Spotter is available (`SpotterEmbed`, `AppEmbed`, `LiveboardEmbed`). + +For more information, see xref:embed-actions.adoc[Show or hide actions] and xref:customize-spotter-embed.adoc#_spotter_starter_prompts[Spotter quick starter prompts]. + +|[tag greenBackground]#NEW FEATURE# a| + +[discrete] +===== Pre-render configuration object + +The SDK introduces the `PreRenderConfig` interface, which bundles pre-rendering settings into a single object: + +* `preRenderId` — Unique identifier for the pre-rendered embed instance. +* `preRenderContainer` — DOM element or selector for the pre-render container. +* `doNotTrackPreRenderSize` — When `true`, disables automatic size tracking of the pre-render container. +* `zIndex` — Z-index for the pre-rendered iframe. + +Use the new `preRenderConfig` property on `BaseViewConfig` instead of the individual top-level properties. -init({ - thoughtSpotHost: 'https://.thoughtspot.cloud', - authType: AuthType.TrustedAuthToken, - getAuthToken: () => fetch('/ts-token').then(r => r.json()).then(d => d.token), +[source,JavaScript] +---- +const embed = new LiveboardEmbed('#embed-container', { + liveboardId: '', + preRenderConfig: { + preRenderId: 'my-pre-render', + preRenderContainer: document.getElementById('pre-render-div'), + doNotTrackPreRenderSize: false, + zIndex: 100, + }, }); +---- + +[IMPORTANT] +==== +The following top-level properties are now [.version-badge.deprecated]#Deprecated# in favor of `preRenderConfig`: + +* `preRenderId` +* `preRenderContainer` +* `doNotTrackPreRenderSize` + +The deprecated properties continue to work but will be removed in a future release. Migrate to `preRenderConfig` when updating your integration. +==== + +For more information, see xref:prerender.adoc[Pre-rendering ThoughtSpot embed components]. + +|[tag greenBackground]#NEW FEATURE# a| + +[discrete] +===== Exported host-event contract types + +// SOURCE: SCAL-325540 + +The SDK now publicly exports host-event contract types that were previously internal-only. This allows TypeScript consumers to strongly type `embed.trigger(HostEvent.X, payload)` calls without importing internal modules. + +Newly exported types include: + +* `UIPassthroughContractBase`, `UIPassthroughRequest`, `UIPassthroughResponse`, `UIPassthroughArrayResponse` +* `HostEventRequest`, `HostEventResponse` +* `TriggerPayload`, `TriggerResponse` +* `LiveboardTab`, `LiveboardGroup` +* `Applicability`, `ApplicabilityLevel` +* `FilterUpdate`, `LiveboardFilter`, `LiveboardParameter` +* `SpotterAnalystConfig` +* `StarterPromptsConfig`, `StarterPromptCategory`, `StarterPreviewDataCategory`, `StarterPromptQuestion` + +[source,TypeScript] +---- +import { + HostEvent, + HostEventRequest, + TriggerResponse, + LiveboardFilter, +} from '@thoughtspot/visual-embed-sdk'; + +// Strongly typed trigger call +const response: TriggerResponse = await embed.trigger( + HostEvent.UpdateRuntimeFilters, + { filters: myFilters } as HostEventRequest, +); +---- + +|[tag greenBackground]#NEW FEATURE# a| + +[discrete] +===== CSS variable for unsaved filter indicator + +A new CSS variable `--ts-var-unsaved-filter-indicator-color` is available to customize the color of the "unsaved changes" indicator dot shown on filter and parameter chips. + +[source,JavaScript] +---- +const embed = new LiveboardEmbed('#embed-container', { + liveboardId: '', + customizations: { + style: { + customCSS: { + variables: { + '--ts-var-unsaved-filter-indicator-color': '#FF6B35', + }, + }, + }, + }, +}); +---- + +For more information, see xref:css-customization.adoc[CSS customization framework]. + +|[tag greenBackground]#NEW FEATURE# a| + +[discrete] +===== Liveboard Schedules page in full application embedding + +The `Page.LiveboardSchedules` enum value (`'liveboard-schedules'`) is now available for full application embedding. Use this value to navigate users directly to the Liveboard schedules list page. + +[source,JavaScript] +---- +import { AppEmbed, Page } from '@thoughtspot/visual-embed-sdk'; const embed = new AppEmbed('#embed-container', { - frameParams: { width: '100%', height: '100%' }, - overrideHistoryState: true, // <1> + pageId: Page.LiveboardSchedules, }); embed.render(); ---- -<1> When set to `true`, ThoughtSpot replaces rather than pushes browser history entries during internal navigation. -//// |[tag greenBackground]#NEW FEATURE# a| [discrete] -===== Collections in left navigation panel -The `HomeLeftNavItem.Collections` enum value is now available in the Visual Embed SDK. Embed developers can include *Collections* as a selectable navigation option in the embedded left navigation panel for full application embeds. When enabled, end users of the embedded application can navigate to *Collections* from the left navigation panel. +===== Insight tile CSS variables -For more information, see xref:full-app-customize.adoc[Customize full application embedding]. +New CSS variables are available to customize the Liveboard insight tile appearance: + +* `--ts-var-liveboard-insight-tile-background` — Background color of the insight tile. +* `--ts-var-liveboard-insight-tile-icon-color` — Color of the insight tile icon. +* `--ts-var-liveboard-insight-tile-success-color` — Color used for positive/success indicators. +* `--ts-var-liveboard-insight-tile-failure-color` — Color used for negative/failure indicators. + +// SOURCE: SCAL-325451 + +For more information, see xref:css-customization.adoc[CSS customization framework]. + +|[tag greenBackground]#MODIFIED# a| + +[discrete] +===== Lazy loading defaults changed for full-height embeds + +// SOURCE: SCAL-333385 + +When `fullHeight` is set to `true` on `AppEmbed` or `LiveboardEmbed`, the following lazy loading parameters now **default to enabled** (previously they defaulted to disabled): + +* `lazyLoadingForFullHeight` — defaults to `true` +* `enableScrollableContainerLazyLoading` — defaults to `true` +* `lazyLoadingMargin` — defaults to `'500px 0px'` + +This improves initial load performance for large Liveboards. If your integration relies on all visualizations loading immediately when `fullHeight` is enabled, you must now explicitly set these parameters to `false`. + +[source,JavaScript] +---- +// To restore previous behavior (all visualizations load immediately): +const embed = new LiveboardEmbed('#embed-container', { + liveboardId: '', + fullHeight: true, + lazyLoadingForFullHeight: false, + enableScrollableContainerLazyLoading: false, +}); +---- + +For more information, see xref:lazy-loading-fullheight.adoc[Lazy loading of Liveboard visualizations]. |==== + + + + + == Version 1.51.x, August 2026 [width="100%" cols="1,4"] diff --git a/modules/ROOT/pages/customize-spotter-embed.adoc b/modules/ROOT/pages/customize-spotter-embed.adoc index 762f4445d..00a425a95 100644 --- a/modules/ROOT/pages/customize-spotter-embed.adoc +++ b/modules/ROOT/pages/customize-spotter-embed.adoc @@ -161,6 +161,50 @@ const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { }); ---- +[source,JavaScript] +---- +const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { + // ...other embed view configuration options +spotterChatConfig: { + enableStarterPrompts: true, + starterPrompts: { + enable: true, + quick: { + label: "Quick questions", + questions: [ + { + label: "Top customers", + prompt: "Who are my top customers by revenue?" + }, + { + label: "Sales by region", + prompt: "Show sales by region" + } + ] + }, + research: { + label: "Deep analysis", + questions: [ + { + label: "Revenue drivers", + prompt: "Analyze the main drivers of revenue changes" + }, + { + label: "Customer churn factors", + prompt: "What factors are driving customer churn?" + } + ] + }, + previewData: { + label: "Explore data" + } + } + }, + +---- + + + [#mcp-connectors] == MCP connectors and resource selection icon If the Spotter 3 interface is enabled, the Spotter page displays the following options to connect external tools and resources for AI analytics. From feb84e649862d0218b8783a421953490f6101f92 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Mon, 31 Aug 2026 20:54:04 +0530 Subject: [PATCH 092/154] spotterviz updates --- modules/ROOT/pages/embed-spotterViz.adoc | 7 ++----- modules/ROOT/pages/whats-new.adoc | 2 +- 2 files changed, 3 insertions(+), 6 deletions(-) diff --git a/modules/ROOT/pages/embed-spotterViz.adoc b/modules/ROOT/pages/embed-spotterViz.adoc index cf059d4dc..0f4bfbf35 100644 --- a/modules/ROOT/pages/embed-spotterViz.adoc +++ b/modules/ROOT/pages/embed-spotterViz.adoc @@ -6,13 +6,11 @@ :page-pageid: spotterViz-agent :page-description: Customize the SpotterViz panel in embedded Liveboards using the Visual Embed SDK. -[earlyAccess eaBackground]#Early Access# - -ThoughtSpot link:https://docs.thoughtspot.com/cloud/latest/spotter-viz[SpotterViz, window=_blank] is the AI-powered analysis panel that appears when a user opens the Liveboard in edit mode. It provides Liveboard users with an in-context AI assistant and a prompt interface to ask questions on Liveboard data and receive automatically generated visualizations and insights in response. +ThoughtSpot link:https://docs.thoughtspot.com/cloud/latest/spotter-viz[SpotterViz, window=_blank] is an AI-powered analysis panel that appears when a user opens the Liveboard in edit mode. It provides Liveboard users with an in-context AI assistant and a prompt interface to ask questions on Liveboard data and receive automatically generated visualizations and insights in response. [NOTE] ==== -SpotterViz is an early access feature and is disabled by default on ThoughtSpot instances. To enable this feature on your instance, contact ThoughtSpot Support. +SpotterViz is disabled by default on ThoughtSpot instances. To enable this feature on your instance, contact ThoughtSpot Support. ==== == Before you begin @@ -51,7 +49,6 @@ Loading state tips:: Use `loaderTips` to replace the default tips shown alongsid + If you set `loaderTips` to an empty array, no tips will be displayed. - Starter prompts:: SpotterViz displays the question suggestions in the panel to help users begin an AI-assisted analysis. Each prompt has a short display label (`displayText`) and a full prompt string (`fullPrompt`) sent to Spotter when clicked. diff --git a/modules/ROOT/pages/whats-new.adoc b/modules/ROOT/pages/whats-new.adoc index 12acd4622..55ec0e2c5 100644 --- a/modules/ROOT/pages/whats-new.adoc +++ b/modules/ROOT/pages/whats-new.adoc @@ -116,7 +116,7 @@ This developer documentation site now includes a SpotterCode AI assistant panel [discrete] ==== Visual Embed SDK -The Visual Embed SDK version 1.51.0 includes new features and enhancements for Spotter Analysts, starter prompts, SpotterViz loading state customization, and the `HostEvent.Navigate` object format. For more information, see the xref:api-changelog.adoc[Visual Embed SDK changelog]. +The Visual Embed SDK version 1.51.0 includes new features and enhancements for Spotter Analysts, starter prompts, and the `HostEvent.Navigate` object format. For more information, see the xref:api-changelog.adoc[Visual Embed SDK changelog]. --- From 42798eabef749209365bebb729bfffbe692e2d93 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Mon, 31 Aug 2026 20:54:04 +0530 Subject: [PATCH 093/154] spotterviz updates --- modules/ROOT/pages/embed-spotterViz.adoc | 7 ++----- modules/ROOT/pages/whats-new.adoc | 2 +- 2 files changed, 3 insertions(+), 6 deletions(-) diff --git a/modules/ROOT/pages/embed-spotterViz.adoc b/modules/ROOT/pages/embed-spotterViz.adoc index cf059d4dc..0f4bfbf35 100644 --- a/modules/ROOT/pages/embed-spotterViz.adoc +++ b/modules/ROOT/pages/embed-spotterViz.adoc @@ -6,13 +6,11 @@ :page-pageid: spotterViz-agent :page-description: Customize the SpotterViz panel in embedded Liveboards using the Visual Embed SDK. -[earlyAccess eaBackground]#Early Access# - -ThoughtSpot link:https://docs.thoughtspot.com/cloud/latest/spotter-viz[SpotterViz, window=_blank] is the AI-powered analysis panel that appears when a user opens the Liveboard in edit mode. It provides Liveboard users with an in-context AI assistant and a prompt interface to ask questions on Liveboard data and receive automatically generated visualizations and insights in response. +ThoughtSpot link:https://docs.thoughtspot.com/cloud/latest/spotter-viz[SpotterViz, window=_blank] is an AI-powered analysis panel that appears when a user opens the Liveboard in edit mode. It provides Liveboard users with an in-context AI assistant and a prompt interface to ask questions on Liveboard data and receive automatically generated visualizations and insights in response. [NOTE] ==== -SpotterViz is an early access feature and is disabled by default on ThoughtSpot instances. To enable this feature on your instance, contact ThoughtSpot Support. +SpotterViz is disabled by default on ThoughtSpot instances. To enable this feature on your instance, contact ThoughtSpot Support. ==== == Before you begin @@ -51,7 +49,6 @@ Loading state tips:: Use `loaderTips` to replace the default tips shown alongsid + If you set `loaderTips` to an empty array, no tips will be displayed. - Starter prompts:: SpotterViz displays the question suggestions in the panel to help users begin an AI-assisted analysis. Each prompt has a short display label (`displayText`) and a full prompt string (`fullPrompt`) sent to Spotter when clicked. diff --git a/modules/ROOT/pages/whats-new.adoc b/modules/ROOT/pages/whats-new.adoc index 1900d4119..86a132fa7 100644 --- a/modules/ROOT/pages/whats-new.adoc +++ b/modules/ROOT/pages/whats-new.adoc @@ -115,7 +115,7 @@ This developer documentation site now includes a SpotterCode AI assistant panel [discrete] ==== Visual Embed SDK -The Visual Embed SDK version 1.51.0 includes new features and enhancements for Spotter Analysts, starter prompts, SpotterViz loading state customization, and the `HostEvent.Navigate` object format. For more information, see the xref:api-changelog.adoc[Visual Embed SDK changelog]. +The Visual Embed SDK version 1.51.0 includes new features and enhancements for Spotter Analysts, starter prompts, and the `HostEvent.Navigate` object format. For more information, see the xref:api-changelog.adoc[Visual Embed SDK changelog]. --- From e177dd4ef3dd13f210f395a1cf2c1da7a4ccca1c Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Mon, 31 Aug 2026 21:27:31 +0530 Subject: [PATCH 094/154] removed EA tag from lb styling --- modules/ROOT/pages/embed-pinboard.adoc | 1 - 1 file changed, 1 deletion(-) diff --git a/modules/ROOT/pages/embed-pinboard.adoc b/modules/ROOT/pages/embed-pinboard.adoc index 0f2c70d79..5b9c22106 100644 --- a/modules/ROOT/pages/embed-pinboard.adoc +++ b/modules/ROOT/pages/embed-pinboard.adoc @@ -421,7 +421,6 @@ To open the **Download** modal with the XLSX option selected when the `isLiveboa To open the **Download** modal with the CSV option selected when `isLiveboardXLSXCSVDownloadEnabled` parameter is enabled in the embed view. === Liveboard grouping and styling -[earlyAccess eaBackground]#Early Access# You can now create a visual group of Answers and note tiles together in the Liveboard. You can select multiple Answers and notes in the Liveboard editor. You can also style parts of the Liveboard, groups and Answers with the new styling panel. To enable this feature, set `isLiveboardMasterpiecesEnabled` to `true`. From 42c4c253894dff52723d9ac48297032b4e39f7f0 Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Mon, 31 Aug 2026 22:23:13 +0530 Subject: [PATCH 095/154] EA flag for lb styling from css --- modules/ROOT/pages/customize-css-styles.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/customize-css-styles.adoc b/modules/ROOT/pages/customize-css-styles.adoc index 067cd0da9..b31d03bd9 100644 --- a/modules/ROOT/pages/customize-css-styles.adoc +++ b/modules/ROOT/pages/customize-css-styles.adoc @@ -207,7 +207,7 @@ Use the following variables to customize the Liveboard page elements. image::./images/custom-css-viz.png[CSS customization Liveboard page] -- [#grp-style] -=== Liveboard grouping and styling [earlyAccess eaBackground]#Early Access# +=== Liveboard grouping and styling Use the following variables to customize the Liveboard visualization groups and style elements. [NOTE] From e7a543de10489cc46fc7eacec53a6f1a0a804e89 Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Mon, 31 Aug 2026 22:31:26 +0530 Subject: [PATCH 096/154] EA content for styling --- modules/ROOT/pages/customize-css-styles.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/customize-css-styles.adoc b/modules/ROOT/pages/customize-css-styles.adoc index b31d03bd9..c81d7804e 100644 --- a/modules/ROOT/pages/customize-css-styles.adoc +++ b/modules/ROOT/pages/customize-css-styles.adoc @@ -212,7 +212,7 @@ Use the following variables to customize the Liveboard visualization groups and [NOTE] ==== -To enable this feature contact ThoughtSpot support and set `isLiveboardMasterpiecesEnabled` to `true` in the SDK . +To enable this feature set `isLiveboardMasterpiecesEnabled` to `true` in the SDK . ==== [width="100%" cols="7,7"] From a37e85c606806e995c62d42ac6c64e671ea32680 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Tue, 1 Sep 2026 07:49:42 +0530 Subject: [PATCH 097/154] removed redundant text --- modules/ROOT/pages/embed-spotterViz.adoc | 4 ---- 1 file changed, 4 deletions(-) diff --git a/modules/ROOT/pages/embed-spotterViz.adoc b/modules/ROOT/pages/embed-spotterViz.adoc index 0f4bfbf35..3b9cdc892 100644 --- a/modules/ROOT/pages/embed-spotterViz.adoc +++ b/modules/ROOT/pages/embed-spotterViz.adoc @@ -13,10 +13,6 @@ ThoughtSpot link:https://docs.thoughtspot.com/cloud/latest/spotter-viz[SpotterVi SpotterViz is disabled by default on ThoughtSpot instances. To enable this feature on your instance, contact ThoughtSpot Support. ==== -== Before you begin -* Ensure that the Spotter feature is enabled on your ThoughtSpot instance. -* Ensure that the SpotterViz feature is enabled on your instance. Contact your ThoughtSpot administrator if SpotterViz is not enabled. - == Accessing SpotterViz panel If the SpotterViz feature is enabled on the instance, the panel is displayed by default when a Liveboard is opened in the edit mode in the embedded view. From 64e4b62ec929d9a059e7799d146aa9c868a30ef9 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Tue, 1 Sep 2026 07:49:42 +0530 Subject: [PATCH 098/154] removed redundant text --- modules/ROOT/pages/embed-spotterViz.adoc | 4 ---- 1 file changed, 4 deletions(-) diff --git a/modules/ROOT/pages/embed-spotterViz.adoc b/modules/ROOT/pages/embed-spotterViz.adoc index 0f4bfbf35..3b9cdc892 100644 --- a/modules/ROOT/pages/embed-spotterViz.adoc +++ b/modules/ROOT/pages/embed-spotterViz.adoc @@ -13,10 +13,6 @@ ThoughtSpot link:https://docs.thoughtspot.com/cloud/latest/spotter-viz[SpotterVi SpotterViz is disabled by default on ThoughtSpot instances. To enable this feature on your instance, contact ThoughtSpot Support. ==== -== Before you begin -* Ensure that the Spotter feature is enabled on your ThoughtSpot instance. -* Ensure that the SpotterViz feature is enabled on your instance. Contact your ThoughtSpot administrator if SpotterViz is not enabled. - == Accessing SpotterViz panel If the SpotterViz feature is enabled on the instance, the panel is displayed by default when a Liveboard is opened in the edit mode in the embedded view. From 76d94de7482e12b2fe3386bfbeba0ee7c23f5aa7 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Mon, 31 Aug 2026 20:54:04 +0530 Subject: [PATCH 099/154] spotterviz updates --- modules/ROOT/pages/embed-spotterViz.adoc | 7 ++----- modules/ROOT/pages/whats-new.adoc | 2 +- 2 files changed, 3 insertions(+), 6 deletions(-) diff --git a/modules/ROOT/pages/embed-spotterViz.adoc b/modules/ROOT/pages/embed-spotterViz.adoc index cf059d4dc..0f4bfbf35 100644 --- a/modules/ROOT/pages/embed-spotterViz.adoc +++ b/modules/ROOT/pages/embed-spotterViz.adoc @@ -6,13 +6,11 @@ :page-pageid: spotterViz-agent :page-description: Customize the SpotterViz panel in embedded Liveboards using the Visual Embed SDK. -[earlyAccess eaBackground]#Early Access# - -ThoughtSpot link:https://docs.thoughtspot.com/cloud/latest/spotter-viz[SpotterViz, window=_blank] is the AI-powered analysis panel that appears when a user opens the Liveboard in edit mode. It provides Liveboard users with an in-context AI assistant and a prompt interface to ask questions on Liveboard data and receive automatically generated visualizations and insights in response. +ThoughtSpot link:https://docs.thoughtspot.com/cloud/latest/spotter-viz[SpotterViz, window=_blank] is an AI-powered analysis panel that appears when a user opens the Liveboard in edit mode. It provides Liveboard users with an in-context AI assistant and a prompt interface to ask questions on Liveboard data and receive automatically generated visualizations and insights in response. [NOTE] ==== -SpotterViz is an early access feature and is disabled by default on ThoughtSpot instances. To enable this feature on your instance, contact ThoughtSpot Support. +SpotterViz is disabled by default on ThoughtSpot instances. To enable this feature on your instance, contact ThoughtSpot Support. ==== == Before you begin @@ -51,7 +49,6 @@ Loading state tips:: Use `loaderTips` to replace the default tips shown alongsid + If you set `loaderTips` to an empty array, no tips will be displayed. - Starter prompts:: SpotterViz displays the question suggestions in the panel to help users begin an AI-assisted analysis. Each prompt has a short display label (`displayText`) and a full prompt string (`fullPrompt`) sent to Spotter when clicked. diff --git a/modules/ROOT/pages/whats-new.adoc b/modules/ROOT/pages/whats-new.adoc index f8004e1c8..ed1431875 100644 --- a/modules/ROOT/pages/whats-new.adoc +++ b/modules/ROOT/pages/whats-new.adoc @@ -218,7 +218,7 @@ This developer documentation site now includes a SpotterCode AI assistant panel [discrete] ==== Visual Embed SDK -The Visual Embed SDK version 1.51.0 includes new features and enhancements for Spotter Analysts, starter prompts, SpotterViz loading state customization, and the `HostEvent.Navigate` object format. For more information, see the xref:api-changelog.adoc[Visual Embed SDK changelog]. +The Visual Embed SDK version 1.51.0 includes new features and enhancements for Spotter Analysts, starter prompts, and the `HostEvent.Navigate` object format. For more information, see the xref:api-changelog.adoc[Visual Embed SDK changelog]. --- From 61a13b61ebc4b9447667b24a9bd56e4cadc4bc3e Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Tue, 1 Sep 2026 07:49:42 +0530 Subject: [PATCH 100/154] removed redundant text --- modules/ROOT/pages/embed-spotterViz.adoc | 4 ---- 1 file changed, 4 deletions(-) diff --git a/modules/ROOT/pages/embed-spotterViz.adoc b/modules/ROOT/pages/embed-spotterViz.adoc index 0f4bfbf35..3b9cdc892 100644 --- a/modules/ROOT/pages/embed-spotterViz.adoc +++ b/modules/ROOT/pages/embed-spotterViz.adoc @@ -13,10 +13,6 @@ ThoughtSpot link:https://docs.thoughtspot.com/cloud/latest/spotter-viz[SpotterVi SpotterViz is disabled by default on ThoughtSpot instances. To enable this feature on your instance, contact ThoughtSpot Support. ==== -== Before you begin -* Ensure that the Spotter feature is enabled on your ThoughtSpot instance. -* Ensure that the SpotterViz feature is enabled on your instance. Contact your ThoughtSpot administrator if SpotterViz is not enabled. - == Accessing SpotterViz panel If the SpotterViz feature is enabled on the instance, the panel is displayed by default when a Liveboard is opened in the edit mode in the embedded view. From afca943bcb6fb7bb12873cfab0dc47c8b83fc03c Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Tue, 1 Sep 2026 10:47:09 +0530 Subject: [PATCH 101/154] changelog and other edits --- modules/ROOT/pages/api-changelog.adoc | 541 +++++++----------- .../embed-event-error-best-practices.adoc | 11 + .../ROOT/pages/lazy-loading-fullheight.adoc | 21 + modules/ROOT/pages/rest-apiv2-changelog.adoc | 148 ++--- .../pages/spotter-agent-sharing-apis.adoc | 50 +- modules/ROOT/pages/whats-new.adoc | 48 +- 6 files changed, 328 insertions(+), 491 deletions(-) diff --git a/modules/ROOT/pages/api-changelog.adoc b/modules/ROOT/pages/api-changelog.adoc index d178aed24..f88bab099 100644 --- a/modules/ROOT/pages/api-changelog.adoc +++ b/modules/ROOT/pages/api-changelog.adoc @@ -12,13 +12,13 @@ This page documents the changes introduced in each release of the Visual Embed S [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a| +|[tag greenBackground]#NEW# a| [discrete] ===== Browser history management in embedded application To override the browser history behavior for embedding application users, you can now set `overrideHistoryState` in the Visual Embed SDK. Use this setting in your embed when the in-app navigation between objects pushes multiple entries onto the host application's browser history stack. When set to `true`, this feature prevents users from getting trapped in back-button loops inside the embedded iframe. -|[tag greenBackground]#NEW FEATURE# a| +|[tag greenBackground]#NEW# a| [discrete] ===== Collections in left navigation panel @@ -26,102 +26,60 @@ The `HomeLeftNavItem.Collections` enum value is now available in the Visual Embe For more information, see xref:full-app-customize.adoc[Customize full application embedding]. -|[tag greenBackground]#NEW FEATURE# a| +|[tag greenBackground]#NEW# a| [discrete] -===== Starter prompt configuration for Spotter embed -The SDK introduces starter prompt configuration properties for the embedded Spotter interface. The `StarterPromptsConfig` interface allows you to set or disable specific elements such as quick search, deep analysis, and data literacy pills on the Spotter page. \ - -The `starterPrompts` object allows you to enable - -Customizes the labels and questions of the Spotter starter prompts. Individual pills are hidden or shown with hiddenActions / visibleActions using Action.QuickSearchPill, Action.DeepAnalysisPill and Action.DataLiteracyPill. - - -For more information, see xref:customize-spotter-embed.adoc#_spotter_starter_prompts[Spotter quick starter prompts]. - +===== Spotter embedding +The SDK introduces starter prompt configuration properties for the embedded Spotter interface. The `StarterPromptsConfig` interface allows you to enable and configure properties of elements such as quick search, deep analysis, and data literacy pills on the Spotter page. +The SDK also provides the following action IDs for disabling or hiding these elements: +* `Action.QuickSearchPill` + +Controls the *Basic Search* starter-prompt pill shown above the Spotter chat input. +* `Action.DeepAnalysisPill` + +Controls the *Deep Analysis* starter-prompt pill. +* `Action.DataLiteracyPill` + +Controls the *Data Literacy* starter-prompt pill. This pill submits a fixed prompt describing the connected data source. -|[tag greenBackground]#NEW FEATURE# a| +|[tag greenBackground]#NEW# a| [discrete] -===== Spotter starter-prompt pill actions -The SDK introduces the following `Action` IDs to control the visibility of starter prompt pills in the Spotter chat interface. Spotter chat starter-prompt pills. You can use these action IDs to show or hide specific starter-prompt categories in the embedded Spotter interface. - +===== Spotter starter-prompt customization +The `starterPrompts` object in the `spotterChatConfig` interaface allows you to customize the labels and questions in the **Quick search** section. -The Basic Search starter prompt pill. - -Starter prompt pills are the row of category buttons shown above the Spotter chat input before a conversation starts. They give a new user ready-made questions to click instead of typing one from scratch, and disappear once the conversation begins. There are three, one per action below. +For more information, see xref:customize-spotter-embed.adoc#_spotter_starter_prompts[Spotter quick starter prompts]. -Clicking this pill opens a card of suggested simple questions; picking one submits it to Spotter right away. Visible by default, and hidden along with the other pills when the surface itself is off +|[tag greenBackground]#MODIFIED# a| -* `Action.QuickSearchPill` — Controls the *Basic Search* starter-prompt pill shown above the Spotter chat input. -* `Action.DeepAnalysisPill` — Controls the *Deep Analysis* starter-prompt pill. -* `Action.DataLiteracyPill` — Controls the *Data Literacy* starter-prompt pill. This pill submits a fixed prompt describing the connected data source. +[discrete] +===== Full height setting with lazy loading defaults for Liveboards +When `fullHeight` is enabled on `LiveboardEmbed` or `AppEmbed`, the following lazy-loading parameters now default to `true`: -[source,JavaScript] ----- -const spotterEmbed = new SpotterEmbed('#ts-embed', { - // Hide the Deep Analysis pill - disabledActions: [Action.DeepAnalysisPill], - // Alternatively, hide all three: - // disabledActions: [Action.QuickSearchPill, Action.DeepAnalysisPill, Action.DataLiteracyPill], -}); - -spotterEmbed.render(); ----- +* `lazyLoadingForFullHeight` + +Enables lazy loading of visualizations when fullHeight is enabled. +* `enableScrollableContainerLazyLoading` + +Enables lazy loading for scrollable container elements. +* `lazyLoadingMargin` + +Sets the margin for lazy loading to `'500px 0px'`. -These action IDs can be passed in `disabledActions`, `hiddenActions`, or `visibleActions` on any embed type where Spotter is available (`SpotterEmbed`, `AppEmbed`, `LiveboardEmbed`). +These defaults apply automatically. Any value you set explicitly, including `false`, overrides the default. If `fullHeight` is disabled or not specified, the behavior is not affected. -For more information, see xref:embed-actions.adoc[Show or hide actions] and xref:customize-spotter-embed.adoc#_spotter_starter_prompts[Spotter quick starter prompts]. +For more information, see xref:lazy-loading-fullheight.adoc[Full height and lazy loading options for Liveboards]. -|[tag greenBackground]#NEW FEATURE# a| +|[tag greenBackground]#NEW# a| [discrete] ===== Pre-render configuration object +The SDK introduces the `PreRenderConfig` interface, which bundles the existing prerender settings such as `preRenderId`, `preRenderContainer`, and `doNotTrackPreRenderSize` into a single object. -The SDK introduces the `PreRenderConfig` interface, which bundles pre-rendering settings into a single object: - -* `preRenderId` — Unique identifier for the pre-rendered embed instance. -* `preRenderContainer` — DOM element or selector for the pre-render container. -* `doNotTrackPreRenderSize` — When `true`, disables automatic size tracking of the pre-render container. -* `zIndex` — Z-index for the pre-rendered iframe. - -Use the new `preRenderConfig` property on `BaseViewConfig` instead of the individual top-level properties. - -[source,JavaScript] ----- -const embed = new LiveboardEmbed('#embed-container', { - liveboardId: '', - preRenderConfig: { - preRenderId: 'my-pre-render', - preRenderContainer: document.getElementById('pre-render-div'), - doNotTrackPreRenderSize: false, - zIndex: 100, - }, -}); ----- - -[IMPORTANT] -==== -The following top-level properties are now [.version-badge.deprecated]#Deprecated# in favor of `preRenderConfig`: - -* `preRenderId` -* `preRenderContainer` -* `doNotTrackPreRenderSize` - -The deprecated properties continue to work but will be removed in a future release. Migrate to `preRenderConfig` when updating your integration. -==== +The existing individual `preRenderId`, `preRenderContainer`, and `doNotTrackPreRenderSize` properties at the top-level are deprecated in this version. Update your integration to use the new `preRenderConfig` property on `BaseViewConfig` instead of the individual top-level properties. For more information, see xref:prerender.adoc[Pre-rendering ThoughtSpot embed components]. -|[tag greenBackground]#NEW FEATURE# a| +|[tag greenBackground]#NEW# a| [discrete] ===== Exported host-event contract types - -// SOURCE: SCAL-325540 - The SDK now publicly exports host-event contract types that were previously internal-only. This allows TypeScript consumers to strongly type `embed.trigger(HostEvent.X, payload)` calls without importing internal modules. Newly exported types include: @@ -135,122 +93,42 @@ Newly exported types include: * `SpotterAnalystConfig` * `StarterPromptsConfig`, `StarterPromptCategory`, `StarterPreviewDataCategory`, `StarterPromptQuestion` -[source,TypeScript] ----- -import { - HostEvent, - HostEventRequest, - TriggerResponse, - LiveboardFilter, -} from '@thoughtspot/visual-embed-sdk'; - -// Strongly typed trigger call -const response: TriggerResponse = await embed.trigger( - HostEvent.UpdateRuntimeFilters, - { filters: myFilters } as HostEventRequest, -); ----- - -|[tag greenBackground]#NEW FEATURE# a| +|[tag greenBackground]#NEW# a| [discrete] -===== CSS variable for unsaved filter indicator +===== CSS customization +CSS variable for unsaved filter indicator:: A new CSS variable `--ts-var-unsaved-filter-indicator-color` is available to customize the color of the "unsaved changes" indicator dot shown on filter and parameter chips. -[source,JavaScript] ----- -const embed = new LiveboardEmbed('#embed-container', { - liveboardId: '', - customizations: { - style: { - customCSS: { - variables: { - '--ts-var-unsaved-filter-indicator-color': '#FF6B35', - }, - }, - }, - }, -}); ----- +Insight tile CSS variables:: +New CSS variables are available to customize the Liveboard insight tile appearance: + +* `--ts-var-liveboard-insight-tile-background` + +Background color of the insight tile. +* `--ts-var-liveboard-insight-tile-icon-color` + +Color of the insight tile icon. +* `--ts-var-liveboard-insight-tile-success-color` + +Color used for positive/success indicators. +* `--ts-var-liveboard-insight-tile-failure-color` + +Color used for negative/failure indicators. For more information, see xref:css-customization.adoc[CSS customization framework]. -|[tag greenBackground]#NEW FEATURE# a| +|[tag greenBackground]#NEW# a| [discrete] ===== Liveboard Schedules page in full application embedding - The `Page.LiveboardSchedules` enum value (`'liveboard-schedules'`) is now available for full application embedding. Use this value to navigate users directly to the Liveboard schedules list page. -[source,JavaScript] ----- -import { AppEmbed, Page } from '@thoughtspot/visual-embed-sdk'; - -const embed = new AppEmbed('#embed-container', { - pageId: Page.LiveboardSchedules, -}); - -embed.render(); ----- - -|[tag greenBackground]#NEW FEATURE# a| - -[discrete] -===== Insight tile CSS variables - -New CSS variables are available to customize the Liveboard insight tile appearance: - -* `--ts-var-liveboard-insight-tile-background` — Background color of the insight tile. -* `--ts-var-liveboard-insight-tile-icon-color` — Color of the insight tile icon. -* `--ts-var-liveboard-insight-tile-success-color` — Color used for positive/success indicators. -* `--ts-var-liveboard-insight-tile-failure-color` — Color used for negative/failure indicators. - -// SOURCE: SCAL-325451 - -For more information, see xref:css-customization.adoc[CSS customization framework]. - |[tag greenBackground]#MODIFIED# a| - -[discrete] -===== Lazy loading defaults changed for full-height embeds - -// SOURCE: SCAL-333385 - -When `fullHeight` is set to `true` on `AppEmbed` or `LiveboardEmbed`, the following lazy loading parameters now **default to enabled** (previously they defaulted to disabled): - -* `lazyLoadingForFullHeight` — defaults to `true` -* `enableScrollableContainerLazyLoading` — defaults to `true` -* `lazyLoadingMargin` — defaults to `'500px 0px'` - -This improves initial load performance for large Liveboards. If your integration relies on all visualizations loading immediately when `fullHeight` is enabled, you must now explicitly set these parameters to `false`. - -[source,JavaScript] ----- -// To restore previous behavior (all visualizations load immediately): -const embed = new LiveboardEmbed('#embed-container', { - liveboardId: '', - fullHeight: true, - lazyLoadingForFullHeight: false, - enableScrollableContainerLazyLoading: false, -}); ----- - -For more information, see xref:lazy-loading-fullheight.adoc[Lazy loading of Liveboard visualizations]. - |==== - - - - - - == Version 1.51.x, August 2026 [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a| +|[tag greenBackground]#NEW# a| [discrete] ===== Spotter embedding @@ -280,34 +158,19 @@ Enables interactive filter chips that allow users to add, update, or remove filt For more information, see xref:embed-pinboard.adoc#common-customizations[Common customization options in Liveboard embedding]. -|[tag greenBackground]#NEW FEATURE# a| +|[tag greenBackground]#NEW# a| [discrete] ===== Object format support in HostEvent.Navigate The `HostEvent.Navigate` event now supports an object format in addition to the existing string path format. Use the object format to replace the current browser history entry instead of pushing a new entry. -//// -[source,JavaScript] ----- -// String format — push new history entry (existing behavior, unchanged) -appEmbed.trigger(HostEvent.Navigate, 'home'); ----- - -[source,JavaScript] ----- -// Object format — replace current history entry (new in SDK 1.51.0) -appEmbed.trigger(HostEvent.Navigate, { path: 'home', replace: true }); ----- -Supported embed types: `AppEmbed`. -//// - |==== == Version 1.50.x, July 2026 [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a| +|[tag greenBackground]#NEW# a| [discrete] ===== SpotterViz embed customization @@ -315,7 +178,7 @@ The Visual Embed SDK 1.50.0 introduces the `SpotterVizConfig` interface and `Spo A new `SpotterVizConfig` interface is available on `LiveboardViewConfig` and `AppViewConfig` for the `spotterViz` object. This object provides branding customization controls for customizing the SpotterViz panel experience. For more information, see xref:embed-spotterViz.adoc[SpotterViz in embedded Liveboards]. -|[tag greenBackground]#NEW FEATURE# a| +|[tag greenBackground]#NEW# a| [discrete] ===== Home page customization in full application embedding @@ -328,7 +191,7 @@ For more information, see xref:full-app-customize.adoc[Customize full applicatio [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a| +|[tag greenBackground]#NEW# a| [discrete] ===== Visual overrides for charts and tables The SDK introduces the `visualOverrides` object in `SearchViewConfig` and @@ -345,7 +208,7 @@ The `visualOverrides` object provides the following customization controls to mo * `updateMaskPaths` property for partial updates. For more information, see xref:viz-overrides.adoc[Visualization overrides]. -|[tag greenBackground]#NEW FEATURE# a| +|[tag greenBackground]#NEW# a| [discrete] ===== Liveboard browser cache refresh @@ -362,7 +225,7 @@ Action ID to show or hide the cache refresh button. For more information, see xref:embed-pinboard.adoc#liveboard-data-cache[Enable Liveboard refresh]. -|[tag greenBackground]#NEW FEATURE# a| +|[tag greenBackground]#NEW# a| [discrete] ===== Spotter file upload The SDK introduces the following configuration parameters in `SpotterChatConfig` object to enable and control file uploads in the embedded Spotter chat interface. @@ -380,7 +243,7 @@ For more information, see xref:embed-spotter.adoc#fileUpload[Allowing file uploa == Version 1.48.x, May 2026 [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a| +|[tag greenBackground]#NEW# a| [discrete] ===== Liveboard embedding The SDK includes the following new features and enhancements in Liveboard embedding. @@ -419,7 +282,7 @@ Programmatically triggers the Send now action to send a test email notification * `Action.SendTestScheduleEmail` + Action ID to disable, show, or hide the **Send now** button on the Liveboard schedule page. -|[tag greenBackground]#NEW FEATURE# a| +|[tag greenBackground]#NEW# a| [discrete] ===== Spotter embedding @@ -433,7 +296,7 @@ For the connectors panel section in the Spotter chat interface. * `Action.SpotterChatModeSwitcher` + For the mode switcher in the Spotter chat interface. -|[tag greenBackground]#NEW FEATURE# a| +|[tag greenBackground]#NEW# a| [discrete] ===== Event handling @@ -453,7 +316,7 @@ host event has been updated to include a `type` discriminator field, making it consistent with the shape of other host event responses. It now returns `{ data: { v2Content }, type }` instead of `{ v2Content }` directly. This enhancement introduces a breaking change for any code that reads `result.v2Content` directly. Update your integration workflows to use `result.data.v2Content`. -|[tag greenBackground]#NEW FEATURE# a| +|[tag greenBackground]#NEW# a| [discrete] ===== Personalized View selection via host event @@ -480,7 +343,7 @@ The following events are deprecated and replaced with new event IDs. == Version 1.47.x, April 2026 [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a| **Spotter chat history sidebar customization** +|[tag greenBackground]#NEW# a| **Spotter chat history sidebar customization** The SDK introduces the `SpotterSidebarViewConfig` interface and the `spotterSidebarConfig` object with configuration controls to customize the appearance and contents of the chat history panel. Developers can use the following properties in the `spotterSidebarConfig` object to enable or disable chat history panel and customize the contents of the sidebar when enabled: @@ -535,7 +398,7 @@ spotterSidebarConfig: { } ---- -|[tag greenBackground]#NEW FEATURE# a| **Spotter chat UI branding** +|[tag greenBackground]#NEW# a| **Spotter chat UI branding** The SDK introduces the `SpotterChatViewConfig` interface for customizing branding in Spotter tool response cards. You can pass these parameters as the `spotterChatConfig` object properties in `SpotterEmbed`, `AppEmbed`, or `LiveboardEmbed` where Spotter interface is used. @@ -550,7 +413,7 @@ Custom label to replace the `ThoughtSpot` prefix in tool response cards. Set to These settings do not affect the external MCP tool branding. ==== -|[tag greenBackground]#NEW FEATURE# a|**Liveboard embed enhancements** +|[tag greenBackground]#NEW# a|**Liveboard embed enhancements** Personalized Liveboard view:: @@ -560,7 +423,7 @@ Centralized Liveboard filter setting:: When set to `true`, the `isCentralizedLiveboardFilterUXEnabled` enables displaying a unified modal to manage and update multiple filters at once, replacing the older individual filter interactions. This feature is disabled by default on ThoughtSpot Embedded instances. -|[tag greenBackground]#NEW FEATURE# a|**Option to include current period in rolling date filters** +|[tag greenBackground]#NEW# a|**Option to include current period in rolling date filters** If the current period inclusion in rolling date filters feature is enabled on your instance, the rolling date filters options such as **Last ** and **Next ** for the Liveboards and Answers in the embed view will allow you to include current period. For example, when you define a date range such as "Last 2 months", the date filter interface displays the **Include this month** checkbox. To disable this feature, use the `isThisPeriodInDateFiltersEnabled` setting. To hide, show, or disable this option in the embed view, use the action ID, `Action.IncludeCurrentPeriod`. @@ -571,7 +434,7 @@ To disable this feature, use the `isThisPeriodInDateFiltersEnabled` setting. To [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a| **Host events with page context framework** +|[tag greenBackground]#NEW# a| **Host events with page context framework** The Visual Embed SDK introduces the HostEvent V2 framework for improved handling and execution of host events in embedded ThoughtSpot experiences with multi-layer UI interactions. The v2 framework supports the page context feature, which tracks the top-most active layer in the user's current context. Developers can use this feature to route events based on the user's current context or set a specific target context for precise and predictable handling of host events. @@ -585,7 +448,7 @@ For more information, refer to the xref:events-context-aware-routing.adoc[Host e The `dataPanelV2` parameter is deprecated and can no longer be used to switch between the classic and new data panel experience. By default, the new data panel v2 experience is enabled on all ThoughtSpot embedded instances. -|[tag greenBackground]#NEW FEATURE# a| **Spotter experience** +|[tag greenBackground]#NEW# a| **Spotter experience** The SDK includes the following parameters, action IDs, and events to customize the Spotter embed experience. Chat history sidebar customization:: @@ -616,11 +479,11 @@ Is emitted when a saved chat is deleted. * `EmbedEvent.SpotterConversationSelected` + Is emitted when a saved chat is selected in the chat history sidebar. -|[tag greenBackground]#NEW FEATURE# | `enableLinkOverridesV2` + +|[tag greenBackground]#NEW# | `enableLinkOverridesV2` + Use this configuration setting to override ThoughtSpot URLs on hover or when opening in a new tab. This is recommended over the earlier `linkOverride` flag for a better user experience. -|[tag greenBackground]#NEW FEATURE# a| **Liveboard experience enhancements** +|[tag greenBackground]#NEW# a| **Liveboard experience enhancements** * The `isLiveboardXLSXCSVDownloadEnabled` attribute adds XLSX and CSV to the available Liveboard download formats. * The `isGranularXLSXCSVSchedulesEnabled` attribute allows you to include the entire Liveboard, specific visualizations, or only tables and pivot tables in the XLSX and CSV schedules. @@ -630,7 +493,7 @@ Use this configuration setting to override ThoughtSpot URLs on hover or when ope [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a| **Spotter enhancements** +|[tag greenBackground]#NEW# a| **Spotter enhancements** You can now embed the Spotter 3 experience in your application and use features such as Auto mode for automatic data model selection, chat history, and a new chat prompt interface. @@ -651,7 +514,7 @@ Events:: On Spotter embed deployments running version 26.2.0.cl or later, the *Add to Coaching* feature is enabled by default. To disable or hide the *Add to Coaching* button, use the xref:Action.adoc#_inconversationtraining[InConversationTraining] action ID. ==== -|[tag greenBackground]#NEW FEATURE# a| **Liveboard experience enhancements** + +|[tag greenBackground]#NEW# a| **Liveboard experience enhancements** + Styling and grouping:: @@ -669,7 +532,7 @@ For more information, see link:https://docs.thoughtspot.com/cloud/latest/securit + The `showMaskedFilterChip` setting is also available in full application embedding. -|[tag greenBackground]#NEW FEATURE# a| **Publishing objects** +|[tag greenBackground]#NEW# a| **Publishing objects** The following action IDs are available for the data publishing menu actions in the *Data workspace* page: @@ -677,7 +540,7 @@ The following action IDs are available for the data publishing menu actions in t * `Action.ManagePublishing` for *Manage publishing* * `Action.Unpublish` for *Unpublish* * `Action.Parameterize` for *Parameterize* -|[tag greenBackground]#NEW FEATURE# a| **Error handling improvements** +|[tag greenBackground]#NEW# a| **Error handling improvements** To handle errors in the embedding workflows, the SDK includes the following features: @@ -698,7 +561,7 @@ For more information, see link:https://developers.thoughtspot.com/docs/Enumerati The `defaultHeight` parameter is deprecated in Visual Embed SDK v1.44.2 and later. To set the minimum height of the embed container for ThoughtSpot components such as a Liveboard, use the `minimumHeight` attribute instead. -|[tag greenBackground]#NEW FEATURE# a| *Intercepting API calls* + +|[tag greenBackground]#NEW# a| *Intercepting API calls* + The SDK provides the following attributes to intercept API calls and handle interception via events and custom workflows: //* `enableApiIntercept` + @@ -719,7 +582,7 @@ For more information, see xref:api-intercept.adoc[Intercept API calls and search == Version 1.43.0, November 2025 [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a| *Code-based custom actions* +|[tag greenBackground]#NEW# a| *Code-based custom actions* The following enumerations are available for code-based custom actions: @@ -727,7 +590,7 @@ The following enumerations are available for code-based custom actions: To define the target object for the custom action, such as on a Liveboard, visualization, Answer, or in Spotter. * `CustomActionsPosition` + To define the position of the custom action in the target object, such as primary menu, **More** options menu image:./images/icon-more-10px.png[the more options menu], or the contextual menu. -|[tag greenBackground]#NEW FEATURE# | *Attribute to set Parameter chip visibility during overrides* + +|[tag greenBackground]#NEW# | *Attribute to set Parameter chip visibility during overrides* + The `HostEvent.UpdateParameters` event now supports configuring the `isVisibleToUser` attribute to show or hide the Parameter chips after an override. For more information, see xref:runtime-parameters.adoc#_show_or_hide_parameter_chips_in_embedded_sessions[Show or hide Parameter chips in embedded sessions]. |==== @@ -735,14 +598,14 @@ The `HostEvent.UpdateParameters` event now supports configuring the `isVisibleTo [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a|*Runtime overrides in Spotter embed* +|[tag greenBackground]#NEW# a|*Runtime overrides in Spotter embed* The Visual Embed SDK now supports runtime overrides in Spotter embed. * To apply runtime filters, use the `runtimeFilters` object * To apply runtime Parameters, use the `runtimeParameters` object. -|[tag greenBackground]#NEW FEATURE# a|*PNG images in Liveboard schedule notifications* + +|[tag greenBackground]#NEW# a|*PNG images in Liveboard schedule notifications* + To enable embedding PNG images of Liveboards in scheduled job notifications sent to subscribers, the SDK provides the `isPNGInScheduledEmailsEnabled` boolean parameter. When set to true, scheduled emails will include a PNG image of the Liveboard. The SDK also provides the following action IDs: @@ -751,7 +614,7 @@ The SDK also provides the following action IDs: Adds the option to include a PNG screenshot in the notification email body when scheduling emails in ThoughtSpot. * `Action.RemoveAttachment` + Allows the user to remove an attachment from the email configuration in the schedule email dialog. -|[tag greenBackground]#NEW FEATURE# a|*Spotter embed* +|[tag greenBackground]#NEW# a|*Spotter embed* Action IDs:: The following action IDs are available for Spotter embedding and are currently supported only in the `hiddenActions` array: @@ -768,13 +631,13 @@ Action ID to enable or disable the link:https://docs.thoughtspot.com/cloud/lates [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a|*React component for Spotter Agent embed* +|[tag greenBackground]#NEW# a|*React component for Spotter Agent embed* The Visual Embed SDK now supports embedding Spotter Agent feature without a body or Spotter interface in a React app. For ease of implementation, the SDK also provides a custom React hook, `useSpotterAgent`. For more information, see xref:embed-ts-react-app.adoc#_embed_spotter_agent_in_your_own_app[Spotter Agent embedding in a React app]. -|[tag greenBackground]#NEW FEATURE# a|*Event handlers for Spotter embed* +|[tag greenBackground]#NEW# a|*Event handlers for Spotter embed* The following event handlers are now available for Spotter embed: @@ -793,7 +656,7 @@ Triggers the action to get TML representation of a Spotter-generated Answer. For more information, see xref:EmbedEvent.adoc[EmbedEvent] and xref:HostEvent.adoc[HostEvent]. -|[tag greenBackground]#NEW FEATURE# a|*Event handlers for Spotter Agent embed* +|[tag greenBackground]#NEW# a|*Event handlers for Spotter Agent embed* You can now use the following host events in Spotter Agent embedding: @@ -812,7 +675,7 @@ Triggers the *Save* action for a Spotter-generated Answer. For more information, see xref:HostEvent.adoc[HostEvent]. -|[tag greenBackground]#NEW FEATURE# a| *Lazy loading of visualizations on an embedded Liveboard* +|[tag greenBackground]#NEW# a| *Lazy loading of visualizations on an embedded Liveboard* You can now use the `lazyLoadingForFullHeight` parameter with the `fullHeight` to progressively load visualizations on an embedded Liveboard. When both these attributes are enabled, only the visualizations in the current viewport are loaded initially, while the other visualizations load as the user scrolls the Liveboard page. @@ -820,7 +683,7 @@ You can also set the margin property for lazy loading to define when the visuali For more information, see xref:lazy-loading-fullheight.adoc[Lazy loading of visualizations in an embedded Liveboard]. -|[tag greenBackground]#NEW FEATURE# a| *Full application embed* + +|[tag greenBackground]#NEW# a| *Full application embed* + You can now enable the persona-based left navigation panel and home page experience on your ThoughtSpot instance. This feature is disabled by default on ThoughtSpot instances and is available for Early Access. When it's enabled on your ThoughtSpot instance, you can roll out the new experience on embedding applications by configuring the xref:AppViewConfig.adoc#_discoveryexperience[`discoveryExperience`] attribute. @@ -831,22 +694,22 @@ When enabled, the left navigation panel organizes the application menu into pers [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a| *Fullscreen presentation mode controls for embedded Liveboards and visualizations* + +|[tag greenBackground]#NEW# a| *Fullscreen presentation mode controls for embedded Liveboards and visualizations* + Developers can now control whether a visualization or Liveboard can be presented in full screen mode using the `disableFullscreenPresentation` attribute. By default, the full screen mode is disabled on embedded Liveboards and visualizations. -|[tag greenBackground]#NEW FEATURE# a| *PDF download settings* + +|[tag greenBackground]#NEW# a| *PDF download settings* + Developers can now control the display of *Include cover page* and *Include filter page(s)* options on the Download PDF dialog for Liveboards. The *Include cover page* and *Include filter page(s)* options are disabled by default on ThoughtSpot instances. When this feature is enabled, developers can use the `coverAndFilterOptionInPDF` attribute to show or hide these options for the Liveboard users in their embedding app. -|[tag greenBackground]#NEW FEATURE# a| *Parameter for overriding a default primary action* + +|[tag greenBackground]#NEW# a| *Parameter for overriding a default primary action* + If Spotter is enabled on your instance, the *Spotter* button appears by default as the primary action on embedded Liveboard charts; if Spotter is not enabled, the *Explore* button is set as the primary action. If you want to replace the primary action with a different action, you can now use the `primaryAction` attribute. For more information, see xref:embed-actions.adoc#_override_default_primary_actions[Override default primary action]. -|[tag greenBackground]#NEW FEATURE# a| *Full application embed experience enhancements* + +|[tag greenBackground]#NEW# a| *Full application embed experience enhancements* + The SDK now includes the `hideObjectSearch` property, which allows developers to hide the object search button in the navigation bar when embedding the full application. -|[tag greenBackground]#NEW FEATURE# a| *Host events* + +|[tag greenBackground]#NEW# a| *Host events* + In this version, the SDK introduces the following host event handlers: @@ -865,7 +728,7 @@ Triggers the delete prompt action. For more information, see xref:HostEvent.adoc[HostEvent]. -|[tag greenBackground]#NEW FEATURE# a|*Events support for Spotter embed* +|[tag greenBackground]#NEW# a|*Events support for Spotter embed* You can now use the following host events in Spotter embed: @@ -881,7 +744,7 @@ You can now use the following host events in Spotter embed: For more information, see xref:HostEvent.adoc[HostEvent]. -|[tag greenBackground]#NEW FEATURE# a| *Lazy loading with full height* +|[tag greenBackground]#NEW# a| *Lazy loading with full height* The SDK introduces `lazyLoadingForFullHeight` parameter, which enables progressive loading of visualizations on an embedded Liveboard. This parameter works in conjunction with the `fullHeight` attribute. When both these attributes are enabled, only the visualizations in the current viewport are loaded initially, while the other visualizations load as the user scrolls the Liveboard page. @@ -897,7 +760,7 @@ To use these attributes effectively in embedded applications, your ThoughtSpot i [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a| *Spotter embed components with new names* + +|[tag greenBackground]#NEW# a| *Spotter embed components with new names* + The following Spotter embed components are now deprecated and replaced with new components in the SDK and Visual Embed Playground: * `ConversationEmbed` + @@ -911,13 +774,13 @@ Replaced with `SpotterAgentEmbedViewConfig` The deprecated components with old names in the existing Spotter embed implementations will continue to function until further notice. For code samples with new component names, see xref:embed-spotter.adoc[Spotter embed documentation]. -|[tag greenBackground]#NEW FEATURE# a| *Action ID for Spotter in-conversation training* + +|[tag greenBackground]#NEW# a| *Action ID for Spotter in-conversation training* + For ThoughtSpot instances that have the new Spotter in-conversation training workflow enabled, the SDK provides the action ID `Action.InConversationTraining` to manage the visibility of the *Add to Coaching* button on Answers generated from Spotter prompts. [NOTE] The *Add to Coaching* feature is currently in beta and is turned off by default on embed deployments. To enable this feature on your instance, contact ThoughtSpot Support. -|[tag greenBackground]#NEW FEATURE# a|*Events support for Spotter embed* +|[tag greenBackground]#NEW# a|*Events support for Spotter embed* New embed events:: @@ -971,7 +834,7 @@ For more information, see xref:EmbedEvent.adoc[EmbedEvent]. [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a| *String IDs for text customization* + +|[tag greenBackground]#NEW# a| *String IDs for text customization* + Developers can now customize a specific occurrence of a visible text string in the ThoughtSpot UI using the `stringIDs` object in the customization interface. To locate the string IDs, SDK provides the `exposeTranslationIds` attribute. By setting `exposeTranslationIds` to `true` in the Playground, you can find the string ID of the UI text and use it in your customization code. @@ -980,7 +843,7 @@ Additionally, the SDK provides the `StringIDsUrl` attribute to allow using a JSO For more information, see xref:customize-text-strings.adoc[Customize text strings]. -|[tag greenBackground]#NEW FEATURE# a| *Hide columns on list pages* + +|[tag greenBackground]#NEW# a| *Hide columns on list pages* + In full app embedding, you can now hide the following columns on the *Liveboards* and *Answers* listing pages using the `hiddenListColumns` array: @@ -1002,16 +865,16 @@ For more information, see xref:full-app-customize.adoc#_hide_columns_on_list_pag [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a| +|[tag greenBackground]#NEW# a| The SDK now provides the `customVariablesForThirdPartyTools` setting to pass custom variables when integrating third-party tools and running custom scripts in your embed. Developers can define this object in the **init()** function and add variables as key-value pairs. This feature is available only if third-party integration is enabled on your instance and the script hosting domain URL is added to the CSP allowlist. For more information, see xref:3rd-party-script.adoc[Integrate third-party tools and allow custom scripts]. -|[tag greenBackground]#NEW FEATURE# a| +|[tag greenBackground]#NEW# a| You can now exclude search token string from the application URL by setting `excludeSearchTokenStringFromURL` to `true` in your embed with ThoughtSpot token-based Search or Search bar. -|[tag greenBackground]#NEW FEATURE# a| This version of the SDK supports the following embed and host events: +|[tag greenBackground]#NEW# a| This version of the SDK supports the following embed and host events: Embed Events:: @@ -1034,7 +897,7 @@ Triggers the *Delete* action on a Liveboard. [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a| +|[tag greenBackground]#NEW# a| The following HostEvents now allow custom parameters to set object properties programmatically: * `HostEvent.SaveAnswer` + @@ -1044,7 +907,7 @@ Allows adding custom properties for visualization ID, name, and description, Liv For more information, see xref:events-hostEvents.adoc#hostEventParameterization[Host Events] documentation. -|[tag greenBackground]#NEW FEATURE# a| +|[tag greenBackground]#NEW# a| New configuration attributes:: @@ -1086,7 +949,7 @@ The following new CSS variables are available for Spotter interface customizatio * `--ts-var-spotter-prompt-background` For more information about Spotter customization, see xref:embed-spotter.adoc#SpotterCSS[Customize styles]. -|[tag greenBackground]#NEW FEATURE# a| +|[tag greenBackground]#NEW# a| Configuration attributes:: @@ -1110,7 +973,7 @@ ID for the action that disables filter chip reordering. [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a| +|[tag greenBackground]#NEW# a| The SDK now provides the `isUnifiedSearchExperienceEnabled` setting to customize the Search experience on ThoughtSpot Home page for embedding application users: * When set to `true`, the split search experience is disabled and the Search bar on the Home page functions as Natural Language Search interface @@ -1118,14 +981,14 @@ The SDK now provides the `isUnifiedSearchExperienceEnabled` setting to customize For more information, see xref:full-app-customize.adoc#_search_components[Search interface on the Home page in full application embedding]. -|[tag greenBackground]#NEW FEATURE# a| The `overrideOrgId` parameter in the SDK provides the ability to override Org context for embedding application users. This parameter allows users authenticated to an Org to temporarily view content from another Org. Before specifying the Org ID for override, make sure the Per Org URL feature is enabled on your ThoughtSpot instance. To enable Per Org URL on your instance, contact ThoughtSpot Support. +|[tag greenBackground]#NEW# a| The `overrideOrgId` parameter in the SDK provides the ability to override Org context for embedding application users. This parameter allows users authenticated to an Org to temporarily view content from another Org. Before specifying the Org ID for override, make sure the Per Org URL feature is enabled on your ThoughtSpot instance. To enable Per Org URL on your instance, contact ThoughtSpot Support. |==== == Version 1.34.0, November 2024 [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a| You can now embed the following ThoughtSpot Spotter components in your app: +|[tag greenBackground]#NEW# a| You can now embed the following ThoughtSpot Spotter components in your app: * `SpotterEmbed` + Embeds Spotter conversation interface in your app @@ -1134,7 +997,7 @@ Creates a conversation component without the body, which can be integrated into For more information, see xref:embed-spotter.adoc[Embed Spotter] and xref:spotter-in-custom-chatbot.adoc[Integrate Spotter into your chatbot]. -|[tag greenBackground]#NEW FEATURE# a|The following parameters and enumerations are available for customizing Liveboard experience: +|[tag greenBackground]#NEW# a|The following parameters and enumerations are available for customizing Liveboard experience: * `showLiveboardVerifiedBadge` + Shows or hides the Liveboard verified badge. Available if the Liveboard compact header feature is enabled. @@ -1143,16 +1006,16 @@ Shows or hides the re-verify banner. Available if the Liveboard compact header f * `Action.KPIAnalysisCTA` + Action ID to show, hide, or disable the **Analyze CTA** action on a KPI chart. -|[tag greenBackground]#NEW FEATURE# |You can now use the `HostEvent.GetIframeUrl` to get the iframe src URL from the Visual Embed Playground. If you are embedding ThoughtSpot in apps like Salesforce and Sharepoint without the SDK, use this event to generate the iframe URL. +|[tag greenBackground]#NEW# |You can now use the `HostEvent.GetIframeUrl` to get the iframe src URL from the Visual Embed Playground. If you are embedding ThoughtSpot in apps like Salesforce and Sharepoint without the SDK, use this event to generate the iframe URL. -|[tag greenBackground]#NEW FEATURE# a|The following parameters are available for customizing Search experience: +|[tag greenBackground]#NEW# a|The following parameters are available for customizing Search experience: * `collapseDataPanel` Minimizes the data panel view. Users can click the data panel header any time to expand the panel. * `collapseSearchBar` Sets the initial state of the search bar when embedding a saved Answer. -|[tag greenBackground]#NEW FEATURE# a| The following settings are available for customizing the new home page and navigation experience in full app embedding: +|[tag greenBackground]#NEW# a| The following settings are available for customizing the new home page and navigation experience in full app embedding: * `HomeLeftNavItem.LiveboardSchedules` + The Liveboard schedules menu on the left navigation panel. @@ -1175,7 +1038,7 @@ To show, disable, or hide the *Unsubscribe* action on the *Liveboard schedules* [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a| You can now customize the search experience for the embedded ThoughtSpot **Home** page using `homePageSearchBarMode`. By default, the **Home** page includes the Object Search bar, which allows finding popular Liveboards and Answers. +|[tag greenBackground]#NEW# a| You can now customize the search experience for the embedded ThoughtSpot **Home** page using `homePageSearchBarMode`. By default, the **Home** page includes the Object Search bar, which allows finding popular Liveboards and Answers. You can set the `homePageSearchBarMode` property to one of the following options: @@ -1185,8 +1048,8 @@ Displays the search bar for Natural Language Search. Hides the Search bar on the **Home** page. Note that it only hides the Search bar on the **Home** page and doesn't affect the Object Search bar visibility on the top navigation bar. ** `objectSearch` (default) + Displays Object Search bar on the **Home** page. -|[tag greenBackground]#NEW FEATURE# a|The SDK now allows you to set the focus on the Search bar or outside the Search bar when rendering the embedded Search page. Use the `focusSearchBarOnRender` property to set the position of the cursor focus. -|[tag greenBackground]#NEW FEATURE# a| The SDK includes the following Event and Action enumeration members: +|[tag greenBackground]#NEW# a|The SDK now allows you to set the focus on the Search bar or outside the Search bar when rendering the embedded Search page. Use the `focusSearchBarOnRender` property to set the position of the cursor focus. +|[tag greenBackground]#NEW# a| The SDK includes the following Event and Action enumeration members: Events:: @@ -1206,7 +1069,7 @@ Use this action enumeration to disable, show, or hide the **Manage tags** button [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a| The following new action enumerations are available in this version: + +|[tag greenBackground]#NEW# a| The following new action enumerations are available in this version: + * `Action.CreateLiveboard` for the *Create Liveboard* menu action on the Liveboards lists page. + * `Action.SyncToTeams` for the **Sync to Teams** menu action on Liveboard visualizations. @@ -1216,26 +1079,26 @@ Use this action enumeration to disable, show, or hide the **Manage tags** button * `Action.AddDataPanelObjects` for the **Add** menu that includes sub-menu options such as Formulas, Parameters, Query set, and Column set actions. * `Action.OrganiseFavourites` for the **Organize** action above the Favorites panel on the modular Homepage (New experience) For more information, see xref:Action.adoc[Actions]. -|[tag greenBackground]#NEW FEATURE#| Developers can now use the `disableRedirectionLinksInNewTab` parameter to disable links and redirection of links in the embedded view. -|[tag greenBackground]#NEW FEATURE# a|You can now enable `enable2ColumnLayout` on a Liveboard to adjust the page view according to the width and resolution of users' devices. +|[tag greenBackground]#NEW#| Developers can now use the `disableRedirectionLinksInNewTab` parameter to disable links and redirection of links in the embedded view. +|[tag greenBackground]#NEW# a|You can now enable `enable2ColumnLayout` on a Liveboard to adjust the page view according to the width and resolution of users' devices. || |==== == Version 1.31.x, July 2024 [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a| Runtime filters + +|[tag greenBackground]#NEW# a| Runtime filters + * `NOT_IN` operator for Runtime filters. For more information, see xref:runtime-filters.adoc#runtimeFilterOp[Runtime filters]. * `excludeRuntimeParametersfromURL` parameter to exclude or remove runtimeParameters from the URL. -|[tag greenBackground]#NEW FEATURE# |For performance optimization, developers can choose to load embedded views in a lightweight V2 shell by setting `enableV2Shell_experimental` to `true`. +|[tag greenBackground]#NEW# |For performance optimization, developers can choose to load embedded views in a lightweight V2 shell by setting `enableV2Shell_experimental` to `true`. |==== == Version 1.30.0, June 2024 [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a| **CSS variables for new homepage experience** +|[tag greenBackground]#NEW# a| **CSS variables for new homepage experience** * `--ts-var-home-watchlist-selected-text-color` + * `--ts-var-home-card-color` + @@ -1250,7 +1113,7 @@ For more information, see xref:css-customization.adoc#_homepage_modules_new_expe [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a| **Ask Sage** +|[tag greenBackground]#NEW# a| **Ask Sage** With Ask Sage [beta betaBackground]^Beta^ embedded application users can ask follow-up questions on a visualization generated from a Natural Language Search query, converse with AI analyst, and refine results. To enable this feature, set `enableAskSage` to `true`. @@ -1281,11 +1144,11 @@ Updates cross filters applied on a Liveboard. [width="100%" cols="1,4"] |===== -|[tag greenBackground]#NEW FEATURE# a| The SDK includes the following new enumeration members in v1.28.0: +|[tag greenBackground]#NEW# a| The SDK includes the following new enumeration members in v1.28.0: ** `Action.VerifiedLiveboard` + Can be used to show or hide the *Verified Liveboard* banner. -|[tag greenBackground]#NEW FEATURE# a| To access the new Home page and global navigation experience in the full application embedding, you can use the `modularHomeExperience` property in the SDK. The modular homepage experience is turned off by default and is available as an Early Access feature in 9.12.5.cl release. When `modularHomeExperience` is set to `true`, you can use the following parameters in the SDK to control the application experience: +|[tag greenBackground]#NEW# a| To access the new Home page and global navigation experience in the full application embedding, you can use the `modularHomeExperience` property in the SDK. The modular homepage experience is turned off by default and is available as an Early Access feature in 9.12.5.cl release. When `modularHomeExperience` is set to `true`, you can use the following parameters in the SDK to control the application experience: * `hiddenhomeleftnavitems` * `hiddenhomepagemodules` @@ -1296,11 +1159,11 @@ Can be used to show or hide the *Verified Liveboard* banner. * `HomeLeftNavItem` For more information, see xref:full-app-customize.adoc[Customize full application embedding] and xref:AppViewConfig.adoc[AppViewConfig]. -|[tag greenBackground]#NEW FEATURE# a| The following embed event is available from the v1.28.0 onwards: +|[tag greenBackground]#NEW# a| The following embed event is available from the v1.28.0 onwards: `EmbedEvent.Rename` + Emits when an embedded Liveboard or visualization is renamed. -|[tag greenBackground]#NEW FEATURE# a| TML actions +|[tag greenBackground]#NEW# a| TML actions The following TML menu actions are now grouped under the **TML** sub-menu of the **More** image:./images/icon-more-10px.png[the more options menu] menu on Answer page. @@ -1327,10 +1190,10 @@ hiddenActions: [Action.TML] // to disable all TML actions disabledActions: [Action.TML] ---- -|[tag greenBackground]#NEW FEATURE# | You can now reset authentication token and fetch a new token for new authentication requests. +|[tag greenBackground]#NEW# | You can now reset authentication token and fetch a new token for new authentication requests. For more information, see link:https://developers.thoughtspot.com/docs/Function_resetCachedAuthToken[resetCachedAuthToken]. -|[tag greenBackground]#NEW FEATURE#| You can now override the default number, date, and currency format defined by your locale settings. To override the default settings, use the following parameters: +|[tag greenBackground]#NEW#| You can now override the default number, date, and currency format defined by your locale settings. To override the default settings, use the following parameters: * `numberFormatLocale` + * `dateFormatLocale` + @@ -1338,7 +1201,7 @@ For more information, see link:https://developers.thoughtspot.com/docs/Function_ For more information, see xref:locale-setting.adoc#_set_locale_in_the_sdk[Customize locale]. -|[tag greenBackground]#NEW FEATURE# |Tokenized fetch + +|[tag greenBackground]#NEW# |Tokenized fetch + The SDK now provides a fetch wrapper that adds the authentication token to the API requests. For more information, see link:https://developers.thoughtspot.com/docs/Function_tokenizedFetch#_tokenizedfetch[tokenizedFetch]. |===== @@ -1347,7 +1210,7 @@ For more information, see link:https://developers.thoughtspot.com/docs/Function_ [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a| The following action enumeration members are available from v1.27.9 and v1.27.10: +|[tag greenBackground]#NEW# a| The following action enumeration members are available from v1.27.9 and v1.27.10: * `Action.AIHighlights` * `Action.AddToWatchlist` @@ -1355,14 +1218,14 @@ For more information, see link:https://developers.thoughtspot.com/docs/Function_ * `Action.CopyKpiLink` For more information, see xref:Action.adoc[Action]. -| [tag greenBackground]#NEW FEATURE# a| You can now use `HostEvent.GetAnswerSession` to get Answer session data for a Search Answer or Liveboard Visualization in the embedded view. +| [tag greenBackground]#NEW# a| You can now use `HostEvent.GetAnswerSession` to get Answer session data for a Search Answer or Liveboard Visualization in the embedded view. |==== == Version 1.27.0, January 2024 [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a|The `SageEmbed` package is now available on all clusters. You can use this SDK package to embed Natural Language Search capabilities and assist users with AI-suggested queries and AI-generated answers. This SDK package also allows you to customize the Natural Language Search experience in the embedded view. +|[tag greenBackground]#NEW# a|The `SageEmbed` package is now available on all clusters. You can use this SDK package to embed Natural Language Search capabilities and assist users with AI-suggested queries and AI-generated answers. This SDK package also allows you to customize the Natural Language Search experience in the embedded view. For a complete list of methods, functions, interface objects, and properties, see the following pages: + @@ -1371,7 +1234,7 @@ For a complete list of methods, functions, interface objects, and properties, se |[tag orangeBackground]#MODIFIED# a| The `HostEvent.DrillDown` now supports the `vizId` parameter to trigger a drill-down action on a specific visualization of a Liveboard. For more information, see xref:HostEvent.adoc#_drilldown[DrillDown]. -|[tag greenBackground]#NEW FEATURE# a| The new version of the SDK introduces the following new enumeration members: +|[tag greenBackground]#NEW# a| The new version of the SDK introduces the following new enumeration members: * Host Events ** `HostEvent.UpdateSageQuery` + @@ -1387,10 +1250,10 @@ Emitted when a user creates a new Worksheet. [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a| The SDK provides `AnswerService` class to trigger the answer service with a custom action payload. +|[tag greenBackground]#NEW# a| The SDK provides `AnswerService` class to trigger the answer service with a custom action payload. You can use this service to run GraphQL queries in the context of the Answer with a custom action trigger. For more information, see link:https://developers.thoughtspot.com/docs/Class_AnswerService[AnswerService]. Recommended ThoughtSpot application version is 9.10.0.cl. -|[tag greenBackground]#NEW FEATURE# a|The following object properties and feature flags are introduced in the `LiveboardEmbed` and `AppEmbed` SDK packages: +|[tag greenBackground]#NEW# a|The following object properties and feature flags are introduced in the `LiveboardEmbed` and `AppEmbed` SDK packages: * `showLiveboardDescription` + Shows the Liveboard description text when set to `true` @@ -1405,9 +1268,9 @@ Hides the specified tabs from the Liveboard page * `visibleTabs` + Displays the specified tabs on the Liveboard page -|[tag greenBackground]#NEW FEATURE# |You can now enable the new data panel experience by setting `dataPanelV2` to `true` in the SDK when embedding ThoughtSpot Search. The new data panel experience is turned off by default on embedded ThoughtSpot instances. +|[tag greenBackground]#NEW# |You can now enable the new data panel experience by setting `dataPanelV2` to `true` in the SDK when embedding ThoughtSpot Search. The new data panel experience is turned off by default on embedded ThoughtSpot instances. -|[tag greenBackground]#NEW FEATURE# a|The new version of the SDK supports the following events: +|[tag greenBackground]#NEW# a|The new version of the SDK supports the following events: Embed events:: * `EmbedEvent.hiddenTabs` @@ -1431,7 +1294,7 @@ Host events:: + For more information, see xref:HostEvent.adoc[HostEvent]. -|[tag greenBackground]#NEW FEATURE# a| The SDK introduces the following action enumeration members: +|[tag greenBackground]#NEW# a| The SDK introduces the following action enumeration members: * `Action.AddTab` + Show, disable, or hide the **Add Tab** action on a Liveboard. @@ -1451,10 +1314,10 @@ For more information, see xref:Action.adoc[Actions]. [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# | The SDK now supports runtime Parameter overrides on Liveboards and Answers. +|[tag greenBackground]#NEW# | The SDK now supports runtime Parameter overrides on Liveboards and Answers. For more information, see xref:runtime-parameters.adoc#_apply_parameter_overrides_using_visual_embed_sdk[Runtime Parameter overrides]. -|[tag greenBackground]#NEW FEATURE# a| The SDK introduces the following action enumeration members: +|[tag greenBackground]#NEW# a| The SDK introduces the following action enumeration members: * `Action.RenameModalTitleDescription` * `Action.EnableContextualChangeAnalysis` @@ -1468,22 +1331,22 @@ For more information, see xref:Action.adoc[Actions]. [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a| ThoughtSpot now provides the `SageEmbed` package to embed the ThoughtSpot Search page with Sage features such as natural language search and AI-suggested search examples. This feature is in beta and not available in the Visual Embed Playground. -|[tag greenBackground]#NEW FEATURE# a| The `HostEvent.SetActiveTab` event in the upcoming version of the SDK allows you to set a tab as an active tab on a Liveboard. +|[tag greenBackground]#NEW# a| ThoughtSpot now provides the `SageEmbed` package to embed the ThoughtSpot Search page with Sage features such as natural language search and AI-suggested search examples. This feature is in beta and not available in the Visual Embed Playground. +|[tag greenBackground]#NEW# a| The `HostEvent.SetActiveTab` event in the upcoming version of the SDK allows you to set a tab as an active tab on a Liveboard. |==== == Version 1.23.0, August 2023 [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a| The SDK supports the following performance optimization enhancements: + +|[tag greenBackground]#NEW# a| The SDK supports the following performance optimization enhancements: + * Ability to pre-render a generic instance of the ThoughtSpot component using the `prerenderGeneric` attribute. The generic instance uses the default host and flags and can be rendered in the background to improve application response. * Ability to use an iFrame from a pre-rendered iFrame pool using the `usePrerenderedIfAvailable` attribute. |==== //// -|[tag greenBackground]#NEW FEATURE# a| New events for Liveboard filters + +|[tag greenBackground]#NEW# a| New events for Liveboard filters + * `EmbedEvent.FilterChanged` + * `HostEvent.GetFilters` + @@ -1494,18 +1357,18 @@ For more information, see xref:Action.adoc[Actions]. [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a| The new version of the SDK introduces the `TrustedAuthTokenCookieless` `authType` property to allow Cookieless embedding. The Cookieless authentication method allows using a bearer token to identify the signed-in user instead of session cookies. +|[tag greenBackground]#NEW# a| The new version of the SDK introduces the `TrustedAuthTokenCookieless` `authType` property to allow Cookieless embedding. The Cookieless authentication method allows using a bearer token to identify the signed-in user instead of session cookies. For more information, see xref:embed-authentication.adoc#_cookieless_authentication[Cookieless authentication]. -|[tag greenBackground]#NEW FEATURE# a|The new version of the SDK allows you to block user access to the non-embedded instance of the ThoughtSpot application. In full app embed deployments, you can use the `blockNonEmbedFullAppAccess` property in the SDK to restrict or allow your application users from accessing ThoughtSpot pages in the non-embed mode. +|[tag greenBackground]#NEW# a|The new version of the SDK allows you to block user access to the non-embedded instance of the ThoughtSpot application. In full app embed deployments, you can use the `blockNonEmbedFullAppAccess` property in the SDK to restrict or allow your application users from accessing ThoughtSpot pages in the non-embed mode. For more information, see xref:security-settings.adoc#_block_access_to_non_embedded_thoughtspot_pages[Block access to non-embedded ThoughtSpot pages]. |==== //// -|[tag greenBackground]#NEW FEATURE# a| The SDK supports the following performance optimization enhancements: + +|[tag greenBackground]#NEW# a| The SDK supports the following performance optimization enhancements: + * Ability to pre-render a generic instance of the ThoughtSpot component using the `prerenderGeneric` attribute. The generic instance uses the default host and flags and can be rendered in the background to improve application response. * Ability to use an iFrame from a pre-rendered iFrame pool using the `usePrerenderedIfAvailable` attribute. @@ -1514,7 +1377,7 @@ For more information, see xref:security-settings.adoc#_block_access_to_non_embed == Version 1.21.0, May 2023 [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a|The new version of the SDK introduces the following action enumeration members: +|[tag greenBackground]#NEW# a|The new version of the SDK introduces the following action enumeration members: * `Action.AxisMenuAggregate` * `Action.AxisMenuConditionalFormat` @@ -1533,7 +1396,7 @@ For more information, see xref:security-settings.adoc#_block_access_to_non_embed For more information, see xref:embed-action-ref.adoc[Action reference]. -|[tag greenBackground]#NEW FEATURE# a| The SDK introduces the following events: +|[tag greenBackground]#NEW# a| The SDK introduces the following events: * `HostEvent.AddColumns` * `HostEvent.OpenFilter` @@ -1574,7 +1437,7 @@ To disable or hide download actions, you can use `Action.Download` in the `disab ** `Action.DownloadAsXlsx` + ** `Action.DownloadAsPng` -|[tag greenBackground]#NEW FEATURE# a| The SDK includes new attributes to customize the experience for embedded app users: +|[tag greenBackground]#NEW# a| The SDK includes new attributes to customize the experience for embedded app users: * `linkOverride` + @@ -1587,7 +1450,7 @@ Allows triggering contextual menu on the Liveboard visualizations and Answers fr * `hideSearchBar` + Allows hiding the Search bar on the embedded Search page. -|[tag greenBackground]#NEW FEATURE# | The SDK now allows setting the loading preference for embedded iFrames. +|[tag greenBackground]#NEW# | The SDK now allows setting the loading preference for embedded iFrames. For performance optimization, you can set the `loading` attribute to `lazy` in the `FrameParams` property. |==== @@ -1596,14 +1459,14 @@ For performance optimization, you can set the `loading` attribute to `lazy` in t [width="100%" cols="1,4"] |==== |[tag redBackground]#DEPRECATED# a|The `dataSources` property in `SearchEmbed` and `SearchBarEmbed` is deprecated and replaced with the `dataSource` attribute. The SDK supports searching from a single data source only. -|[tag greenBackground]#NEW FEATURE# a|The embed SDK packages now include the `insertAsSibling` property. This attribute can be used to insert the embedded object as a sibling to the element inside the target container. +|[tag greenBackground]#NEW# a|The embed SDK packages now include the `insertAsSibling` property. This attribute can be used to insert the embedded object as a sibling to the element inside the target container. |==== == Version 1.19.0, February 2023 [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a|The `customCSS` property in the `customizations` object supports new variables to customize the styles for dialogs, search bar, search navigation and search suggestions panels. +|[tag greenBackground]#NEW# a|The `customCSS` property in the `customizations` object supports new variables to customize the styles for dialogs, search bar, search navigation and search suggestions panels. For more information, see xref:css-customization.adoc[Customize CSS]. |[tag redBackground]#BREAKING CHANGE# a|The new Liveboard experience mode introduces changes to the data format of the JSON response payload triggered by callback custom actions. For example, the `reportBookData`, and `vizData` attributes are modified, and the custom action `id` now is part of the data attribute. These changes may break your current custom action event handlers. For interoperability, we recommend adding the data attribute to `payload` in your code as shown in the example here: @@ -1618,7 +1481,7 @@ liveboardEmbed.on(EmbedEvent.CustomAction, payload => { You may also want to update the data classes in your scripts to process the JSON response payload and handle complex data. For more information, see xref:custom-actions-callback.adoc#_define_functions_and_classes_to_handle_liveboard_data[Callback custom actions]. -|[tag greenBackground]#NEW FEATURE# a|The new version of the SDK introduces the following Host events: +|[tag greenBackground]#NEW# a|The new version of the SDK introduces the following Host events: * `HostEvent.Delete` * `HostEvent.Download` @@ -1643,17 +1506,17 @@ For more information, see xref:embed-authentication.adoc#_saml_redirection[SAML [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a|The new version of the SDK provides the `SearchBarEmbed` JavaScript package to embed only the ThoughtSpot Search bar in your app. + +|[tag greenBackground]#NEW# a|The new version of the SDK provides the `SearchBarEmbed` JavaScript package to embed only the ThoughtSpot Search bar in your app. + For more information, see xref:embed-searchbar.adoc[Embed ThoughtSpot search bar]. -|[tag greenBackground]#NEW FEATURE# a|The `customCSS` property in the `customizations` object supports new variables to customize the UI elements on Liveboard, visualization, and Answer pages. You can also use these variables to define custom styles in the CSS file. + +|[tag greenBackground]#NEW# a|The `customCSS` property in the `customizations` object supports new variables to customize the UI elements on Liveboard, visualization, and Answer pages. You can also use these variables to define custom styles in the CSS file. + For more information, see xref:css-customization.adoc[Customize CSS]. -|[tag greenBackground]#NEW FEATURE# |The new version of the SDK allows fetching TML objects via `GetTML` host event. This event is triggered when a user clicks on the *Show underlying data* action on a Liveboard visualization or Answer page. + +|[tag greenBackground]#NEW# |The new version of the SDK allows fetching TML objects via `GetTML` host event. This event is triggered when a user clicks on the *Show underlying data* action on a Liveboard visualization or Answer page. + For more information, see xref:HostEvent.adoc#_gettml[GetTML]. -|[tag greenBackground]#NEW FEATURE# a| The new version of the SDK introduces the following enums in the `Action` object: +|[tag greenBackground]#NEW# a| The new version of the SDK introduces the following enums in the `Action` object: * `Action.SyncToOtherApps` + * `Action.SyncToSheets` + @@ -1679,9 +1542,9 @@ The new version of the SDK introduces several new features and enhancements. * `AuthType.OIDC` is renamed as `AuthType.OIDCRedirect` + * `AuthType.AuthServer` is renamed to `AuthType.TrustedAuthToken` + This enhancement does not introduce any breaking changes to your current implementation. -|[tag greenBackground]#NEW FEATURE# a|To use your current SAML or OIDC authentication setup and redirect users to the IdP for authentication within the embedded iFrame, you can now use `AuthType.EmbeddedSSO`. + +|[tag greenBackground]#NEW# a|To use your current SAML or OIDC authentication setup and redirect users to the IdP for authentication within the embedded iFrame, you can now use `AuthType.EmbeddedSSO`. + For more information, see xref:embed-authentication.adoc[Authentication]. -|[tag greenBackground]#NEW FEATURE#| +|[tag greenBackground]#NEW#| The `customizations` object in the SDK allows you to specify a custom CSS URL. You can also use this object to define CSS variables directly in the `init` code. + For more information, see xref:css-customization.adoc[Customize CSS]. |==== @@ -1693,7 +1556,7 @@ The new version of the SDK includes bug fixes and improvements to the new Livebo == Version 1.15.1, September 2022 [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE#| +|[tag greenBackground]#NEW#| The `prefetch` method now supports the `url` and `prefetchFeatures` parameters. You can use these parameters to call the prefetch method before `init` and prefetch static resources on application load. + For more information, see xref:prefetch-and-cache.adoc[Prefetch static resources]. |==== @@ -1701,12 +1564,12 @@ For more information, see xref:prefetch-and-cache.adoc[Prefetch static resources == Version 1.15.0, September 2022 [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE#| +|[tag greenBackground]#NEW#| For embedded instances with the new Liveboard experience, the Visual Embed SDK provides the `activeTabId` attribute, using which you can set a Liveboard tab as an active tab. For more information, see xref:embed-pinboard.adoc#_liveboard_tabs[Customize Liveboard tabs]. -|[tag greenBackground]#NEW FEATURE# a|The new version of the SDK supports firing events for Liveboard menu actions from the host application. The SDK introduces the following host event enumeration members for Liveboard objects: +|[tag greenBackground]#NEW# a|The new version of the SDK supports firing events for Liveboard menu actions from the host application. The SDK introduces the following host event enumeration members for Liveboard objects: * CopyLink * CreateMonitor @@ -1731,7 +1594,7 @@ For more information, see xref:events-hostEvents.adoc[Events reference]. == Version 1.14.0, August 2022 [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE#| +|[tag greenBackground]#NEW#| The Visual Embed SDK now includes the `liveboardV2` attribute in the `LiveboardEmbed` package to allow developers to enable the new Liveboard experience on their embedded ThoughtSpot instance. + For more information, see xref:embed-pinboard.adoc[Embed a Liveboard]. |[tag orangeBackground]#MODIFIED#|If trusted authentication is enabled, the SDK makes a `POST` API call to get a login token and log the user into ThoughtSpot. @@ -1741,13 +1604,13 @@ The earlier versions of the SDK supported only `GET` API requests. For more info == Version 1.13.0, July 2022 [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE#| +|[tag greenBackground]#NEW#| This version of Visual Embed SDK includes the `enableSearchAssist` attribute, using which you can turn on the Search Assist feature on an embedded instance. -|[tag greenBackground]#NEW FEATURE#| The new version of SDK introduces the `AuthType.SAML` enum for SAML-based SSO authentication. Note that `AuthType.SAML` replaces the `AuthType.SSO` enum, which is deprecated in the v1.13.0 version of the SDK. + +|[tag greenBackground]#NEW#| The new version of SDK introduces the `AuthType.SAML` enum for SAML-based SSO authentication. Note that `AuthType.SAML` replaces the `AuthType.SSO` enum, which is deprecated in the v1.13.0 version of the SDK. + For more information, see xref:embed-authentication.adoc#saml-sso-embed[Authentication]. |[tag redBackground]#DEPRECATED#| The `AuthType.SSO` enum is deprecated in v1.13.0. ThoughtSpot recommends using `AuthType.SAML` for the SAML SSO authentication method. + This change does not impact your current embed implementation with `AuthType.SSO`. -|[tag greenBackground]#NEW FEATURE#| The SDK includes the `getExportRequestForCurrentPinboard` event, which is triggered when a user tries to export a Liveboard in its current state. + +|[tag greenBackground]#NEW#| The SDK includes the `getExportRequestForCurrentPinboard` event, which is triggered when a user tries to export a Liveboard in its current state. + For more information, see xref:events-hostEvents.adoc[Events reference]. |==== @@ -1755,11 +1618,11 @@ For more information, see xref:events-hostEvents.adoc[Events reference]. [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE#| +|[tag greenBackground]#NEW#| This version of Visual Embed SDK introduces the `navigate` host event, which is triggered when a user navigates to an application page without a page reload. For more information, see xref:events-hostEvents.adoc[Events reference]. -|[tag greenBackground]#NEW FEATURE# | The new `getThoughtSpotPostUrlParams` method fetches ThoughtSpot URL query parameters prefixed with `ts-`. +|[tag greenBackground]#NEW# | The new `getThoughtSpotPostUrlParams` method fetches ThoughtSpot URL query parameters prefixed with `ts-`. |==== == Version 1.11.2, June 2022 @@ -1770,14 +1633,14 @@ Bug fix for Typescript builds that affect Angular project configurations. [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE#| The SDK includes the action enum `ReportError`, using which you can turn off ThoughtSpot-specific error reporting. +|[tag greenBackground]#NEW#| The SDK includes the action enum `ReportError`, using which you can turn off ThoughtSpot-specific error reporting. |==== == Version 1.11.0, May 2022 [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a| The new version of SDK includes the following new events: +|[tag greenBackground]#NEW# a| The new version of SDK includes the following new events: * `ALL` * `AnswerChartSwitcher` @@ -1803,16 +1666,16 @@ Bug fix for Typescript builds that affect Angular project configurations. * `VizPointClick` For more information about how to register and handle these events, see xref:embed-events.adoc[Events and app integration]. -|[tag greenBackground]#NEW FEATURE# a| The new version of SDK supports the `showAlerts` attribute, using which you can show or hide alerts and error messages in the embedded view. +|[tag greenBackground]#NEW# a| The new version of SDK supports the `showAlerts` attribute, using which you can show or hide alerts and error messages in the embedded view. -|[tag greenBackground]#NEW FEATURE# a| The `Action.CreateMonitor` enumeration is available in the SDK for embedded ThoughtSpot environments on which the *Monitor* feature is enabled. +|[tag greenBackground]#NEW# a| The `Action.CreateMonitor` enumeration is available in the SDK for embedded ThoughtSpot environments on which the *Monitor* feature is enabled. For more information, see xref:embed-actions.adoc[Show or hide UI actions]. |==== == Version 1.10.4, May 2022 [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE#|The `detectCookieAccessSlow` parameter in the SDK allows your app to check if third-party cookies are enabled on the browser. This parameter is available only for trusted and `Basic` authentication types. +|[tag greenBackground]#NEW#|The `detectCookieAccessSlow` parameter in the SDK allows your app to check if third-party cookies are enabled on the browser. This parameter is available only for trusted and `Basic` authentication types. |==== == Version 1.10.3, May 2022 @@ -1821,14 +1684,14 @@ Bug fix and improvements to the `logout` method. == Version 1.10.2, May 2022 [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE#|Ability to configure `redirectPath` on the origin when using the SAMLRedirect `authType`. +|[tag greenBackground]#NEW#|Ability to configure `redirectPath` on the origin when using the SAMLRedirect `authType`. |==== == Version 1.10.1, May 2022 [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE#|You can now use the `logout` method to log out embed users. +|[tag greenBackground]#NEW#|You can now use the `logout` method to log out embed users. |[tag orangeBackground]#MODIFIED# a| Note the following changes: + * You can now use the `loginFailedMessage` property on init to display the `Not logged in` message when a user login fails. You can customize this message by defining a custom text string in the `loginFailedMessage` attribute. @@ -1839,14 +1702,14 @@ Bug fix and improvements to the `logout` method. [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a| The `AddRemoveColumns` event is now available in the SDK. For more information, see xref:event-embedEvents.adoc[Events reference]. +|[tag greenBackground]#NEW# a| The `AddRemoveColumns` event is now available in the SDK. For more information, see xref:event-embedEvents.adoc[Events reference]. |==== == Version 1.9.8, April 2022 [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE#|The `pageId` attribute now allows you to set the **SpotIQ** page as the home tab of your embedded ThoughtSpot app. +|[tag greenBackground]#NEW#|The `pageId` attribute now allows you to set the **SpotIQ** page as the home tab of your embedded ThoughtSpot app. For more information, see xref:full-embed.adoc[Embed full application]. |==== @@ -1858,7 +1721,7 @@ Bug fixes and improvements == Version 1.9.5, April 2022 [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE#|The `locale` attribute is now available in embed packages. You can use this attribute to set the locale or language of your embedded application view. +|[tag greenBackground]#NEW#|The `locale` attribute is now available in embed packages. You can use this attribute to set the locale or language of your embedded application view. For more information, see xref:locale-setting.adoc[Set locale and display language]. |==== @@ -1870,7 +1733,7 @@ Bug fixes and improvements to React components. [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE#| The SDK now supports the `disableLoginRedirect` attribute to improve the login experience for your application users. When enabled, this attribute prevents your app from redirecting users to the login page when their session expires. + +|[tag greenBackground]#NEW#| The SDK now supports the `disableLoginRedirect` attribute to improve the login experience for your application users. When enabled, this attribute prevents your app from redirecting users to the login page when their session expires. + You can use this attribute along with `autoLogin` to automatically authenticate and re-login a user. + This feature is applicable to token-based authentication, that is, when the `AuthType` is set as `TrustedAuthToken` in the SDK. @@ -1880,7 +1743,7 @@ For more information, see xref:embed-authentication.adoc#trusted-auth-embed[Auth == Version 1.9.2, March 2022 [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE#| You can now trigger events on React components using the `useEmbedRef` hook. +|[tag greenBackground]#NEW#| You can now trigger events on React components using the `useEmbedRef` hook. For more information, see xref:embed-ts-react-app.adoc[Embed ThoughtSpot in a React app]. |==== @@ -1888,11 +1751,11 @@ For more information, see xref:embed-ts-react-app.adoc[Embed ThoughtSpot in a Re == Version 1.9.1, March 2022 [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE#| The SDK now includes the `visibleVizs` attribute in the `LiveboardEmbed` package. This attribute allows you to add visualization GUIDs that you want to display when a Liveboard renders for the first time. +|[tag greenBackground]#NEW#| The SDK now includes the `visibleVizs` attribute in the `LiveboardEmbed` package. This attribute allows you to add visualization GUIDs that you want to display when a Liveboard renders for the first time. For more information, see xref:embed-pinboard.adoc[Embed a Liveboard]. -|[tag greenBackground]#NEW FEATURE# a| The following events are now available in the SDK: + +|[tag greenBackground]#NEW# a| The following events are now available in the SDK: + * `LiveboardRendered` (EmbedEvent) @@ -1902,7 +1765,7 @@ For more information, see xref:event-embedEvents.adoc[Events reference]. == Version 1.9.0, March 2022 [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a| The SDK now includes the following new enumerations for UI actions: +|[tag greenBackground]#NEW# a| The SDK now includes the following new enumerations for UI actions: * `Action.AnswerDelete` + * `Action.AnswerChartSwitcher` + @@ -1911,7 +1774,7 @@ For more information, see xref:event-embedEvents.adoc[Events reference]. For more information, see xref:embed-actions.adoc#standard-actions[Show or hide UI actions]. -|[tag greenBackground]#NEW FEATURE# a| The SDK now supports the `UpdateRuntimeFilters` host event. For more information, see xref:events-hostEvents.adoc[Events reference]. +|[tag greenBackground]#NEW# a| The SDK now supports the `UpdateRuntimeFilters` host event. For more information, see xref:events-hostEvents.adoc[Events reference]. |==== == Version 1.8.x, February 2022 @@ -1919,7 +1782,7 @@ For more information, see xref:embed-actions.adoc#standard-actions[Show or hide [width="100%" cols="1,4"] |==== |[tag redBackground]#BREAKING CHANGE# | The `autoLogin` attribute is now set as `false` by default. This attribute is used in the `init` method to automatically re-login a user when a session expires. -|[tag greenBackground]#NEW FEATURE# | The `init` method now returns the `authPromise` which resolves when a user authentication is completed. +|[tag greenBackground]#NEW# | The `init` method now returns the `authPromise` which resolves when a user authentication is completed. |==== @@ -1928,12 +1791,12 @@ For more information, see xref:embed-actions.adoc#standard-actions[Show or hide [width="100%" cols="1,4"] |==== | -[tag greenBackground]#NEW FEATURE# |+++
OIDC AuthType
+++ +[tag greenBackground]#NEW# |+++
OIDC AuthType
+++ The SDK supports the `OIDC` `authType` in `init` calls. If you want your application users to authenticate to an OpenID provider and use their SSO credentials to access the embedded ThoughtSpot content, you can enable the `OIDC` authentication type in the SDK. For more information, see xref:embed-authentication.adoc#oidc-auth[Authentication and security attributes]. -|[tag greenBackground]#NEW FEATURE# a|+++
Embed events
+++ +|[tag greenBackground]#NEW# a|+++
Embed events
+++ The SDK includes the following new event: @@ -1947,7 +1810,7 @@ For more information, see xref:event-embedEvents.adoc[Events reference]. [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a|+++
Visible actions
+++ +|[tag greenBackground]#NEW# a|+++
Visible actions
+++ You can now configure a set of ThoughtSpot UI actions as visible actions and display these actions in the embedded UI. If your embedded instance requires only a few actions, you can use the `visibleActions` API to show only these actions in the embedded ThoughtSpot UI. @@ -1957,7 +1820,7 @@ For more information, see xref:embed-actions.adoc[Show or hide UI actions]. The SDK library and object parameter names are modified to rebrand pinboards as Liveboards. For a complete list of changes, see xref:terminology-update.adoc#sdk-changes[Terminology changes]. -|[tag greenBackground]#NEW FEATURE# a|+++
Embed events
+++ +|[tag greenBackground]#NEW# a|+++
Embed events
+++ The SDK supports the following new events: @@ -1972,17 +1835,17 @@ For more information, see xref:event-embedEvents.adoc[Events reference]. [width="100%" cols="1,4"] |==== || -|[tag greenBackground]#NEW FEATURE# | +++
Render embedded objects in queue
+++ +|[tag greenBackground]#NEW# | +++
Render embedded objects in queue
+++ The SDK now supports rendering embedded objects in a queue. If you have multiple embedded objects, you can enable the `queueMultiRenders` parameter to queue your embedded objects and render them one after another. This feature helps in decreasing the load on the web browsers and improving your application loading experience. By default, this attribute is set to `false`. -|[tag greenBackground]#NEW FEATURE# a|+++
Liveboard embed
+++ +|[tag greenBackground]#NEW# a|+++
Liveboard embed
+++ The `pinboardEmbed` package includes the `defaultHeight` attribute that sets a minimum height for embedded objects on a pinboard page, and the corresponding visualization pages that a user can navigate to. For more information, see xref:embed-search.adoc[Embed a pinboard]. -|[tag greenBackground]#NEW FEATURE# a|+++
Embed events
+++ +|[tag greenBackground]#NEW# a|+++
Embed events
+++ The SDK EmbedEvent library includes the following new events: @@ -1999,19 +1862,19 @@ For more information, see xref:event-embedEvents.adoc[Events reference]. [width="100%" cols="1,4"] |==== || -|[tag greenBackground]#NEW FEATURE# a|+++
+++Prefetch API+++
+++ +|[tag greenBackground]#NEW# a|+++
+++Prefetch API+++
+++ The `prefetch` API fetches static resources from a given URL before your application loads. Web browsers can then cache the prefetched resources locally and serve them from a user's local disk. You can use this API to load the embedded objects faster and improve your application response time. For more information, see xref:prefetch-and-cache.adoc[Prefetch static resources]. -|[tag greenBackground]#NEW FEATURE# a|+++
+++In-app page navigation+++
+++ +|[tag greenBackground]#NEW# a|+++
+++In-app page navigation+++
+++ The `navigateToPage` method in the SDK lets you provide quick and direct access to a specific pinboard, saved Answer, or an application page. You can add a custom menu action or button in your application UI that calls the `navigateToPage` method and leads your users to the page specified in the `path` parameter. For more information, see xref:page-navigation.adoc[Add a custom action for in-app navigation]. -|[tag greenBackground]#NEW FEATURE# a|+++
+++Full application embedding+++
+++ +|[tag greenBackground]#NEW# a|+++
+++Full application embedding+++
+++ The `appEmbed` SDK package includes the following new attributes: @@ -2021,7 +1884,7 @@ The `appEmbed` SDK package includes the following new attributes: For more information, see xref:full-embed.adoc[Embed full application]. -|[tag greenBackground]#NEW FEATURE# |+++
+++Search embed +++
+++ +|[tag greenBackground]#NEW# |+++
+++Search embed +++
+++ The `searchEmbed` package includes the `forceTable` attribute that sets tabular view as the default format for presenting search data. You can set this attribute to `true` to force search results to appear in the table view. @@ -2030,7 +1893,7 @@ For more information, see xref:embed-search.adoc[Embed ThoughtSpot search]. |[tag redBackground]#REMOVED# | The `searchQuery` parameter is no longer supported and is removed from the `searchEmbed` SDK package. -|[tag greenBackground]#NEW FEATURE# a|+++
+++Embed events +++
+++ +|[tag greenBackground]#NEW# a|+++
+++Embed events +++
+++ The SDK EmbedEvent library includes the following events: * `QueryChanged` @@ -2044,7 +1907,7 @@ For more information, see xref:embed-events.adoc[Events and app integration]. [width="100%" cols="1,4"] |==== || -|[tag greenBackground]#NEW FEATURE# a| +++
searchOptions
+++ +|[tag greenBackground]#NEW# a| +++
searchOptions
+++ The `searchEmbed` SDK package introduces the `searchOptions` parameter for setting search tokens. The `searchOptions` parameter includes the following attributes: @@ -2064,13 +1927,13 @@ The `searchQuery` parameter in the `searchEmbed` SDK package is deprecated in th For more information about `searchOptions`, see xref:embed-search.adoc#search-query[Embed ThoughtSpot search]. -|[tag greenBackground]#NEW FEATURE# a| +++
autoLogin
+++ +|[tag greenBackground]#NEW# a| +++
autoLogin
+++ The SDK now supports logging in users automatically after a user session has expired. For more information, see xref:embed-authentication.adoc#embed-session-sec[Embed user authentication]. -|[tag greenBackground]#NEW FEATURE# a| +++
shouldEncodeUrlQueryParams
+++ +|[tag greenBackground]#NEW# a| +++
shouldEncodeUrlQueryParams
+++ You can now convert query parameters in the ThoughtSpot generated URLs to base64-encoded format. You can enable this attribute to secure your cluster from cross-site scripting attacks. |[tag redBackground]#BREAKING CHANGE# a| +++
Data structure changes in custom action response payloads
+++ @@ -2089,16 +1952,16 @@ Includes user information such as username, GUID of the user, and email address. To view a sample response payload, see xref:callback-response-payload.adoc#search-data-payload[Custom action response payload]. -|[tag greenBackground]#NEW FEATURE# a| +++
preventPinboardFilterRemoval
+++ +|[tag greenBackground]#NEW# a| +++
preventPinboardFilterRemoval
+++ The `pinboardEmbed` SDK package now includes the `preventPinboardFilterRemoval` attribute. You can use this attribute to disable the filter removal action and thus prevent users from removing the filter chips added on a pinboard page. For more information, see xref:embed-pinboard.adoc[Embed a pinboard] and xref:embed-a-viz.adoc[Embed a visualization]. -|[tag greenBackground]#NEW FEATURE# a| +++
suppressNoCookieAccessAlert
+++ +|[tag greenBackground]#NEW# a| +++
suppressNoCookieAccessAlert
+++ You can now set custom alerts for `noCookieAccess` events. By default, the SDK triggers a `noCookieAccess` event and generates an alert when a user's browser blocks third-party cookies. The `suppressNoCookieAccessAlert` allows you to disable this alert. -|[tag greenBackground]#NEW FEATURE# a| +++
Support for fetching callback custom action payload in batches
+++ +|[tag greenBackground]#NEW# a| +++
Support for fetching callback custom action payload in batches
+++ The Visual Embed SDK now supports processing data in batches for callback custom action responses. The callback custom action event in the SDK package supports defining `batchSize` and `offset` values to paginate the Answer payload and send the records in batches. @@ -2110,13 +1973,13 @@ For more information, see xref:push-data-to-external-app.adoc#large-dataset[Call [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a|+++
SAML authentication
+++ +|[tag greenBackground]#NEW# a|+++
SAML authentication
+++ The Visual Embed SDK packages now include the `noRedirect` attribute as an optional parameter for the SAMLRedirect SSO `AuthType`. If you want to display the SAML authentication workflow in a pop-up window, instead of refreshing the application web page to direct users to the SAML login page, you can set the `noRedirect` attribute to `true`. For more information, see the instructions for embedding xref:full-embed.adoc[ThoughtSpot pages], xref:embed-search.adoc[search], xref:embed-pinboard.adoc[pinboard], and xref:embed-a-viz.adoc[visualizations]. -|[tag greenBackground]#NEW FEATURE# a|+++
Pinboard actions
+++ +|[tag greenBackground]#NEW# a|+++
Pinboard actions
+++ The *More* menu image:./images/icon-more-10px.png[the more options menu] in the embedded Pinboard page now shows the following actions for pinboard and visualizations. Pinboard:: @@ -2132,7 +1995,7 @@ Pinboard:: [NOTE] Users with edit permissions can view and access the *Save*, *Add filters*, *Configure filters*, and *Manage schedules* actions. -|[tag greenBackground]#NEW FEATURE# a|+++
Visualization actions
+++ +|[tag greenBackground]#NEW# a|+++
Visualization actions
+++ Visualizations on a pinboard: @@ -2153,7 +2016,7 @@ Users with edit permissions can view and access the *Edit* action. The *Download [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a|+++
NoCookieAccess event
+++ +|[tag greenBackground]#NEW# a|+++
NoCookieAccess event
+++ When a user accesses the embedded application from a web browser that has third-party cookies disabled, the Visual Embed SDK emits the `NoCookieAccess` event to notify the developer. Cookies are disabled by default in Safari. Users can enable third-party cookies in Safari’s Preferences setting page or use another web browser. To know how to enable this setting by default on Safari for a ThoughtSpot embedded instance, contact ThoughtSpot Support. diff --git a/modules/ROOT/pages/embed-event-error-best-practices.adoc b/modules/ROOT/pages/embed-event-error-best-practices.adoc index e9bdc49f0..dc10ab699 100644 --- a/modules/ROOT/pages/embed-event-error-best-practices.adoc +++ b/modules/ROOT/pages/embed-event-error-best-practices.adoc @@ -6,6 +6,17 @@ :page-pageid: handling-embed-errors :page-description: This document lists the best practices for handling error events. + +[IMPORTANT] +==== +In the upcoming ThoughtSpot Cloud 26.10.0.cl and Visual Embed SDK 1.53.0 versions, `EmbedEvent.Error` will include a `severity` field that categorizes errors into three severity levels: `SEV1`, `SEV2`, and `SEV3`. + +ThoughtSpot recommends reviewing your error handing logic to prepare your integrations for this change. If your application currently handles all errors uniformly, you may need to update your error handling to distinguish between critical errors (SEV1) that require tearing down the embed and less severe errors (SEV2, SEV3) that can be logged or ignored. + +//For more information, see the xref:embed-event-error-best-practices.adoc#_error_severity_levels[Error severity levels] section. +==== + + The ThoughtSpot Visual Embed SDK provides a layered approach to error handling. `EmbedEvent.Error` is a real-time outbound event emitted from the embedded ThoughtSpot iframe to the host application, signaling that something has gone wrong, either inside the SDK itself, inside the embedded app (the iframe), or as a result of an invalid HostEvent payload sent by the host. diff --git a/modules/ROOT/pages/lazy-loading-fullheight.adoc b/modules/ROOT/pages/lazy-loading-fullheight.adoc index 0d09fafb2..cb2942781 100644 --- a/modules/ROOT/pages/lazy-loading-fullheight.adoc +++ b/modules/ROOT/pages/lazy-loading-fullheight.adoc @@ -47,6 +47,9 @@ const embed = new LiveboardEmbed("#your-embed-div", { By default, the `lazyLoadingForFullHeight` attribute is set to `false`. When set to `false`, all visualizations load immediately, and the data is fetched upfront. +== Lazy loading of scrollable container +When `fullHeight` is enabled, the `enableScrollableContainerLazyLoading` parameter is set to `true` by default to enable lazy loading for scrollable container elements in Visual Embed SDK 1.52.0 and later. + == Margin settings for lazy loading The `lazyLoadingMargin` parameter allows you to set the margin before a visualization loads in the viewport. For example, if set to '10px', the visualizations will begin loading when the top edge is within the 10-pixel margin of the viewport. If set to '0px', the visualization will load only when it becomes fully visible in the viewport. This allows for precise control over lazy loading behavior and improves both user experience and performance. @@ -61,6 +64,24 @@ const embed = new LiveboardEmbed("#your-embed-div", { }); ---- +== Margin settings for lazy loading + +The `lazyLoadingMargin` parameter allows you to set the margin before a visualization loads in the viewport. For example, if set to `'10px'`, the visualizations begin loading when the top edge is within the 10-pixel margin of the viewport. If set to `'0px'`, the visualization loads only when it becomes fully visible in the viewport. This allows precise control over lazy loading behavior and improves both user experience and performance. + +In Visual Embed SDK 1.52.0 and later, the `lazyLoadingMargin` defaults to `'500px 0px'` when `fullHeight` is enabled. This setting is similar to CSS margin, so '500px 0px' extends the prefetch 500px above and below the viewport and not sideways. The default setting allows loading one visualization ahead of the scroll position, so a chart has usually finished loading by the time it scrolls into view. + +You can edit the margin setting as needed. Use a smaller margin to cut warehouse queries further, or '0px' to load a visualization only when it is visible. Accepted units are `px`, `em`, `rem`, `%`, `vh` and `vw`. The parameter also allows setting `0` and `auto`. Any invalid value is logged and ignored. + +[source,JavaScript] +---- +const embed = new LiveboardEmbed("#your-embed-div", { + liveboardId: "your-liveboard-id", //your Liveboard ID + fullHeight: true, + lazyLoadFullHeight: true, // Enable lazy loading for full height + lazyLoadingMargin: '0px', +}); +---- + == Additional resources * xref:embed-pinboard.adoc[Embedding a Liveboard] * xref:LiveboardViewConfig.adoc[Liveboard embed view configuration properties] diff --git a/modules/ROOT/pages/rest-apiv2-changelog.adoc b/modules/ROOT/pages/rest-apiv2-changelog.adoc index dbf3eca3b..323859523 100644 --- a/modules/ROOT/pages/rest-apiv2-changelog.adoc +++ b/modules/ROOT/pages/rest-apiv2-changelog.adoc @@ -10,125 +10,83 @@ This changelog lists the features and enhancements introduced in REST API v2.0. == Version 26.9.0.cl, September 2026 - === Answer Export API enhancements — General Availability +=== Answer Export API - // SOURCE: SCAL-306069 +The `POST /api/rest/2.0/report/answer` endpoint is now GA with the following enhancements: - The `POST /api/rest/2.0/report/answer` endpoint is generally available from 26.9.0.cl. The `isAnswerExportV2Enabled` flag is enabled by default on all ThoughtSpot Cloud instances. The following enhancements are included in this release: - - Pinned Answer export:: - Pass `viz_guid` to export a pinned Answer (a visualization on a Liveboard) directly. Liveboard-level filters and runtime overrides are applied automatically. The `metadata_identifier` must be the parent Liveboard GUID or name. - - Personalized View support:: - Pass `personalised_view_identifier` to export data from a specific Personalized View of a Liveboard. - - Spotter Answer export:: - XLSX and PDF export formats are now supported for Spotter-generated (ad hoc) Answers, in addition to CSV and PNG. - - Custom PNG dimensions:: - Use `x_resolution` and `y_resolution` parameters to specify custom pixel dimensions for PNG exports. Accepted range: 600–3840 px per axis. Default: 2254 × 1588. - - Display scaling:: - Use `scaling_factor` (range: 80–400) to adjust the relative size of chart elements in a PNG export without cropping the image. - - Dynamic file naming:: - Exported files are automatically named based on the Answer title with the correct file extension (`.png`, `.pdf`, `.csv`, `.xlsx`) appended. - - For more information, see xref:data-report-v2-api.adoc#answer-report[Answer Report API]. - - === Snowflake Semantic View integration APIs - - // SOURCE: SCAL-309867 - - ThoughtSpot 26.9.0.cl introduces REST API v2.0 endpoints for managing Snowflake Semantic View integrations programmatically. These APIs allow administrators and data managers to create, search, import, and delete semantic integration configurations without using the ThoughtSpot UI. - - [width="100%"] - [options="header"] - |===== - | Method | Endpoint | Description - | `POST` | `/api/rest/2.0/semantic-integrations/create` | Creates a new semantic integration by reading a Snowflake Semantic View and generating a ThoughtSpot data model. - | `POST` | `/api/rest/2.0/semantic-integrations/search` | Returns a list of semantic integrations matching the specified filter criteria. - | `POST` | `/api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/import` | Re-imports semantic updates from Snowflake and refreshes the associated ThoughtSpot data model. - | `POST` | `/api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/delete` | Deletes a semantic integration and its generated ThoughtSpot data model. - |===== - - Required privilege: `ADMINISTRATION` or `DATAMANAGEMENT`. If RBAC is enabled, the user also requires the `CAN_CREATE_OR_EDIT_CONNECTIONS` privilege and permission to manage data models. - - For more information, see xref:semantic-integrations-api.adoc[Snowflake Semantic View integration APIs]. - - === Spotter Memory — General Availability - - // SOURCE: SCAL-306173 - - The Spotter Memory feature is generally available from 26.9.0.cl. The memory APIs introduced in 26.8.0.cl (`POST /api/rest/2.0/ai/memory/import` and `POST /api/rest/2.0/ai/memory/export`) are enabled by default on all ThoughtSpot Cloud instances. Administrators can manage and audit Spotter training data programmatically without enabling a feature flag. - - For more information, see xref:spotter-ai-memory-api.adoc[Spotter memory APIs]. - - === Spotter Agent — Conversation sharing APIs - - // SOURCE: SCAL-306173 (aug.26.mt) - - ThoughtSpot 26.9.0.cl introduces REST API v2.0 endpoints for sharing saved Spotter agent conversations with other users or groups. Shared conversations are always `READ_ONLY`. - - [width="100%"] - [options="header"] - |===== - | Method | Endpoint | Description - | `POST` | `/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` | Shares a saved Spotter conversation with specified principals. Use `grant` and `revoke` arrays to manage access. - | `GET` | `/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content` | Returns the content of a shared Spotter conversation — messages, data sources, and answer details. - | `GET` | `/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info` | Returns sharing metadata — the list of principals the conversation is shared with and their access levels. The `is_shared_content_outdated` flag indicates if the shared snapshot is stale. - |===== - - For more information, see xref:spotter-agent-sharing-apis.adoc[Sharing Spotter conversations]. +Pinned Answer export:: +Pass `viz_guid` to export a pinned Answer (a visualization on a Liveboard) directly. Liveboard-level filters and runtime overrides are applied automatically. The `metadata_identifier` must be the parent Liveboard GUID or name. - === KPI Sparkline setting in metadata search response +Personalized View support:: +Pass `personalised_view_identifier` to export data from a specific Personalized View of a Liveboard. - // SOURCE: SCAL-320899 +Spotter Answer export:: +XLSX and PDF export formats are now supported for Spotter-generated (ad hoc) Answers, in addition to CSV and PNG. - The `POST /api/rest/2.0/metadata/search` API response now includes the `isSparklineEnabled` field in the `AnswerSpecHeader` object for KPI chart type answers. This boolean field indicates whether the sparkline trend line is enabled for the KPI visualization. +Custom PNG dimensions:: +Use `x_resolution` and `y_resolution` parameters to specify custom pixel dimensions for PNG exports. Accepted range: 600–3840 px per axis. Default: 2254 × 1588. - * `true` — the sparkline trend line is enabled. - * `false` — the sparkline is disabled. - * Absent — the answer was saved before this release and has not been re-saved. Treat an absent field as unknown, not as `false`. +Display scaling:: +Use `scaling_factor` (range: 80–400) to adjust the relative size of chart elements in a PNG export without cropping the image. - === Outline Encoding — BYOC Muze +Dynamic file naming:: +Exported files are automatically named based on the Answer title with the correct file extension (`.png`, `.pdf`, `.csv`, `.xlsx`) appended. - // SOURCE: SCAL-317550 +For more information, see xref:data-report-v2-api.adoc#answer-report[Answer Report API]. - ThoughtSpot 26.9.0.cl promotes mark outline color to a first-class data-driven encoding channel in the Muze charting library (BYOC). Developers building custom charts with Muze can now bind a data field to `encoding.outline` to produce ordinal color palettes (for categorical fields) or continuous gradient ramps (for measures), with full legend rendering and legend-to-mark interaction. +=== Snowflake Semantic View integration APIs +This release introduces the following new REST API v2.0 endpoints for managing Snowflake Semantic View integrations programmatically. - The static `outline` config (`{ fill, color, width, dash }`) remains fully backward compatible. Supported mark types: Point, Bar, Arc. +* `POST /api/rest/2.0/semantic-integrations/create` + +Creates a new semantic integration by reading a Snowflake Semantic View and generating a ThoughtSpot data model. +* `POST /api/rest/2.0/semantic-integrations/search` + +Returns a list of semantic integrations matching the specified filter criteria. +* `POST /api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/import` + +Re-imports semantic updates from Snowflake and refreshes the associated ThoughtSpot data model. +* `POST /api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/delete` + +Deletes a semantic integration and its generated ThoughtSpot data model. - === Personalized Views TML portability — General Availability +For more information, see xref:semantic-integrations-api.adoc[Snowflake Semantic View integration APIs]. - // SOURCE: SCAL-307284 +=== Conversation sharing APIs +ThoughtSpot introduces the following REST API v2.0 endpoints to share Spotter agent conversations with other users or groups. - The Personalized Views TML portability feature introduced as Early Access in 26.8.0.cl is generally available from 26.9.0.cl. +* `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` + +Share a conversation with users or groups with `READ_ONLY` access. +* `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content` + +Retrieve the shared messages and answers in a conversation. +* `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info` + +Retrieve the list of principals a conversation is shared with and their access levels. - * The `author` field in Personalized View TML maps to the view owner's username or email, ensuring ownership is retained when a Liveboard is promoted across clusters or orgs. - * The `obj_id` field provides a stable cross-environment identifier for Personalized Views. - * Smart merge import: when importing a Liveboard TML that contains Personalized Views, ThoughtSpot preserves views that exist only in the target environment, appends new views from the imported TML, and updates views present in both. +For more information, see xref:spotter-agent-sharing-apis.adoc[Sharing Spotter conversations]. - For more information, see xref:tml.adoc#personalized-views-portability[Personalized Views portability in TML]. +=== KPI Sparkline setting in metadata search response +The `POST /api/rest/2.0/metadata/search` API response now includes the `isSparklineEnabled` parameter in the `AnswerSpecHeader` object for KPI chart type answers. This boolean parameter indicates whether the sparkline trend line is enabled for the KPI visualization. - === Connection configuration — Scheduled Liveboards process type +//// +=== Outline Encoding for Muze charts +Developers building custom charts with Muze can now bind a data field to `encoding.outline` to produce ordinal color palettes (for categorical fields) or continuous gradient ramps (for measures), with full legend rendering and legend-to-mark interaction. - // SOURCE: SCAL-312738 +The static `outline` config (`{ fill, color, width, dash }`) remains fully backward compatible. Supported mark types: Point, Bar, Arc. +//// - ThoughtSpot 26.9.0.cl adds `SCHEDULED_LIVEBOARDS` as a new process type for Embrace connection configurations. Administrators can assign the Scheduled Liveboards process to a connection configuration, enabling ThoughtSpot to use the associated credentials when running scheduled Liveboard delivery jobs. Configurable via: +=== Personalized Views TML portability +The Personalized Views TML portability feature is now GA and enabled on all ThoughtSpot Embedded instances: - * `POST /api/rest/2.0/connection/configuration/create` - * `PUT /api/rest/2.0/connection/configuration/{configuration_identifier}/update` +* The `author` field in Personalized View TML maps to the view owner's username or email, ensuring ownership is retained when a Liveboard is promoted across clusters or orgs. +* The `obj_id` field provides a stable cross-environment identifier for Personalized Views. +* Smart merge import: when importing a Liveboard TML that contains Personalized Views, ThoughtSpot preserves views that exist only in the target environment, appends new views from the imported TML, and updates views present in both. - === AI Context — Spotter Optimization tab +For more information, see xref:tml.adoc#personalized-views-portability[Personalized Views portability in TML]. - // SOURCE: SCAL-277656 +=== Support for Scheduled Liveboards process type in Connection configuration +The connection configuration API endpoints now support `SCHEDULED_LIVEBOARDS` as a process type: - The AI Context generation UI is revamped in 26.9.0.cl. A new *Spotter Optimization* tab is introduced in the data model editor for managing AI context, replacing the previous AI Context panel. The tab provides a more streamlined interface for reviewing and editing auto-generated descriptions for columns and joins. +* `POST /api/rest/2.0/connection/configuration/create` +* `PUT /api/rest/2.0/connection/configuration/{configuration_identifier}/update` - No changes to the AI context REST API endpoints in this release. +Administrators can assign the Scheduled Liveboards process to a connection configuration, enabling ThoughtSpot to use the associated credentials when running scheduled Liveboard delivery jobs. - == Version 26.8.0.cl, August 2026 === Spotter AI APIs diff --git a/modules/ROOT/pages/spotter-agent-sharing-apis.adoc b/modules/ROOT/pages/spotter-agent-sharing-apis.adoc index 3b80474b6..c9fb4b15c 100644 --- a/modules/ROOT/pages/spotter-agent-sharing-apis.adoc +++ b/modules/ROOT/pages/spotter-agent-sharing-apis.adoc @@ -6,9 +6,6 @@ :page-pageid: spotter-agent-sharing-apis :page-description: Use the Spotter agent conversation sharing REST API v2.0 endpoints to share saved Spotter agent conversations with other users or groups. -// SOURCE: SCAL-306173 (aug.26.mt) -// SOURCE: prism/src/public-apis/nl-to-answer.graphql (master) - ThoughtSpot provides REST API v2.0 endpoints to share saved Spotter agent conversations with other users or groups. Shared conversations are always `READ_ONLY` — recipients can view conversation messages and associated answers but cannot send new queries or modify the conversation. For information about creating and saving a conversation, see xref:spotter-agent-conversation-apis.adoc[Spotter agent conversation APIs] and xref:spotter-agent-conversation-mgmt-apis.adoc[APIs for managing saved conversations]. @@ -32,8 +29,7 @@ __Available on ThoughtSpot Cloud instances from 26.9.0.cl onwards.__ [#_share_a_conversation] == Share a conversation - -Use `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` to share a saved Spotter conversation with one or more principals. +Use `/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` API endpoint to share a saved Spotter conversation with one or more principals. === Path parameters @@ -78,7 +74,7 @@ curl -X POST \ [#_get_shared_content] == Get shared content -Use `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content` to retrieve the content of a shared Spotter conversation. +Use the `/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content` API endpoint to retrieve the content of a shared Spotter conversation. === Path parameters @@ -89,6 +85,18 @@ Use `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shar | `conversation_identifier` | The GUID of the shared Spotter conversation. |===== +=== Example request + +[source,cURL] +---- +curl -X GET \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/json' +---- + + + === Response fields [width="100%" cols="2,4"] @@ -102,16 +110,6 @@ Use `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shar | `code_execution_files` | Array of files generated by code execution steps, if any. |===== -=== Example request - -[source,cURL] ----- -curl -X GET \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content' \ - -H 'Authorization: Bearer {access-token}' \ - -H 'Accept: application/json' ----- - [#_get_share_information] == Get share information @@ -126,16 +124,6 @@ Use `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shar | `conversation_identifier` | The GUID of the Spotter conversation. |===== -=== Response fields - -[width="100%" cols="2,4"] -[options="header"] -|===== -| Field | Description -| `is_shared_content_outdated` | Boolean. `true` if the shared content snapshot is stale. Use the share endpoint with `refresh_shared_content: true` to regenerate. -| `principals` | Array of principal objects the conversation is shared with. Each entry includes the principal identifier and their access level (always `READ_ONLY`). -|===== - === Example request [source,cURL] @@ -146,6 +134,16 @@ curl -X GET \ -H 'Accept: application/json' ---- +=== Response fields + +[width="100%" cols="2,4"] +[options="header"] +|===== +| Field | Description +| `is_shared_content_outdated` | Boolean. `true` if the shared content snapshot is stale. Use the share endpoint with `refresh_shared_content: true` to regenerate. +| `principals` | Array of principal objects the conversation is shared with. Each entry includes the principal identifier and their access level (always `READ_ONLY`). +|===== + == Additional resources * See also xref:spotter-agent-apis.adoc[Spotter Agent APIs] diff --git a/modules/ROOT/pages/whats-new.adoc b/modules/ROOT/pages/whats-new.adoc index ed1431875..fb4ab0b09 100644 --- a/modules/ROOT/pages/whats-new.adoc +++ b/modules/ROOT/pages/whats-new.adoc @@ -42,16 +42,22 @@ When ThoughtSpot is embedded in a host application, internal navigation pushes n --- [discrete] -==== Collections in embedded left navigation panel [.version-badge.new]#New# - +==== Collections in embedded left navigation panel The `HomeLeftNavItem.Collections` value is now available in the Visual Embed SDK 1.52.0. Embed developers can include *Collections* as a navigation option in the left navigation panel for full application embeds, enabling end users to navigate to *Collections* directly from the embedded experience. For more information, see xref:full-app-customize.adoc[Customize the embedded ThoughtSpot experience]. --- [discrete] -==== Answer Export API — General Availability [.version-badge.new]#New# +==== Upcoming changes to `EmbedEvent.Error` framework +In the upcoming ThoughtSpot Cloud 26.10.0.cl and Visual Embed SDK 1.53.0 versions, `EmbedEvent.Error` will include a `severity` field that categorizes errors into three levels, `SEV1`, `SEV2`, and `SEV3`. ThoughtSpot recommends reviewing your error handling logic to prepare for this change. For more information, see xref:embed-event-error-best-practices.adoc[Handling embed errors]. + +--- -The Answer Export API (`POST /api/rest/2.0/report/answer`) is now generally available. This release introduces the following enhancements: + +[discrete] +==== Answer Export API + +The Answer Export API (`POST /api/rest/2.0/report/answer`) endpoint is now Generally available (GA) with the following enhancements: * *Pinned Answer export*: Export a pinned visualization from a Liveboard directly using the `viz_guid` parameter. * *Personalized View support*: Export data from a specific Personalized View using `personalised_view_identifier`. @@ -64,37 +70,16 @@ For more information, see xref:data-report-v2-api.adoc#answer-report[Answer Repo --- [discrete] -==== Snowflake Semantic View integration APIs [.version-badge.new]#New# - -ThoughtSpot introduces four new REST API v2.0 endpoints to manage Snowflake Semantic View integrations programmatically without using the ThoughtSpot UI: +==== Snowflake Semantic View integration APIs -* `POST /api/rest/2.0/semantic-integrations/create` -* `POST /api/rest/2.0/semantic-integrations/search` -* `POST /api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/import` -* `POST /api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/delete` - -Requires `ADMINISTRATION` or `DATAMANAGEMENT` privilege. For more information, see xref:semantic-integrations-api.adoc[Snowflake Semantic View integration APIs]. +ThoughtSpot introduces four new REST API v2.0 endpoints to manage Snowflake Semantic View integrations programmatically. For more information, see xref:semantic-integrations-api.adoc[Snowflake Semantic View integration APIs]. --- -[discrete] -==== Spotter Memory — General Availability [.version-badge.new]#New# - -The Spotter memory feature is now generally available. The memory APIs (`POST /api/rest/2.0/ai/memory/import` and `POST /api/rest/2.0/ai/memory/export`) are enabled by default on all ThoughtSpot Cloud instances. Administrators can manage and audit Spotter's training data programmatically. For more information, see xref:spotter-agent-apis.adoc[Spotter agent APIs]. - ---- [discrete] -==== Spotter conversation sharing APIs [.version-badge.new]#New# - -ThoughtSpot introduces three new REST API v2.0 endpoints to share Spotter agent conversations programmatically: - -* `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` -- Share a conversation with users or groups with `READ_ONLY` access. -* `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content` -- Retrieve the shared messages and answers in a conversation. -* `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info` -- Retrieve the list of principals a conversation is shared with and their access levels. - -For more information, see xref:spotter-agent-sharing-apis.adoc[Sharing Spotter conversations]. - +==== Sharing Spotter conversations +You can now share Spotter conversations programmatically via REST API endpoints. For more information, see xref:spotter-agent-sharing-apis.adoc[Sharing Spotter conversations]. --- [discrete] @@ -105,12 +90,13 @@ The `POST /api/rest/2.0/metadata/search` response now includes the `isSparklineE --- [discrete] -==== Personalized Views TML portability — General Availability [.version-badge.new]#New# +==== Personalized Views TML portability -The Personalized Views TML portability feature introduced in Early Access in 26.8.0.cl is now generally available. The `author` and `obj_id` fields are fully supported in exported and imported Personalized View TML. Smart merge import logic is applied by default. For more information, see xref:tml.adoc#personalized-views-portability[Personalized Views portability]. +The Personalized Views TML portability feature introduced in Early Access in 26.8.0.cl is now GA. The `author` and `obj_id` fields are fully supported in exported and imported Personalized View TML. Smart merge import logic is applied by default. For more information, see xref:tml.adoc#personalized-views-portability[Personalized Views portability]. --- + [discrete] ==== Visual Embed SDK The Visual Embed SDK version 1.52.0 introduces `overrideHistoryState` for browser history management in `AppEmbed` and `HomeLeftNavItem.Collections` for embedded left navigation. For more information, see the xref:api-changelog.adoc[Visual Embed SDK changelog]. From 4aaa6869621c3f25482befb73d186fffbea10729 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Thu, 27 Aug 2026 23:44:54 +0530 Subject: [PATCH 102/154] dark theme edits --- src/components/FloatingAssistant/index.scss | 217 +++++++++++++------- src/components/FloatingAssistant/index.tsx | 50 ++++- 2 files changed, 194 insertions(+), 73 deletions(-) diff --git a/src/components/FloatingAssistant/index.scss b/src/components/FloatingAssistant/index.scss index f8276f276..8901f566e 100644 --- a/src/components/FloatingAssistant/index.scss +++ b/src/components/FloatingAssistant/index.scss @@ -1,6 +1,83 @@ @import '../../assets/styles/variables.scss'; @import '../../assets/styles/highlight.scss'; +// ── Theme tokens ──────────────────────────────────────────────────────────── +// This widget mounts into its own React root appended directly to +// document.body (see gatsby-browser.js), outside #wrapper/#docsModal, so it +// can't inherit the site's data-theme custom properties from variables.scss. +// index.tsx mirrors the site's current theme onto this root's own +// data-theme attribute; these aliases are redeclared under that selector so +// they resolve against the dark values for every descendant (same reason +// variables.scss's ts-docs-radiant-aliases mixin is included twice). +#floating-assistant-root { + --fa-bg: #fff; + --fa-panel-bg: #fff; + --fa-surface: #F6F8FA; + --fa-surface-hover: #eef1f5; + --fa-border: #EAEDF2; + --fa-border-strong: #e3e6eb; + --fa-text: #1d232f; + --fa-text-secondary: #5f6368; + --fa-text-muted: #a5acb9; + --fa-accent: #2770ef; + --fa-accent-hover: #1a5fd4; + --fa-user-bubble-bg: #f1f4f8; + --fa-user-bubble-border: #e8eaed; + --fa-scrollbar: #d0d4db; + --fa-scrollbar-hover: #a5acb9; + --fa-scroll-btn-bg: #fff; + --fa-scroll-btn-border: #e0e4ea; + --fa-shadow: 0 4px 16px 0 rgba(25, 35, 49, 0.10); + --fa-shadow-hover: 0 8px 24px 0 rgba(25, 35, 49, 0.16); + --fa-panel-shadow: -4px 0 24px 0 rgba(25, 35, 49, 0.10); + --fa-input-border-idle: #d0d4db; + --fa-input-row-border: rgba(0, 0, 0, 0.06); + --fa-input-row-bg: rgba(255, 255, 255, 0.6); + --fa-fade-color: #fff; + --fa-code-inline-bg: #f1f4f8; + --fa-code-inline-border: #e3e6eb; + --fa-hover-overlay: rgba(0, 0, 0, 0.06); + --fa-panel-wash-1: rgba(255, 120, 160, 0.3); + --fa-panel-wash-2: rgba(160, 100, 255, 0.2); + --fa-panel-wash-3: rgba(100, 160, 255, 0.3); +} + +#floating-assistant-root[data-theme='dark'] { + --fa-bg: #26282C; + --fa-panel-bg: #1F2024; + --fa-surface: #26282C; + --fa-surface-hover: #2f333b; + --fa-border: #34363C; + --fa-border-strong: #34363C; + --fa-text: #e6edf3; + --fa-text-secondary: #9098a8; + --fa-text-muted: #8b949e; + --fa-accent: #71a1f4; + --fa-accent-hover: #abc7f9; + --fa-user-bubble-bg: #26282C; + --fa-user-bubble-border: #34363C; + --fa-scrollbar: #3a3f4b; + --fa-scrollbar-hover: #545b6b; + --fa-scroll-btn-bg: #2a3142; + --fa-scroll-btn-border: #3a4255; + --fa-shadow: 0 4px 16px 0 rgba(0, 0, 0, 0.4); + --fa-shadow-hover: 0 8px 24px 0 rgba(0, 0, 0, 0.5); + --fa-panel-shadow: -4px 0 24px 0 rgba(0, 0, 0, 0.4); + --fa-input-border-idle: #3a3f4b; + --fa-input-row-border: rgba(255, 255, 255, 0.08); + --fa-input-row-bg: rgba(31, 32, 36, 0.6); + --fa-fade-color: #1F2024; + --fa-code-inline-bg: #2a3142; + --fa-code-inline-border: #3a4255; + --fa-hover-overlay: rgba(255, 255, 255, 0.08); + // Same wash hues at much lower opacity — on the dark panel background the + // light-mode opacities read as a saturated, concentrated band instead of + // the soft diffused glow the reference design uses. + --fa-panel-wash-1: rgba(255, 120, 160, 0.10); + --fa-panel-wash-2: rgba(160, 100, 255, 0.07); + --fa-panel-wash-3: rgba(100, 160, 255, 0.10); +} + // ── Chip trigger ───────────────────────────────────────────────────────────── .floating-assistant__chip { position: fixed; @@ -12,19 +89,19 @@ justify-content: center; width: 56px; height: 56px; - background: #fff; + background: var(--fa-bg); border: 2px solid transparent; border-radius: 50%; cursor: pointer; background-clip: padding-box; - box-shadow: 0 4px 16px 0 rgba(25, 35, 49, 0.10); + box-shadow: var(--fa-shadow); transition: box-shadow 0.2s ease, transform 0.2s ease; outline: 2px solid transparent; // Gradient border using outline + pseudo-element on a wrapper isn't needed — // use a parent wrapper div for the gradient ring &:hover { - box-shadow: 0 8px 24px 0 rgba(25, 35, 49, 0.16); + box-shadow: var(--fa-shadow-hover); } svg { @@ -32,7 +109,7 @@ height: 26px; position: relative; z-index: 1; - color: #2770ef; + color: var(--fa-accent); } } @@ -47,7 +124,7 @@ background: linear-gradient(135deg, #8C62F5, #48D1E0, #2770EF); padding: 1px; z-index: 1001; - box-shadow: 0 4px 16px 0 rgba(25, 35, 49, 0.10); + box-shadow: var(--fa-shadow); cursor: pointer; .floating-assistant__chip { @@ -83,18 +160,18 @@ bottom: 0; width: 360px; background: - linear-gradient(180deg, transparent 0%, #fff 35%), + linear-gradient(180deg, transparent 0%, var(--fa-panel-bg) 35%), linear-gradient(90deg, - rgba(255, 120, 160, 0.3) 0%, - rgba(160, 100, 255, 0.2) 60%, - rgba(100, 160, 255, 0.3) 90% + var(--fa-panel-wash-1) 0%, + var(--fa-panel-wash-2) 60%, + var(--fa-panel-wash-3) 90% ), - #fff; + var(--fa-panel-bg); display: flex; flex-direction: column; overflow: hidden; z-index: 1002; - box-shadow: -4px 0 24px 0 rgba(25, 35, 49, 0.10); + box-shadow: var(--fa-panel-shadow); animation: fa-slide-in 0.25s ease-out forwards; &.closing { @@ -102,7 +179,7 @@ } &--conversation { - background: #fff; + background: var(--fa-panel-bg); } &--embedded { @@ -121,7 +198,7 @@ background: transparent; border: none; outline: none; - border-bottom: 1px solid #EAEDF2; + border-bottom: 1px solid var(--fa-border); } .floating-assistant__close-btn { @@ -133,16 +210,17 @@ justify-content: center; padding: 4px; border-radius: 4px; + color: var(--fa-text); transition: background 0.15s; - &:hover { background: #f1f4f8; } + &:hover { background: var(--fa-surface); } } .floating-assistant__title { font-size: 16px; font-weight: 600; font-family: 'Optimo-Plain', sans-serif; - color: #1d232f; + color: var(--fa-text); } @@ -160,12 +238,12 @@ &::-webkit-scrollbar { width: 4px; } &::-webkit-scrollbar-track { background: transparent; } &::-webkit-scrollbar-thumb { - background: #d0d4db; + background: var(--fa-scrollbar); border-radius: 2px; - &:hover { background: #a5acb9; } + &:hover { background: var(--fa-scrollbar-hover); } } scrollbar-width: thin; - scrollbar-color: #d0d4db transparent; + scrollbar-color: var(--fa-scrollbar) transparent; } // ── Messages fade + scroll-to-bottom ───────────────────────────────────────── @@ -183,7 +261,7 @@ left: 0; right: 0; height: 48px; - background: linear-gradient(to top, #fff 0%, transparent 100%); + background: linear-gradient(to top, var(--fa-fade-color) 0%, transparent 100%); opacity: 0; transition: opacity 0.2s ease; } @@ -203,17 +281,13 @@ display: inline-flex; align-items: center; justify-content: center; - background: #fff; - border: 1px solid #e0e4ea; + background: var(--fa-scroll-btn-bg); + border: 1px solid var(--fa-scroll-btn-border); border-radius: 50%; width: 28px; height: 28px; cursor: pointer; box-shadow: 0 2px 6px rgba(0,0,0,0.1); - @media (prefers-color-scheme: dark) { - background: #2a3142; - border-color: #3a4255; - } } @keyframes fa-fade-in { @@ -255,12 +329,12 @@ font-size: 22px; font-weight: 700; font-family: 'Optimo-Plain', sans-serif; - color: #1d232f; + color: var(--fa-text); line-height: 1.3; letter-spacing: -0.4px; text-align: center; - span { color: #2770ef; } + span { color: var(--fa-accent); } } .floating-assistant__suggestions { @@ -272,10 +346,10 @@ } .floating-assistant__suggestion { - background: #F6F8FA; - border: 1px solid #EAEDF2; + background: var(--fa-surface); + border: 1px solid var(--fa-border); border-radius: 40px; - color: #1d232f; + color: var(--fa-text); cursor: pointer; font-size: 12px; font-family: 'Optimo-Plain', sans-serif; @@ -287,7 +361,7 @@ animation: fa-suggestion-in 0.3s ease-out both; opacity: 0; - &:hover { background: #eef1f5; } + &:hover { background: var(--fa-surface-hover); } } @keyframes fa-suggestion-in { @@ -320,7 +394,7 @@ .floating-assistant__timestamp { font-size: 11px; - color: #a5acb9; + color: var(--fa-text-muted); font-family: 'Optimo-Plain', sans-serif; } @@ -338,14 +412,14 @@ background: none; &:hover { - background: #d0d4db; + background: var(--fa-scrollbar); } &--send { - background: #2770ef; + background: var(--fa-accent); &:hover { - background: #1a5fd4; + background: var(--fa-accent-hover); } } } @@ -385,13 +459,13 @@ // User bubble — light gray rounded box .floating-assistant__user-bubble { - background: #f1f4f8; - border: 1px solid #e8eaed; + background: var(--fa-user-bubble-bg); + border: 1px solid var(--fa-user-bubble-border); border-radius: 10px; padding: 10px 14px; font-size: 13px; font-weight: 400; - color: #1d232f; + color: var(--fa-text); font-family: 'Optimo-Plain', sans-serif; line-height: 1.5; word-break: break-word; @@ -400,8 +474,8 @@ box-sizing: border-box; &--editing { - border-color: #2770ef; - background: #fff; + border-color: var(--fa-accent); + background: var(--fa-panel-bg); cursor: text; white-space: pre-wrap; } @@ -435,7 +509,7 @@ .floating-assistant__message-text { font-size: 13px; line-height: 1.6; - color: #1d232f; + color: var(--fa-text); word-break: break-word; font-family: 'Optimo-Plain', sans-serif; @@ -448,8 +522,8 @@ li { margin-bottom: 3px; } strong { font-weight: 600; } em { font-style: italic; } - a { color: #2770ef; text-decoration: underline; } - h1, h2, h3 { font-weight: 600; margin: 10px 0 4px; color: #1d232f; } + a { color: var(--fa-accent); text-decoration: underline; } + h1, h2, h3 { font-weight: 600; margin: 10px 0 4px; color: var(--fa-text); } h1 { font-size: 15px; } h2 { font-size: 14px; } h3 { font-size: 13px; } @@ -457,11 +531,11 @@ code { font-family: $font-family-code; font-size: 12px; - background: #f1f4f8; - color: #1d232f; + background: var(--fa-code-inline-bg); + color: var(--fa-text); border-radius: 3px; padding: 1px 5px; - border: 1px solid #e3e6eb; + border: 1px solid var(--fa-code-inline-border); } pre { @@ -486,7 +560,7 @@ gap: 5px; font-size: 13px; font-weight: 400; - color: #6b7280; + color: var(--fa-text-secondary); font-family: 'Optimo-Plain', sans-serif; cursor: default; user-select: none; @@ -513,12 +587,12 @@ border-radius: 4px; font-size: 11px; font-family: 'Optimo-Plain', sans-serif; - color: #a5acb9; + color: var(--fa-text-muted); transition: color 0.15s, background 0.15s; &:hover { - color: #1d232f; - background: #f1f4f8; + color: var(--fa-text); + background: var(--fa-surface); } &--copied { @@ -538,7 +612,7 @@ border-radius: 4px; opacity: 0.7; transition: opacity 0.15s, background 0.15s; - &:hover { opacity: 1; background: rgba(0,0,0,0.06); } + &:hover { opacity: 1; background: var(--fa-hover-overlay); } &.fa-feedback-btn--active { opacity: 1; } } @@ -552,7 +626,7 @@ .floating-assistant__loading-phase { font-size: 13px; - color: #5f6368; + color: var(--fa-text-secondary); font-family: 'Optimo-Plain', sans-serif; animation: fa-phase-in 0.4s ease-out forwards; } @@ -567,19 +641,19 @@ display: flex; align-items: center; gap: 6px; - background: #f1f4f8; + background: var(--fa-surface); border-radius: 8px; padding: 6px 8px 6px 10px; margin-bottom: 4px; - color: #5f6368; + color: var(--fa-text-secondary); - svg { flex-shrink: 0; color: #a5acb9; } + svg { flex-shrink: 0; color: var(--fa-text-muted); } } .floating-assistant__quote-text { flex: 1; font-size: 12px; - color: #5f6368; + color: var(--fa-text-secondary); font-family: 'Optimo-Plain', sans-serif; white-space: nowrap; overflow: hidden; @@ -649,8 +723,8 @@ .floating-assistant__input-row { padding: 8px 12px 8px; flex-shrink: 0; - border-top: 1px solid rgba(0, 0, 0, 0.06); - background: rgba(255,255,255,0.6); + border-top: 1px solid var(--fa-input-row-border); + background: var(--fa-input-row-bg); backdrop-filter: blur(8px); } @@ -658,7 +732,7 @@ display: flex; flex-direction: column; gap: 6px; - background: #fff; + background: var(--fa-bg); border-radius: 12px; padding: 10px 10px 8px; cursor: text; @@ -671,7 +745,7 @@ inset: 0; border-radius: 12px; padding: 1.5px; - background: #d0d4db; + background: var(--fa-input-border-idle); -webkit-mask: linear-gradient(#fff 0 0) content-box, linear-gradient(#fff 0 0); @@ -718,15 +792,15 @@ font-size: 14px; font-family: 'Optimo-Plain', sans-serif; background: transparent; - color: #1d232f; + color: var(--fa-text); min-height: 28px; max-height: calc(14px * 1.5 * 4); // 4 lines at font-size 14px, line-height 1.5 overflow-y: auto; line-height: 1.5; - &::placeholder { color: #a5acb9; } + &::placeholder { color: var(--fa-text-muted); } scrollbar-width: thin; - scrollbar-color: #d0d4db transparent; + scrollbar-color: var(--fa-scrollbar) transparent; } .floating-assistant__input-buttons { @@ -740,15 +814,15 @@ width: 30px; height: 30px; border-radius: 50%; - border: 1px solid #e3e6eb; - background: #fff; + border: 1px solid var(--fa-border-strong); + background: var(--fa-bg); cursor: pointer; display: flex; align-items: center; justify-content: center; flex-shrink: 0; transition: background 0.15s; - &:hover { background: #f1f4f8; } + &:hover { background: var(--fa-surface); } } .floating-assistant__send { @@ -756,7 +830,7 @@ height: 30px; border-radius: 50%; border: none; - background: #2770ef; + background: var(--fa-accent); cursor: pointer; display: flex; align-items: center; @@ -764,7 +838,8 @@ flex-shrink: 0; transition: background 0.15s; &:disabled { opacity: 0.4; cursor: not-allowed; } - &:not(:disabled):hover { background: #1a5ccc; } + &:not(:disabled):hover, + &:not(:disabled):active { background: var(--fa-accent-hover); } } .floating-assistant__stop { @@ -776,7 +851,7 @@ align-items: center; justify-content: center; flex-shrink: 0; - background: #2770ef; + background: var(--fa-accent); border:0px; color: #fff; transition: background 0.15s, border-color 0.15s; @@ -787,12 +862,12 @@ .floating-assistant__footer { padding: 6px 16px 12px; font-size: 11.5px; - color: #a5acb9; + color: var(--fa-text-muted); text-align: center; font-family: 'Optimo-Plain', sans-serif; a { - color: #2770ef; + color: var(--fa-accent); text-decoration: none; &:hover { text-decoration: underline; } } diff --git a/src/components/FloatingAssistant/index.tsx b/src/components/FloatingAssistant/index.tsx index 22edad90d..d117a5ad4 100644 --- a/src/components/FloatingAssistant/index.tsx +++ b/src/components/FloatingAssistant/index.tsx @@ -269,6 +269,52 @@ const FloatingAssistant: React.FC = () => { return () => window.removeEventListener('gatsby-route-update', handler as EventListener); }, []); + // This widget mounts into its own React root appended directly to + // document.body (see gatsby-browser.js), outside #wrapper/#docsModal, so + // it can't inherit the site's data-theme custom properties. Mirror the + // site's current theme onto our own root's data-theme attribute instead, + // so CSS here can key off #floating-assistant-root[data-theme='dark']. + useEffect(() => { + const themeRoot = document.getElementById('floating-assistant-root'); + const setTheme = (theme: 'dark' | 'light') => { + // Guard against redundant writes — themeRoot lives inside document.body, + // so an unconditional setAttribute here would itself be a mutation that + // a body-wide observer could pick back up, looping forever. + if (themeRoot && themeRoot.getAttribute('data-theme') !== theme) { + themeRoot.setAttribute('data-theme', theme); + } + }; + + let attrObserver: MutationObserver | null = null; + + // Watches the specific #wrapper/#docsModal element for data-theme flips + // (e.g. the user toggling dark mode) — scoped to that one element only, + // so it never observes themeRoot's own attribute writes above. + const watchThemedEl = () => { + const themedEl = document.getElementById('wrapper') || document.getElementById('docsModal'); + if (!themedEl) return; + setTheme(themedEl.getAttribute('data-theme') === 'dark' ? 'dark' : 'light'); + attrObserver?.disconnect(); + attrObserver = new MutationObserver(() => { + setTheme(themedEl.getAttribute('data-theme') === 'dark' ? 'dark' : 'light'); + }); + attrObserver.observe(themedEl, { attributes: true, attributeFilter: ['data-theme'] }); + }; + + watchThemedEl(); + + // #wrapper/#docsModal can be unmounted/remounted on client-side route + // changes — re-attach the attribute observer whenever that happens. + // childList-only, so this never fires from themeRoot's attribute writes. + const bodyObserver = new MutationObserver(watchThemedEl); + bodyObserver.observe(document.body, { childList: true, subtree: true }); + + return () => { + attrObserver?.disconnect(); + bodyObserver.disconnect(); + }; + }, []); + useEffect(() => { const handler = (e: CustomEvent<{ location: Location }>) => { setIsTutorialsPage(isTutorialsPath(e.detail.location.pathname)); @@ -455,7 +501,7 @@ const FloatingAssistant: React.FC = () => { SpotterCode @@ -685,7 +731,7 @@ const FloatingAssistant: React.FC = () => { aria-label="Reset conversation" disabled={messages.length === 0 && !input.trim() && !quotedText} > - + {isLoading ? (