diff --git a/modules/ROOT/pages/api-changelog.adoc b/modules/ROOT/pages/api-changelog.adoc
index 025fe544d..dabe5cc70 100644
--- a/modules/ROOT/pages/api-changelog.adoc
+++ b/modules/ROOT/pages/api-changelog.adoc
@@ -8,9 +8,64 @@
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.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.
+
+|[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"]
+[width="100%" cols="1,4"]
|====
|[tag greenBackground]#NEW FEATURE# a|
@@ -44,11 +99,10 @@ The `visualOverrides` object provides the following customization controls to mo
* `legend` to control legend visibility, position, and color palette of charts.
* `dataLabel` attribute for data labels and per-column label filters.
-* `display` attributes for such as regression line overlay and grid line visibility in charts and table themes and content density in tables.
+* `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.
-* `updateMaskPaths` property for partial updates
-* `columns` property for column visibility, text wrapping, conditional formatting, and column summary in tables.
+* `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|
@@ -1008,7 +1062,7 @@ For more information, see xref:full-app-customize.adoc[Customize full applicatio
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 *TML* sub-menu of the **More** image:./images/icon-more-10px.png[the more options menu] menu on Answer page.
+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
@@ -1818,7 +1872,7 @@ For more information, see xref:push-data-to-external-app.adoc#large-dataset[Call
|====
|[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`.
+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].
diff --git a/modules/ROOT/pages/collections.adoc b/modules/ROOT/pages/collections.adoc
index a028490b6..2c4e7c00c 100644
--- a/modules/ROOT/pages/collections.adoc
+++ b/modules/ROOT/pages/collections.adoc
@@ -1,4 +1,4 @@
-= Collections [beta betaBackground]^Beta^
+= Collections
:toc: true
:toclevels: 1
:page-title: Collections
diff --git a/modules/ROOT/pages/common/nav-embedding.adoc b/modules/ROOT/pages/common/nav-embedding.adoc
index 4f5f8a246..347aa02bb 100644
--- a/modules/ROOT/pages/common/nav-embedding.adoc
+++ b/modules/ROOT/pages/common/nav-embedding.adoc
@@ -11,6 +11,7 @@ Embed ThoughtSpot in a web app
* link:{{navprefix}}/tsembed[Quickstart guide]
* link:{{navprefix}}/embed-ai-search-analytics[Embed AI Search and Analytics]
** link:{{navprefix}}/embed-spotter[Embed Spotter experience]
+*** link:{{navprefix}}/customize-spotter-embed[Customize Spotter interface]
** link:{{navprefix}}/embed-spotter-agent[Embed Spotter Agent]
* link:{{navprefix}}/embed-liveboard[Embed Analytics]
** link:{{navprefix}}/embed-liveboard[Embed a Liveboard]
diff --git a/modules/ROOT/pages/common/nav-in-product-help.adoc b/modules/ROOT/pages/common/nav-in-product-help.adoc
index 10d35096a..1220e40da 100644
--- a/modules/ROOT/pages/common/nav-in-product-help.adoc
+++ b/modules/ROOT/pages/common/nav-in-product-help.adoc
@@ -226,6 +226,7 @@ REST APIs
*** link:{{navprefix}}/spotter-agent-apis[AI APIs (Spotter Agent and Spotter 3)]
*** 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]
*** link:{{navprefix}}/spotter-apis-classic[AI APIs (Spotter Classic) ^BETA^]
*** link:{{navprefix}}/spotter-nl-instructions[Data model instructions APIs ^BETA^]
** link:{{navprefix}}/style-customization-apis[Style customization APIs]
@@ -234,6 +235,7 @@ REST APIs
** link:{{navprefix}}/collections[Collections ^BETA^]
** link:{{navprefix}}/connections[Connections]
** link:{{navprefix}}/connection-config[Connection configuration]
+** link:{{navprefix}}/input-tables-api[Input Tables API]
** link:{{navprefix}}/runtime-sort[Runtime sorting]
* link:{{navprefix}}/manual-translation-api[Manual translations]
* link:{{navprefix}}/webhooks-rest-api[Webhook APIs]
diff --git a/modules/ROOT/pages/common/nav-rest-api.adoc b/modules/ROOT/pages/common/nav-rest-api.adoc
index 01a17bdb0..fe44ba50c 100644
--- a/modules/ROOT/pages/common/nav-rest-api.adoc
+++ b/modules/ROOT/pages/common/nav-rest-api.adoc
@@ -20,23 +20,26 @@ REST APIs
*** 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}}/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-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]
*** link:{{navprefix}}/spotter-apis-classic[AI APIs (Spotter Classic) ^BETA^]
*** link:{{navprefix}}/spotter-nl-instructions[Data model instructions APIs ^BETA^]
-** 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}}/connections[Connections]
** link:{{navprefix}}/connection-config[Connection configuration]
-** link:{{navprefix}}/runtime-sort[Runtime sorting]
** link:{{navprefix}}/manual-translation-api[Manual translations]
+** link:{{navprefix}}/style-customization-apis[Style customization APIs]
** link:{{navprefix}}/webhooks-rest-api[Webhook APIs]
+
+
[.sidebar-title]
REST API SDK
@@ -44,6 +47,7 @@ REST API SDK
* link:{{navprefix}}/rest-api-sdk-typescript[TypeScript SDK]
* link:{{navprefix}}/rest-api-sdk-java[Java SDK]
* link:{{navprefix}}/python-sdk[Python SDK]
+* link:{{navprefix}}/rest-api-sdk-csharp[C# SDK]
* link:{{navprefix}}/rest-apiv2-js[REST API v2.0 in JavaScript]
[.sidebar-title]
diff --git a/modules/ROOT/pages/customize-css-styles.adoc b/modules/ROOT/pages/customize-css-styles.adoc
index 523961072..067cd0da9 100644
--- a/modules/ROOT/pages/customize-css-styles.adoc
+++ b/modules/ROOT/pages/customize-css-styles.adoc
@@ -8,7 +8,6 @@
The xref:css-customization.adoc[ThoughtSpot CSS customization framework] defines a number of variables for applying styles throughout embedded ThoughSpot components.
-
== Application-wide settings
The following example shows the supported variables:
@@ -43,6 +42,25 @@ The navigation panel appears at the top of the application page.
|`--ts-var-search-data-button-font-family`| Font of the text on the *Search data* button.
|======
+[#left-nav-css-vars]
+=== Left navigation panel
+Use the following CSS variables to customize the left navigation panel in full application embedding.
+
+[width="60%", cols="3,4"]
+[options="header"]
+|====
+|Variable |Description
+|`--ts-var-left-nav-background` |Background color of the left navigation panel.
+|`--ts-var-left-nav-active-tab-background` |Background color of the active tab in the left navigation panel.
+|`--ts-var-left-nav-active-tab-border-color` |Border color of the active tab in the left navigation panel.
+|`--ts-var-left-nav-section-title-color` |Font color of section title labels in the left navigation panel.
+|`--ts-var-left-nav-item-color` |Font color of navigation items in the left navigation panel.
+|`--ts-var-left-nav-item-selection-color` |Font color of the selected navigation item.
+|`--ts-var-left-nav-item-selection-background` |Background color of the selected navigation item.
+|`--ts-var-left-nav-tab-icon-active-color` |Icon color of the active tab in the left navigation panel.
+|`--ts-var-left-nav-tab-icon-inactive-color` |Icon color of inactive tabs in the left navigation panel.
+|====
+
== Menu elements
CSS Variables for **More** menu image:./images/icon-more-10px.png[the more options menu], contextual menu, and dropdown selection panels.
The *More* menu appears on Liveboard, visualization, answers, SpotIQ, and several other application pages. Contextual menu appears when you right-click on a data point on a chart or table.
diff --git a/modules/ROOT/pages/customize-homepage-full-embed.adoc b/modules/ROOT/pages/customize-homepage-full-embed.adoc
index 70d9b1bbf..79f8605c3 100644
--- a/modules/ROOT/pages/customize-homepage-full-embed.adoc
+++ b/modules/ROOT/pages/customize-homepage-full-embed.adoc
@@ -4,18 +4,13 @@
:page-title: Customize home page experience
:page-pageid: customize-homepage-experience
-:page-description: Customize the home page experience by including or excluding specific modules and arrange them as needed in full application embedding
+:page-description: Customize the home page experience by including or excluding specific modules and arranging them as needed in full application embedding
-Developers can customize the home page experience in full application embedding to show either the classic layout or the new modular home page.
+Developers can customize the home page experience in full application embedding to show either the V3 modular layout or the V4 focused home page.
[IMPORTANT]
====
-The classic (V1) experience and V2 experience modes will be deprecated in an upcoming release in 2026. Therefore, ThoughtSpot recommends upgrading the UI experience of your full application embedding to the V3 experience.
-====
-
-[NOTE]
-====
-The focused homepage experience is an Early Access feature and is disabled by default. To enable this experience in your embedding application, ensure that the feature is enabled on your ThoughtSpot instance and in the Visual Embed SDK.
+Starting from Visual Embed SDK 1.51.0, the classic v1 and v2 navigation and homepage experience are deprecated. Deployments using full application embed will be upgraded to the V3 navigation and home page experience. When your application is switched to V3 experience, you can choose to use the `HomePage.ModularWithStylingChanges` (V3) or `HomePage.Focused` (V4) experience.
====
== Home page layout
@@ -27,17 +22,19 @@ The SDK provides the xref:HomePage.adoc[homePage] attribute to set the desired h
* `homePage: HomePage.Focused` [earlyAccess eaBackground]#Early Access# +
Enables the V4 home page experience.
* `homePage: HomePage.ModularWithStylingChanges` +
-Enables the V3 modular home page experience with customizable components, styling options, and enhanced layout.
-* `homePage: HomePage.Modular` +
-Enables the basic modular home page experience with customizable components.
+Enables the V3 modular home page experience with customizable components, styling options, and enhanced layout. This experience includes charts in the **Watchlist** module that are arranged horizontally. Each chart includes menu actions to remove the KPI charts from the watchlist and create alerts, and allows drag-and-drop reordering.
+
+////
+=== V3 home page experience
+The V3 home page experience improves the layout with the following enhancements:
+
+*
-Both V2 and V3 home page experience show customization modules. The V3 home page experience improves the layout with the following enhancements:
-* The charts in the **Watchlist** module are arranged horizontally. Each chart includes menu actions to remove the KPI charts from the watchlist and create alerts, and allows drag-and-drop reordering.
+
[.bordered]
[.widthAuto]
-image::./images/watchlistv3andv2.png[V2 and V3 Watchlist module]
+image::./images/watchlistv3andv2.png[V3 Watchlist module]
* The **Trending** module displays separate lists for Liveboards and Answers objects. Both these lists show the objects trending for the last 15 days, or based on the overall views, or both.
+
[.bordered]
@@ -51,6 +48,7 @@ image::./images/favoritesV3.png[V2 and V3 Trending module, scaledwidth=50%]
* Style and CSS improvements to the **Learning** module.
In both V2 and V3, the SDK allows customization to include or exclude modules, change their order, and adjust the overall layout.
+////
[#_enable_focused_home_page]
=== V4 focused home page experience
@@ -79,8 +77,43 @@ const embed = new AppEmbed("#embed", {
----
== Customization settings for home page
-The following customization settings are available for the modular home page in the V2 and V3 experience modes.
+The following customization settings are available for the modular home page in the V3 and V4 experience modes.
+[width="100%", cols="5,^3,^3"]
+[options="header"]
+|====
+|Feature |V3 experience +
+`HomePage.ModularWithStylingChanges` |V4 experience +
+`HomePage.Focused`
+|Default experience as of 26.8.0.cl
+|[tag greenBackground tick]#✓# Default
+|[tag redBackground tick]#x# Not default
+|`hideHomepageLeftNav` +
+Hides the left navigation panel on the home page.
+|[tag greenBackground tick]#✓# Supported
+|[tag greenBackground tick]#✓# Supported
+|`hiddenHomepageModules` +
+Hides specific modules on the home page.
+|[tag greenBackground tick]#✓# Supported
+|[tag greenBackground tick]#✓# Supported
+|`reorderedHomepageModules` +
+Reorders modules on the home page.
+|[tag greenBackground tick]#✓# Supported
+|[tag redBackground tick]#x# Not supported
+|`homePageModules` +
+Specifies which modules to show on the home page.
+|[tag greenBackground tick]#✓# Supported
+|[tag redBackground tick]#x# Not supported
+|Left navigation panel customization
+|[tag greenBackground tick]#✓# Supported
+|[tag greenBackground tick]#✓# Supported
+|Custom reordering of left nav items
+|[tag greenBackground tick]#✓# Supported
+|[tag greenBackground tick]#✓# Supported
+|====
+
+
+////
[width="100%", cols="2,2,2,2"]
[options='header']
|====
@@ -122,7 +155,7 @@ Hides xref:customize-nav-full-embed.adoc#_customize_the_left_navigation_panel_on
| [tag greenBackground tick]#✓# Supported
|====
-////
+
[width="100%", cols="2,2,2,2,2"]
[options='header']
|====
@@ -175,6 +208,82 @@ In the V2 and V3 experience modes, the home page includes sections such as *Watc
The `hiddenHomepageModules` and `reorderedHomepageModules` attributes support the following settings:
+=== `hiddenHomepageModules`
+
+[source,TypeScript]
+----
+hiddenHomepageModules?: HomepageModule[];
+----
+
+Hides specific modules on the home page. Applies to V3 (`HomePage.ModularWithStylingChanges`) and V4 (`HomePage.Focused`) home page experiences.
+
+// SOURCE: visual-embed-sdk PR #530 — updated note in types.ts JSDoc
+// TODO: [WRITER] Confirm which HomepageModule values apply to V4 experience only.
+
+=== `reorderedHomepageModules`
+
+[source,TypeScript]
+----
+reorderedHomepageModules?: HomepageModule[];
+----
+
+Reorders modules on the home page. Applies to V3 (`HomePage.ModularWithStylingChanges`) only.
+
+// SOURCE: visual-embed-sdk PR #530
+// TODO: [WRITER] Confirm with product team whether reordering is available in V4.
+
+=== `homePageModules`
+
+[source,TypeScript]
+----
+homePageModules?: HomepageModule[];
+----
+
+Specifies which modules to show on the home page. Applies to V3 (`HomePage.ModularWithStylingChanges`) only.
+
+// TODO: [WRITER] Confirm with product team whether homePageModules is available in V4.
+
+== `HomepageModule` enum values
+
+// SOURCE: SCAL-312731, src/types.ts
+// TODO: [WRITER] Confirm the full list of HomepageModule enum values and
+// which apply to V3 only vs both V3 and V4 with the SDK/product team.
+
+[width="100%", cols="3,6"]
+[options="header"]
+|====
+|Value |Description
+|`HomepageModule.Watchlist` |The Watchlist module showing pinned objects.
+|`HomepageModule.MyLibrary` |The My Library module showing user's content.
+|`HomepageModule.Learning` |The Learning module with onboarding content.
+|`HomepageModule.Trending` |The Trending module showing trending content.
+|`HomepageModule.Answers` |The Answers module showing recent Answers.
+// TODO: [WRITER] Verify complete enum list — add all values from types.ts.
+|====
+
+== `HomeLeftNavItem` enum values
+
+// SOURCE: visual-embed-sdk PR #530 — updated class-level JSDoc in types.ts
+// "Classic (V1) and Modular (V2) home page experiences are deprecated.
+// This attribute applies to V3 (ModularWithStylingChanges) and V4 (Focused)."
+
+Use `HomeLeftNavItem` to customize the left navigation panel items on the home page.
+Applies to V3 (`HomePage.ModularWithStylingChanges`) and V4 (`HomePage.Focused`) home page experiences.
+
+[width="100%", cols="3,6"]
+[options="header"]
+|====
+|Value |Description
+|`HomeLeftNavItem.Home` |The Home item in the left navigation panel.
+|`HomeLeftNavItem.Liveboards` |The Liveboards item in the left navigation panel.
+|`HomeLeftNavItem.Answers` |The Answers item in the left navigation panel.
+|`HomeLeftNavItem.SpotIQ` |The SpotIQ item in the left navigation panel.
+|`HomeLeftNavItem.MonitorAlerts` |The Monitor Alerts item in the left navigation panel.
+|====
+
+
+
+////
[width="100%", cols="2,2,2,2"]
[options='header']
|===
@@ -219,6 +328,7 @@ For the **Watchlist** section, which is used for KPI monitoring.
| [tag greenBackground tick]#✓# Supported
| [tag greenBackground tick]#✓# Supported
|===
+////
=== Customize home page modules in the V3 experience
The following example shows the configuration properties for customizing the home page modules:
@@ -254,6 +364,7 @@ const embed = new AppEmbed("#embed", {
});
----
+////
=== Customize home page modules in the V2 experience
The following example shows the configuration properties for customizing the home page modules in the V2 experience:
@@ -282,15 +393,15 @@ The following example shows the configuration properties for customizing the hom
//... Other view configuration properties
});
----
-
+////
[#_search_experience_on_home_page]
=== Customize the search experience on home page
You can set the search experience on the home page to function as an object search bar that allows finding popular objects, or as an AI search interface that allows natural language queries or Spotter sessions. You can also choose to hide it from the home page.
To configure your preference, specify the following values in the `homePageSearchBarMode` attribute.
[width="100%", cols="4,8"]
-[options='header']
-|=====
+[options="header"]
+|====
|Search bar mode|Description
|`HomePageSearchBarMode.AI_ANSWER` |
Sets the natural language search bar that allows queries in natural language.
@@ -299,8 +410,7 @@ If Spotter is enabled on your instance, you can use this setting to set the Spot
|`HomePageSearchBarMode.NONE` a| 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.
To hide the search bar on the home page, you can also use the xref:customize-homepage-full-embed.adoc#_control_the_visibility_of_home_page_modules[homepageModule: HomepageModule.Search] setting.
-||
-|=====
+|====
[NOTE]
====
@@ -316,15 +426,15 @@ V3 experience::
----
import {
AppEmbed,
- PrimaryNavbarVersion // Enum for V3 navigation experience
+ PrimaryNavbarVersion, // Enum for V3 navigation experience
HomePage, // Enum for home page experience settings
HomePageSearchBarMode // Import the enum for search bar mode options
} from '@thoughtspot/visual-embed-sdk';
const embed = new AppEmbed("#embed", {
discoveryExperience: {
- primaryNavbarVersion: PrimaryNavbarVersion.Sliding, // Enable v3 experience
- homePage: HomePage.ModularWithStylingChanges // Enable v3 home page experience
+ primaryNavbarVersion: PrimaryNavbarVersion.Sliding, // Enable V3 experience
+ homePage: HomePage.ModularWithStylingChanges // Enable V3 home page experience
},
// Set the home page search bar to show the Spotter / AI search bar
homePageSearchBarMode: HomePageSearchBarMode.AI_ANSWER
@@ -332,17 +442,23 @@ const embed = new AppEmbed("#embed", {
});
----
-V2 experience::
+
+V4 experience::
[source,javascript]
----
import {
AppEmbed,
+ PrimaryNavbarVersion, // Enum for V3 navigation experience
+ HomePage, // Enum for home page experience settings
HomePageSearchBarMode // Import the enum for search bar mode options
} from '@thoughtspot/visual-embed-sdk';
const embed = new AppEmbed("#embed", {
- modularHomeExperience: true, // Enable v2 modular home page experience
+ discoveryExperience: {
+ primaryNavbarVersion: PrimaryNavbarVersion.Sliding, // Enable V3 experience
+ homePage: HomePage.Focused, // Enable V4 home page experience
+ },
// Set the home page search bar to show the Spotter / AI search bar
homePageSearchBarMode: HomePageSearchBarMode.AI_ANSWER
// Other view configuration attributes
@@ -350,24 +466,6 @@ const embed = new AppEmbed("#embed", {
----
-Classic (V1) experience::
-
-[source,javascript]
-----
-import {
- AppEmbed,
- HomePageSearchBarMode // Import the enum for search bar mode options
-} from '@thoughtspot/visual-embed-sdk';
-
-const embed = new AppEmbed("#embed", {
- // Set the home page search bar to show the Spotter / AI search bar
- homePageSearchBarMode: HomePageSearchBarMode.aiAnswer,
- // Disable the unified search experience
- isUnifiedSearchExperienceEnabled: false,
- //... other embed view configuration attributes
-});
-----
-
////
==== Enable AI Search
To set AI Search as the default search experience on the Home page, use the settings shown in the following examples.
diff --git a/modules/ROOT/pages/customize-nav-full-embed.adoc b/modules/ROOT/pages/customize-nav-full-embed.adoc
index cb4b45ceb..b90c71995 100644
--- a/modules/ROOT/pages/customize-nav-full-embed.adoc
+++ b/modules/ROOT/pages/customize-nav-full-embed.adoc
@@ -8,44 +8,24 @@
You can customize the navigation experience and the visibility of navigation menu elements using the Visual Embed SDK.
-[div announcementBlock]
---
[IMPORTANT]
-The classic (V1) experience and V2 experience modes will be deprecated in an upcoming release in 2026. Therefore, ThoughtSpot recommends upgrading the UI experience of your full application embedding to the V3 experience.
---
+====
+The classic V1 and V2 navigation and homepage experience modes are deprecated as of ThoughtSpot Cloud 26.8.0.cl. Starting from this release, all embedded sessions render in the V3 navigation experience by default.
+====
== Navigation experience
-The navigation structure in ThoughtSpot UI varies based on the UI experience mode set in your embed view.
-
-[width="100%", cols="2,4"]
-[options='header']
-|====
-|UI experience| Navigation options
-|Classic (V1) experience a|A standard top navigation bar with the following components: +
+Both V3 and V4 experience provide the following navigation experience:
-* A horizontal application menu
-* Help and user profile icons
-* Org switcher
-
-|V2 experience a|
-* Simplified top navigation structure. Includes the following components: +
-** Object search bar
-** The application selector to switch between different application contexts
-** Help and profile icons
-** Org switcher for instances with Orgs
-* A left navigation panel for each application context.
-|V3 experience
-a|
* Top navigation bar with a modern look and feel. Includes the following components:
** A hamburger icon for the sliding navigation overlay
** Object search bar
-** Help and profile icons +
+** Help and profile icons
** Org switcher
* Left navigation
** A sliding left navigation panel controlled via the hamburger icon
** Persona-based app selection icons in the panel header
** Left navigation menu that adjusts its contents according to the application context
-|====
+
[NOTE]
====
@@ -56,58 +36,52 @@ The V4 focused home page experience (`HomePage.Focused`) uses the same navigatio
The following customization settings are available for the top navigation bar.
-[width="100%", cols="2,2,2,2"]
-[options='header']
+[width="100%", cols="3,^2,^2"]
+[options="header"]
|====
| SDK property
-| Classic (V1) experience
-| V2 experience
-| V3 experience
-|`showPrimaryNavbar` +
+| V3 experience +
+`HomePage.ModularWithStylingChanges`
+| V4 experience +
+`HomePage.Focused`
+
+| `showPrimaryNavbar` +
To show or hide the navigation experience.
| [tag greenBackground tick]#✓# Supported
| [tag greenBackground tick]#✓# Supported
-| [tag greenBackground tick]#✓# Supported
-
| `hideApplicationSwitcher` +
To show or hide the application switcher.
-| [tag redBackground tick]#x# Not supported
| [tag greenBackground tick]#✓# Supported +
-In V2 experience, hides the app selector in the top navigation bar.
+Hides the app selection icons on the left navigation panel.
| [tag greenBackground tick]#✓# Supported +
-In the V3 experience, hides the app selection icons on the left navigation panel.
+Hides the app selection icons on the left navigation panel.
| `disableProfileAndHelp` +
-To show or hide the help and user profile icons in top navigation bar.
-| [tag greenBackground tick]#✓# Supported
+To show or hide the help and user profile icons in the top navigation bar.
| [tag greenBackground tick]#✓# Supported +
Also hides or shows the *Help* menu on the left navigation panel of the home page.
-| [tag greenBackground tick]#✓# Supported +
+| [tag greenBackground tick]#✓# Supported
| `hideOrgSwitcher` +
To show or hide the Org switcher.
| [tag greenBackground tick]#✓# Supported
| [tag greenBackground tick]#✓# Supported
-| [tag greenBackground tick]#✓# Supported
| `hideNotification` +
To show or hide the notification (bell) icon.
-| [tag redBackground tick]#x# Not supported
-| [tag redBackground tick]#x# Not supported
+| [tag greenBackground tick]#✓# Supported
| [tag greenBackground tick]#✓# Supported
| `hideObjectSearch` +
To show or hide the object search bar in the top navigation bar.
-| __Not applicable__ +
-The object search bar is hidden by default.
| [tag greenBackground tick]#✓# Supported
| [tag greenBackground tick]#✓# Supported
| `hideHamburger` +
To show or hide the hamburger icon in the top navigation bar.
-| __Not applicable__
-| __Not applicable__
| [tag greenBackground tick]#✓# Supported +
-Hides the hamburger icon available on pages where the left navigation panel is hidden by default.
+Hides the hamburger icon available on pages where the left navigation
+panel is hidden by default.
+| [tag greenBackground tick]#✓# Supported
|====
=== Example
@@ -117,15 +91,11 @@ The following example hides the icons in the top navigation and the application
[source,JavaScript]
----
const embed = new AppEmbed("#embed", {
- //... V3 experience attributes
- // Show navigation bar
+ //... V3 experience attributes
showPrimaryNavbar: true,
hideApplicationSwitcher: true,
- // Hide Help and User Profile icons in top navigation
disableProfileAndHelp: true,
- // Hide object search bar in top navigation
hideObjectSearch: true,
- // Hide the alert icon in top navigation
hideNotification: true,
//... other attributes
});
@@ -135,161 +105,89 @@ const embed = new AppEmbed("#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.
== Customize the left navigation panel on the home page
-In the V2 and V3 experience modes, the left navigation panel on the *Insights* > *Home* page includes menu items such as *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.
+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.
If you want to include the left navigation, but hide only a specific section in the *Insights* panel, use the `hiddenHomeLeftNavItems` property and specify the menu items to hide. The allowed values for `hiddenHomeLeftNavItems` are listed in the following table:
-[width="100%", cols="2,2,2,2"]
-[options='header']
-
-|===
-|Allowed values
-| Classic (V1) experience
-| V2 experience
-| V3 experience
+[width="100%", cols="3,^2,^2"]
+[options="header"]
+|====
+| Allowed values
+| V3 experience +
+`HomePage.ModularWithStylingChanges`
+| V4 experience +
+`HomePage.Focused`
| `HomeLeftNavItem.Create` +
-To show or hide the `+` icon that allows users to create a Liveboard or Answer in the *Insights* panel.
-| __Not applicable__
-| __Not applicable__
+To show or hide the `+` icon that allows users to create a
+Liveboard or Answer in the *Insights* panel.
+| [tag greenBackground tick]#✓# Supported
| [tag greenBackground tick]#✓# Supported
| `HomeLeftNavItem.Home` +
To show or hide the *Home* menu in the *Insights* panel.
-| __Not applicable__
| [tag greenBackground tick]#✓# Supported
| [tag greenBackground tick]#✓# Supported
+
| `HomeLeftNavItem.Spotter` +
-To show or hide the *Spotter* menu item in the *Insights* panel.
-| __Not applicable__
-| __Not applicable__
+To show or hide the *Spotter* menu item in the *Insights* panel.
+| [tag greenBackground tick]#✓# Supported
| [tag greenBackground tick]#✓# Supported
| `HomeLeftNavItem.SearchData` +
To show or hide the *Search Data* in the *Insights* panel.
-| __Not applicable__
| [tag greenBackground tick]#✓# Supported
| [tag greenBackground tick]#✓# Supported
| `HomeLeftNavItem.Liveboards` +
To show or hide the *Liveboards* menu in the *Insights* panel.
-| __Not applicable__
| [tag greenBackground tick]#✓# Supported
| [tag greenBackground tick]#✓# Supported
| `HomeLeftNavItem.Answers` +
To show or hide the *Answers* menu in the *Insights* panel.
-| __Not applicable__
| [tag greenBackground tick]#✓# Supported
| [tag greenBackground tick]#✓# Supported
-| `HomeLeftNavItem.LiveboardSchedules` +
-To show or hide the *Liveboard Schedules* menu in the *Insights* panel.
-| __Not applicable__
+| `HomeLeftNavItem.MonitorAlerts` +
+To show or hide the *Monitor* > *Alerts* menu in the *Insights* panel.
| [tag greenBackground tick]#✓# Supported
| [tag greenBackground tick]#✓# Supported
-| `HomeLeftNavItem.MonitorSubscription` +
-To show or hide the *Monitor subscriptions* in the *Insights* panel.
-| __Not applicable__
-| [tag greenBackground tick]#✓# Supported
-| [tag greenBackground tick]#✓# Supported
-| `HomeLeftNavItem.SpotIQAnalysis` +
-To show or hide the *SpotIQ analyses* in the *Insights* panel.
-| __Not applicable__
+| `HomeLeftNavItem.MonitorSubscriptions` +
+To show or hide the *Monitor* > *Subscriptions* menu in the
+*Insights* panel.
| [tag greenBackground tick]#✓# Supported
| [tag greenBackground tick]#✓# Supported
-| `HomeLeftNavItem.Favorites` +
-To show or hide the `Favorites` section in the *Insights* panel.
-| __Not applicable__
-| __Not applicable__
-| [tag greenBackground tick]#✓# Supported
-|===
-== Examples
-The following sections show code samples for customizing the default left navigation panel in the *Insights* section and the home page.
-
-=== V3 experience
-
-[source,JavaScript]
-----
-import {
- AppEmbed, // Main class to embed the full ThoughtSpot app
- HomePage, // Enum for home page experience setting
- PrimaryNavbarVersion, // Enum for navigation bar version
- HomeLeftNavItem, // Enum for left navigation items
-} from '@thoughtspot/visual-embed-sdk';
-
-const embed = new AppEmbed("#embed", {
- discoveryExperience: {
- primaryNavbarVersion: PrimaryNavbarVersion.Sliding, // Enable V3 navigation
- homePage: HomePage.ModularWithStylingChanges, // Enable V3 modular home page
- },
- // Show navigation bar
- showPrimaryNavbar: true,
- // Show left navigation on home page
- hideHomepageLeftNav: false,
- // Hide SpotIQ analysis and Favorites menu options
- hiddenHomeLeftNavItems: [
- HomeLeftNavItem.Favorites,
- HomeLeftNavItem.SpotIQAnalysis
- ],
- //... other embed view configuration attributes
-});
-----
-
-=== V2 experience
+| `HomeLeftNavItem.SpotIQAnalysis` +
+To show or hide the *SpotIQ Analysis* menu in the *Insights* panel.
+| [tag greenBackground tick]#✓# Supported
+| [tag redBackground tick]#x# Not supported
-[source,JavaScript]
-----
-import {
- AppEmbed, // Main class to embed the full ThoughtSpot app
- HomeLeftNavItem, // Enum for left navigation items
-} from '@thoughtspot/visual-embed-sdk';
-const embed = new AppEmbed("#embed", {
- // Enable the V2 navigation experience
- modularHomeExperience: true,
- // Show left navigation panel
- hideHomepageLeftNav: false,
- // Hide SpotIQ analysis and Monitor subscriptions menu options
- hiddenHomeLeftNavItems: [
- HomeLeftNavItem.MonitorSubscription,
- HomeLeftNavItem.SpotIQAnalysis
- ],
- //... other embed view configuration attributes
-});
-----
-
-== Customize the Help menu
+| `HomeLeftNavItem.Learning` +
+To show or hide the *Learning* menu in the *Insights* panel.
+| [tag greenBackground tick]#✓# Supported
+| [tag greenBackground tick]#✓# Supported
-If you want to include the help menu and link:https://docs.thoughtspot.com/cloud/latest/customize-help[add custom links, window=_blank] to it, ensure that the top navigation bar is visible and `disableProfileAndHelp` is set to `false`.
-By default, the help menu in the embedded view shows the legacy information center controlled using Pendo. To enable the new information center and add custom links, set `enablePendoHelp` to `false`.
+| `HomeLeftNavItem.LiveboardSchedules` +
+To show or hide the *Scheduled Liveboards* section in the
+*Insights* panel.
+| [tag greenBackground tick]#✓# Supported
+| [tag greenBackground tick]#✓# Supported
-To add custom links to the help menu, use the customization options in the **Admin settings** > **Help customization** page. For more information, refer to the link:https://docs.thoughtspot.com/cloud/latest/customize-help[ThoughtSpot Product Documentation].
+|====
-[source,JavaScript]
-----
-const embed = new AppEmbed("#embed", {
- // Display the top navigation bar
- showPrimaryNavbar: true,
- // Show the profile and help icons in the top navigation bar.
- disableProfileAndHelp: false,
- // Use the new ThoughtSpot information center for help and support.
- enablePendoHelp: false,
- //... other embed view configuration attributes
-});
-----
-== Additional resources
-See also:
+== Related resources
-* xref:full-app-customize.adoc[Customize full application embed]
-* xref:full-embed.adoc[Embed full application]
+* xref:full-app-customize.adoc[Customize full application embedding]
+* xref:customize-homepage-full-embed.adoc[Customize home page experience]
* xref:AppViewConfig.adoc[AppViewConfig reference page]
* xref:HostEvent.adoc[Host events]
* xref:EmbedEvent.adoc[Embed Events]
diff --git a/modules/ROOT/pages/customize-spotter-embed.adoc b/modules/ROOT/pages/customize-spotter-embed.adoc
new file mode 100644
index 000000000..762f4445d
--- /dev/null
+++ b/modules/ROOT/pages/customize-spotter-embed.adoc
@@ -0,0 +1,368 @@
+= Customizing the Spotter embed view
+:toc: true
+:toclevels: 2
+
+:page-title: Customizing the Spotter embed view
+:page-pageid: customize-spotter-embed
+:page-description: You can customize the SpotterEmbed experience using the customization options available in the Visual Embed SDK.
+
+When you xref:embed-spotter.adoc[embed Spotter] in your application, you'll notice that the embedded component loads an initial page with a prompt interface. The look and feel of this page vary depending on the Spotter version used for embedding.
+
+== Spotter UI
+If you have embedded Spotter Classic or Spotter 2, the initial page includes a prompt bar for user input, a data source selector, and the UI options to preview data and reset a Spotter session.
+
+[.widthAuto]
+[.bordered]
+image::./images/spotter-embed-legacy.png[Spotter embed]
+
+In Spotter 3 embedding, you can load the page with a pre-selected data source or use the *Auto mode* to allow Spotter to automatically discover and select a relevant data model for user queries.
+
+**Default view**:
+
+[.widthAuto]
+[.bordered]
+image::./images/spotter3-legacy-interface.png[Spotter 3 interface]
+
+**With Auto mode enabled**:
+
+[.widthAuto]
+[.bordered]
+image::./images/spotter3-leagcy-interface-automode.png[Spotter 3 interface]
+
+[NOTE]
+====
+When Auto mode is enabled, **Preview data** and **Data Model instructions** options will not be available.
+====
+
+== Chat interface
+Spotter 3 experience is available with a new prompt interface that includes additional features and user elements to enrich your Spotter experience.
+
+To enable the new chat interface in your embed, set the `updatedSpotterChatPrompt` attribute:
+
+[source,JavaScript]
+----
+const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), {
+ // ...other embed configuration attributes
+ // Enable the updated Spotter chat prompt experience.
+ updatedSpotterChatPrompt: true,
+});
+----
+
+[.widthAuto]
+[.bordered]
+image::./images/spotter3-new-interface.png[Spotter 3 new interface]
+
+=== Chat history panel
+You can also include the *Chat history* panel to allow your users to access the chat history from their previous sessions. To enable and customize the chat history sidebar, configure the chat history properties in the `spotterSidebarConfig` object:
+
+[source,JavaScript]
+----
+import {
+ SpotterEmbed,
+ SpotterEmbedViewConfig,
+ SpotterSidebarViewConfig
+} from '@thoughtspot/visual-embed-sdk';
+
+const embed = new SpotterEmbed('#tsEmbed', {
+ // ...other embed view configuration options
+ // Configuration for the Spotter sidebar UI
+ spotterSidebarConfig: {
+ enablePastConversationsSidebar: true, // Enable the chat history sidebar
+ spotterSidebarDefaultExpanded: true, // Expand the sidebar by default
+ spotterSidebarTitle: 'Chat History', // Custom sidebar header text
+ spotterNewChatButtonTitle: 'New Conversation', // Custom label for the New chat button
+ spotterChatRenameLabel: 'Rename session', // Custom label for the Rename action
+ spotterChatDeleteLabel: 'Delete session', // Custom label for the Delete action
+ spotterConversationsBatchSize: 20, // Conversations fetched per batch (default: 30)
+ spotterDocumentationUrl: 'https://your-help-center-url', // Custom best practices link
+ },
+})
+----
+
+[NOTE]
+====
+The standalone `enablePastConversationsSidebar` property on `SpotterEmbedViewConfig` is deprecated from Visual Embed SDK v1.47.0. Use the `enablePastConversationsSidebar` property within the `spotterSidebarConfig` object instead. When both properties are defined, the value in `spotterSidebarConfig` takes precedence.
+====
+
+== Spotter Analysts
+ThoughtSpot allows users to create and manage AI agents (Analysts) directly within the Spotter interface. These AI agents or bots are referred to as link:https://docs.thoughtspot.com/cloud/latest/spotter-analysts[Spotter Analysts, window=_blank]. Each Analyst is scoped to a data model and can be configured with custom instructions, personas, and conversation starters.
+
+If you have Spotter Analysts on your ThoughtSpot instance, you can make these available to your embedding application users.
+
+=== Spotter Analyst panel
+If your ThoughtSpot instance has Spotter Analysts, the Spotter Analysts panel and dashboard are visible by default in the Spotter sidebar in the embed view. To control the visibility of this panel in the embed view, use the `SpotterAnalystSidebar` action ID in the `disabledActions`, `hiddenActions`, or `visibleActions` arrays as needed.
+
+If Spotter Analysts are enabled in the embed view, you can use the following action IDs to show or hide the menu actions:
+
+* `Action.CreateAnalyst` +
+Action ID for the **Create new** action in the Spotter Analysts page.
+* `Action.EditAnalyst` +
+Action ID for the Analyst edit option.
+* `Action.CopyAnalyst` +
+Action ID for the *Make a copy* action that creates a copy of the Analyst.
+* `Action.ShareAnalyst` +
+Action ID for the share action that allows sharing an Analyst with other users.
+* `Action.DeleteAnalyst` +
+Action ID for the delete option.
+
+[source,JavaScript]
+----
+const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), {
+ // ...other embed view configuration options
+ hiddenActions: [
+ Action.CreateAnalyst,
+ Action.DeleteAnalyst,
+ ],
+});
+----
+
+=== Analysts label strings
+Use `spotterAnalystLabel` and `spotterAnalystsLabel` to replace the default "Analyst" and "Analysts" label text in the embedded Spotter interface with custom terminology suited to your application:
+
+[source,JavaScript]
+----
+const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), {
+ // ...other embed view configuration options
+ // Custom label for a single Analyst (default: "Analyst")
+ spotterAnalystLabel: 'AI Assistant',
+ // Custom label for the Analysts section heading (default: "Analysts")
+ spotterAnalystsLabel: 'AI Assistants',
+});
+----
+
+== Quick search and deep analysis mode
+When Spotter 3 experience is enabled on a ThoughtSpot instance, the Spotter interface displays a switcher to toggle between the Quick Search and Deep Analysis modes.
+
+To show, hide, or disable this feature in the embedded view, use the action ID,
+`Action.SpotterChatModeSwitcher`.
+
+[source,JavaScript]
+----
+const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), {
+ // ...other embed view configuration options
+ hiddenActions: [
+ Action.SpotterChatModeSwitcher,
+ ],
+});
+----
+
+== Spotter starter prompts
+ThoughtSpot allows users to preselect prompts and display these prompts in the Spotter interface for quick analysis. This feature is disabled by default in the embedded view. To enable this feature, contact ThoughtSpot Support.
+
+When this feature is enabled on your instance, you can use the `enableStarterPrompts` property in the `spotterChatConfig` object to display the starter prompts to your embedding application users. These prompts appear below the search bar when the users open the Spotter embedded view.
+
+[source,JavaScript]
+----
+const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), {
+ // ...other embed view configuration options
+ spotterChatConfig: {
+ enableStarterPrompts: true,
+ },
+});
+----
+
+[#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.
+
+* Connector icon that allows you to connect to external applications such as Google Drive, Slack, Notion, Confluence, or Jira, which can be used as a data source in Spotter sessions. These connectors must be preconfigured by your ThoughtSpot administrator for your embedding deployments.
+* Add files (+) icon for uploading files and resources for setting the conversation context.
+* **Connectors** menu with a `+` icon in the prompt panel that lets your application users connect to external tools and resources.
+
+These integrations allow users to include both structured and unstructured data in their conversation sessions.
+
+To show, hide, or disable these options, use the following action IDs in the `disabledActions`, `hiddenActions`, or `visibleActions` arrays as needed:
+
+* `Action.SpotterChatConnectors` for the Connectors list.
+* `Action.SpotterChatConnectorResources` for the connector resources section.
+
+[source,JavaScript]
+----
+const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), {
+ // ...other embed view configuration options
+ hiddenActions: [
+ Action.SpotterChatConnectors,
+ Action.SpotterChatConnectorResources,
+ ],
+});
+spotterEmbed.render();
+----
+
+[#fileUpload]
+== File uploads in Spotter chats
+To enable file uploads in the Spotter chat panel:
+
+. Ensure that `spotterFileUploadEnabled` is set to `true` in the `spotterChatConfig` object. This setting enables the **+ Add files** option in the Spotter chat panel.
+. Optionally, you can restrict the types of files users can upload by specifying the file types in the `spotterFileUploadFileTypes` array. If no file format is specified, all supported file types are allowed for uploads.
+
+[source,JavaScript]
+----
+const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), {
+ //...
+ spotterChatConfig: {
+ spotterFileUploadEnabled: true,
+ spotterFileUploadFileTypes: ['pdf', 'png', 'xlsx'],
+ },
+});
+----
+
+////
+For earlier SDK versions, you can use CSS selectors as a workaround:
+
+[source,JavaScript]
+----
+init({
+ thoughtSpotHost: 'https://your-thoughtspot-host', // URL of your ThoughtSpot instance
+ authType: AuthType.None, // Authentication type; use appropriate AuthType for your environment
+ customizations: {
+ style: {
+ customCSS: {
+ rules_UNSTABLE: {
+ // Hide the MCP connectors module in the Spotter prompt panel
+ ".button-module__buttonWrapper.chat-connector-resources-module__addConnectorResourceButton": {
+ "display": "none !important"
+ },
+ // Hide the add resources (+) icon in the Spotter prompt panel
+ "button.button-module__button.button-module__buttonWithIcon.button-module__tertiary.button-module__sizeM.button-module__backgroundLight.button-module__both": {
+ "display": "none !important"
+ }
+ }
+ }
+ }
+ },
+ // ...other configuration attributes
+});
+----
+////
+
+== Spotter icon customization
+To override an icon, you must find the ID of the icon, create an SVG file to replace this icon, and add the SVG hosting URL to your embed customization code. The most common icon to override is the default Spotter icon and its icon ID is `rd-icon-spotter`.
+
+The following example uses the link:https://github.com/thoughtspot/custom-css-demo/blob/main/alternate-spotter-icon.svg[alternate-spotter-icon.svg, window=_blank] file hosted on `\https://cdn.jsdelivr.net/` to override the Spotter icon.
+
+[source,JavaScript]
+----
+ init({
+ //...
+ customizations: {
+ // Specify the SVG hosting URL to override the icon, for example Spotter (`rd-icon-spotter`) icon
+ iconSpriteUrl: "https://cdn.jsdelivr.net/gh/thoughtspot/custom-css-demo/alternate-spotter-icon.svg"
+ }
+ });
+----
+
+The following figures show the customized Spotter icon:
+[.widthAuto]
+[.bordered]
+image::./images/spotter-icon-customization.png[Spotter icon customization]
+
+=== Spotter logo and ThoughtSpot branding label
+To hide the Spotter logo and branding in the chat interface and tool response, use the following `SpotterChatViewConfig` object properties:
+
+* `hideToolResponseCardBranding` +
+When set to `true`, hides the ThoughtSpot logo and icon in tool response cards. The branding label prefix is controlled separately via `toolResponseCardBrandingLabel`.
+
+* `toolResponseCardBrandingLabel` +
+Custom label to replace the `ThoughtSpot` prefix in tool response cards. Set to an empty string (`''`) to hide the prefix entirely.
+
+Example::
++
+[source,JavaScript]
+----
+import {
+ SpotterEmbed,
+ SpotterEmbedViewConfig,
+ SpotterChatViewConfig
+} from '@thoughtspot/visual-embed-sdk';
+
+const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), {
+ // ...other embed view configuration options
+ spotterChatConfig: {
+ // Hide the default logo and label on tool response cards in Spotter chat UI
+ hideToolResponseCardBranding: true,
+ // Set a custom label to display as the branding on tool response cards
+ toolResponseCardBrandingLabel: 'CompanyName',
+ },
+});
+----
+
+== Styles and interface elements
+The Visual Embed SDK provides a comprehensive style customization framework for overriding icons, text strings, and the appearance of UI elements.
+
+The `customizations` object allows you to add custom CSS definitions, replace text strings, and override icons. If your customization framework uses external sources or hosting servers, ensure they are added to the CSP allowlist. For more information, see the xref:css-customization.adoc[CSS customization framework], xref:customize-text-strings.adoc[Customize text strings], and xref:customize-icons.adoc[Customize icons] sections.
+
+[#SpotterCSS]
+=== CSS variables for style customization
+You can customize the background color of the conversation and prompt panels, button elements, and the components of the charts generated by Spotter using xref:customize-css-styles.adoc[CSS variables].
+
+If Theme Builder is enabled on your ThoughtSpot instance, you can find the variables for Spotter customization by navigating to *Develop* > *Customizations* > *Theme Builder* in the ThoughtSpot UI and downloading the CSS variables.
+
+[source,JavaScript]
+----
+// Initialize the SDK with CSS variables with custom style definitions
+init({
+ // ...
+ customizations: {
+ style: {
+ // Use CSS variables to customize styles
+ customCSS: {
+ variables: {
+ "--ts-var-button--primary-background": "#008000",
+ "--ts-var-spotter-prompt-background": "#F0EBFF",
+ "--ts-var-root-color": "#E3D9FC",
+ "--ts-var-root-background": "#F7F5FF",
+ },
+ },
+ },
+ },
+});
+----
+
+=== Text string customization
+To replace text strings, you can use the `stringIDs` and `strings` properties in the content customization object.
+
+The following example shows how to replace "Spotter" and other text strings on the Spotter interface.
+
+[source,JavaScript]
+----
+// Initialize the SDK with custom text string replacements
+init({
+ // ...
+ customizations: {
+ content: {
+ // Use the strings object to replace the visible UI text with custom labels.
+ strings: {
+ // Change all instances of "Preview data" to "Show data"
+ "Preview data": "Show data",
+ // Change all instances of "Spotter" to "dataAnalyzer"
+ "Spotter": "dataAnalyzer",
+ }
+ }
+ }
+});
+----
+
+[#spotterMenuActions]
+=== Menu elements and action visibility
+The SDK provides action IDs to disable, show, or hide the following elements and menu actions via `disabledActions`, `visibleActions`, or `hiddenActions` arrays.
+
+For example, you can hide the *Preview data*, *Reset* in the prompt panel, or *Pin*, *Download*, and other actions from a Spotter-generated response.
+
+The following code sample disables actions and menu elements using the xref:embed-actions.adoc[`disabledActions`] array:
+
+[source,JavaScript]
+----
+ // Hide these actions
+ hiddenActions: [Action.Pin,Action.ResetSpotterChat,Action.DeletePreviousPrompt],
+ // Disable actions
+ disabledActions:[Action.PreviewDataSpotter,Action.Edit],
+ disabledActionReason: "Contact your administrator to enable this feature"
+----
+For a comprehensive list of supported actions, see xref:Action.adoc[Spotter menu actions].
+
+== Additional resources
+* xref:embed-ai-analytics.adoc[Spotter features and embedding options]
+* link:https://developers.thoughtspot.com/docs/Class_SpotterEmbed[SpotterEmbed classes and methods]
+* link:https://developers.thoughtspot.com/docs/Interface_SpotterEmbedViewConfig[Configuration options for Spotter interface customization]
+* link:https://github.com/thoughtspot/developer-examples/tree/main/visual-embed/spotter/spotter-embed[Developer examples, window=_blank]
+* link:https://docs.thoughtspot.com/cloud/latest/spotter[Spotter Product Documentation]
diff --git a/modules/ROOT/pages/customize-style.adoc b/modules/ROOT/pages/customize-style.adoc
index 45798283f..8f9d7c374 100644
--- a/modules/ROOT/pages/customize-style.adoc
+++ b/modules/ROOT/pages/customize-style.adoc
@@ -6,7 +6,7 @@
:page-pageid: customize-style
:page-description: Rebrand embedded ThoughtSpot content
-If you want to match the look and feel of embedded ThoughtSpot content with your core application, you can customize the ThoughtSpot application UI elements. Using style customization, you can create a uniform ThoughtSpot experience that complies with your company’s branding guidelines.
+If you want to match the look and feel of embedded ThoughtSpot content with your core application, you can customize the ThoughtSpot application UI elements. Using style customization, you can create a uniform ThoughtSpot experience that complies with your company's branding guidelines.
You can rebrand the ThoughtSpot interface elements such as the application logo, background color, and color scheme of visualizations.
[NOTE]
@@ -68,13 +68,16 @@ image::./images/style-applogo.png[Default Application Logo]
+
image::./images/style-widelogo.png[Wide application logo]
++
+// SOURCE: SCAL-319679 (doc task: SCAL-323307) — engineering commit 821c07db scaligent #64156
+// CHANGE: Updated wide logo recommended size from 330px by 100px to 250px by 50px (5:1 ratio)
+// Effective from: ThoughtSpot Cloud 26.8.0.cl
+
[NOTE]
====
* The application logo (wide) appears on the login screen.
-
-* The recommended size is 330px by 100px. This will allow the system to preserve the aspect ratio of the uploaded logo image and prevent distortion.
-
+* The recommended size is 250px by 50px (5:1 aspect ratio). This allows the system to preserve the aspect ratio of the uploaded logo image and prevent distortion.
+* The wide logo dimensions have changed in ThoughtSpot Cloud 26.8.0.cl and later versions. If you previously uploaded a logo sized at 330px by 100px, re-upload your logo at 250px by 50px to ensure it displays correctly on the login screen without distortion.
* The accepted file formats for the logo image are jpg, jpeg, and png.
====
@@ -181,67 +184,42 @@ To change the color palette for charts:
. To access the ThoughtSpot Developer portal, click *Develop*
. Under *Customizations*, click *Styles*.
-. Click the background color box under *Chart Color Palettes*.
-. Click the color you would like to change in the *primary* color palette, and use the color menu to choose your new color.
+. Click the color box under *Chart Color Palettes*.
+
-You can also add a HEX color code.
-. Click the color you would like to change in the *secondary* color palette, and use the color menu to choose your new color.
-You can also add a HEX color code.
-+
-The colors from the secondary color palette are used after all of the primary colors from the primary palette have been exhausted.
-Therefore, the secondary palette usually consists of secondary colors.
-
-=== Configure color rotation
+image::./images/chart-colors.png[Chart Color Palettes]
-If the chart requires only one color, ThoughtSpot selects a primary color depending on whether you enabled color rotation. The *Color rotation* feature determines whether single-color charts use a random primary color or always use the first primary color in the palette. If you enable Color Rotation, ThoughtSpot picks colors randomly and may choose any color from Primary 1 through Primary 6 in your color palette for single-color charts. If you disable Color Rotation, ThoughtSpot always chooses Primary 1.
+. To choose a primary color, click the color box.
++
+image::./images/select-color.png[Select Primary Color]
-If you disable color rotation, ThoughtSpot generates single-color charts in the order of your color palette, left to right.
+. You can also add a HEX color code.
+. To add more colors, click *Add Color*.
+. To reset your chart colors to the ThoughtSpot default, click *Reset*.
[#footer-text]
== Customize footer text
-You can customize the footer text in your ThoughtSpot instance to add your company-specific message.
-To customize or rebrand the footer text, follow these steps:
+You can add custom footer text to the ThoughtSpot UI.
+
+To customize footer text:
. To access the ThoughtSpot Developer portal, click *Develop*
. Under *Customizations*, click *Styles*.
-. Click the text box under *Footer text* and enter the message.
-+
-Your custom message will appear in the footer.
-
-////
-. Add `?customBrandingEnabled=true` to your application URL as shown in the following examples:
-+
-----
-https://{ThoughtSpot-Host}/?customBrandingEnabled=true/#/
-----
-+
-----
-https://{ThoughtSpot-Host}/?customBrandingEnabled=true/#/pinboards
-----
-. Go to *Admin* > *Application settings* > *Style customization* or *Develop* > *Customizations* > *Styles*.
-+
-You require administrator or developer privilege to apply custom styles and footer text.
-. Click the text box under *Footer text* and enter the message.
-+
-Your custom message will appear in the footer.
-. To enable footer text customization on your cluster by default, contact ThoughtSpot Support.
-////
+. Add the footer text in the *Footer Text* box.
-////
[#page-title]
== Customize page title
-To customize the page title displayed in the browser bar:
+You can customize the page title that appears in the browser tab.
+
+To customize the page title:
. To access the ThoughtSpot Developer portal, click *Develop*
. Under *Customizations*, click *Styles*.
-. Click the text box under *Page title*.
-. Enter your new text message.
-////
-
-== Reset styles
+. Add the page title in the *Page Title* box.
-When you customize styles, the changes take effect after you refresh the browser.
+== Related resources
-To revert your changes, use the *Reset* button that appears when you move your cursor to the right of the style setting option.
+* link:https://docs.thoughtspot.com/cloud/latest/style-customization[Style Customization in ThoughtSpot, window=_blank]
+* xref:embed-liveboard.adoc[Embed Liveboards]
+* xref:full-app-customize.adoc[Customize the full application]
diff --git a/modules/ROOT/pages/data-report-v2-api.adoc b/modules/ROOT/pages/data-report-v2-api.adoc
index b95b51895..f32d57f79 100644
--- a/modules/ROOT/pages/data-report-v2-api.adoc
+++ b/modules/ROOT/pages/data-report-v2-api.adoc
@@ -245,7 +245,7 @@ The default `file_format` is *CSV*.
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 [earlyAccess eaBackground]#Early Access#,
+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.
@@ -269,14 +269,14 @@ curl -X POST \
}'
----
-For *XLSX* downloads [earlyAccess eaBackground]#Early Access#,
+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. To enable this on your ThoughtSpot instance, contact ThoughtSpot Support.
+* 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
@@ -299,12 +299,11 @@ For *PDF* downloads, you can specify additional parameters to customize the page
You can now also download continuous pdfs which matches the full length of your Liveboard, without breaking them into multiple A4 pages.
-* `page_size = CONTINUOUS` [beta betaBackground]^Beta^ Unlike the A4 format, which introduces forced page breaks between visualizations, this continuous flow maintains your exact design and intended layout.
+* `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` [beta betaBackground]^Beta^ 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.
+* `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.
-To enable this on your ThoughtSpot instance, contact ThoughtSpot Support.
===== Sample API payload for PDF downloads
@@ -335,11 +334,9 @@ curl -X POST 'https://{ThoughtSpot-Host}/api/rest/2.0/report/liveboard' \
For *PNG* downloads, you can now define
-* `image_resolution` [earlyAccess eaBackground]#Early Access#
-* `image_scale` [earlyAccess eaBackground]#Early Access#
-* `include_header` [earlyAccess eaBackground]#Early Access#
-
-Contact ThoughtSpot support to enable these settings for PNG downloads on your ThoughtSpot instance.
+* `image_resolution`
+* `image_scale`
+* `include_header`
[IMPORTANT]
====
diff --git a/modules/ROOT/pages/embed-pinboard.adoc b/modules/ROOT/pages/embed-pinboard.adoc
index 3d8d67eee..acabc5b2a 100644
--- a/modules/ROOT/pages/embed-pinboard.adoc
+++ b/modules/ROOT/pages/embed-pinboard.adoc
@@ -10,6 +10,7 @@ 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:
diff --git a/modules/ROOT/pages/embed-spotter.adoc b/modules/ROOT/pages/embed-spotter.adoc
index eaaf2b1a0..01fbdf608 100644
--- a/modules/ROOT/pages/embed-spotter.adoc
+++ b/modules/ROOT/pages/embed-spotter.adoc
@@ -35,14 +35,13 @@ import {
prefetch,
EmbedEvent,
HostEvent
-}
-from '@thoughtspot/visual-embed-sdk';
+} from '@thoughtspot/visual-embed-sdk';
----
**ES6**
[source,JavaScript]
----
-
----
== Initialize the SDK
@@ -132,7 +131,6 @@ spotterEmbed.on(EmbedEvent.Subscribed, (eventData) => {
});
----
-
To trigger actions on the embedded interface, use the xref:HostEvent.adoc[Host events].
The following example shows the host event to reset a Spotter conversation session:
@@ -164,291 +162,7 @@ spotterEmbed.render();
[#configControls]
== Customizing the embedded Spotter interface
-When you embed Spotter, you'll notice that the embedded component loads an initial page with a prompt interface. The look and feel of this page vary depending on the Spotter version used for embedding.
-
-=== Spotter Classic and Spotter 2 experiences
-If you have embedded Spotter Classic or Spotter 2, the initial page includes a prompt bar for user input, a data source selector, and the UI options to preview data and reset a Spotter session.
-
-[.widthAuto]
-[.bordered]
-image::./images/spotter-embed-legacy.png[Spotter embed]
-
-=== Spotter 3 experience
-In Spotter 3 embedding, you can load the page with a pre-selected data source or use the *Auto mode* to allow Spotter to automatically discover and select a relevant data model for user queries.
-
-**Default view**:
-
-[.widthAuto]
-[.bordered]
-image::./images/spotter3-legacy-interface.png[Spotter 3 interface]
-
-**With Auto mode enabled**:
-
-[.widthAuto]
-[.bordered]
-image::./images/spotter3-leagcy-interface-automode.png[Spotter 3 interface]
-
-[NOTE]
-====
-When Auto mode is enabled, **Preview data** and **Data Model instructions** options will not be available.
-====
-
-
-==== New chat interface
-
-Spotter 3 experience is available with a new prompt interface that includes additional features and user elements to enrich your Spotter experience.
-
-To enable the new chat interface in your embed, set the `updatedSpotterChatPrompt` attribute:
-
-[source,JavaScript]
-----
-const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), {
- // ...other embed configuration attributes
- // Enable the updated Spotter chat prompt experience.
- updatedSpotterChatPrompt: true,
-});
-----
-
-[.widthAuto]
-[.bordered]
-image::./images/spotter3-new-interface.png[Spotter 3 new interface]
-
-==== Chat history panel
-
-You can also include the *Chat history* panel to allow your users to access the chat history from their previous sessions.
-
-To enable chat history features, set the `enablePastConversationsSidebar` attribute to `true`. Additionally, you can customize the appearance and contents of the chat history panel using the configuration parameters available in the xref:SpotterSidebarViewConfig.adoc[`SpotterSidebarViewConfig`] interface and the xref:SpotterEmbedViewConfig.adoc#_spottersidebarconfig[spotterSidebarConfig] object.
-
-[source,JavaScript]
-----
-import {
- SpotterEmbed,
- SpotterEmbedViewConfig,
- SpotterSidebarViewConfig
-} from '@thoughtspot/visual-embed-sdk';
-
-const embed = new SpotterEmbed('#tsEmbed', {
- // ...other embed view configuration options
- // Configuration for the Spotter sidebar UI
- spotterSidebarConfig: {
- enablePastConversationsSidebar: true, // Show chat history sidebar
- spotterSidebarTitle: 'My Conversations', // Update the title of the sidebar
- spotterSidebarDefaultExpanded: true, // Expand Spotter chat history sidebar by default on load
- },
-})
-----
-
-[NOTE]
-====
-The standalone `enablePastConversationsSidebar` attribute is deprecated in v1.47.0 and can no longer be used to enable or disable the chat history.
-====
-
-
-==== Chat history panel
-
-To enable and customize the chat history sidebar, configure the chat history properties in the `spotterSidebarConfig` object:
-
-[source,JavaScript]
-----
-const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), {
- // ...
- worksheetId: '<%=datasourceGUID%>',
- spotterSidebarConfig: {
- enablePastConversationsSidebar: true, // Enable the chat history sidebar
- spotterSidebarDefaultExpanded: true, // Expand the sidebar by default
- spotterSidebarTitle: 'Chat History', // Custom sidebar header text
- spotterNewChatButtonTitle: 'New Conversation', // Custom label for the New chat button
- spotterChatRenameLabel: 'Rename session', // Custom label for the Rename action
- spotterChatDeleteLabel: 'Delete session', // Custom label for the Delete action
- spotterConversationsBatchSize: 20, // Conversations fetched per batch (default: 30)
- spotterDocumentationUrl: 'https://your-help-center-url', // Custom best practices link
- },
-});
-----
-
-[NOTE]
-====
-The standalone `enablePastConversationsSidebar` property on `SpotterEmbedViewConfig` is deprecated from Visual Embed SDK v1.47.0. Use the `enablePastConversationsSidebar` property within the `spotterSidebarConfig` object instead. When both properties are defined, the value in `spotterSidebarConfig` takes precedence.
-====
-
-
-==== MCP connectors and resource selection icon
-A connector is an external MCP server or tool, such as Google Drive, Slack, Notion, Confluence, or Jira, which can be used as a data source in Spotter sessions. ThoughtSpot administrators can configure connectors to enable Spotter users to include both structured and unstructured data in their conversation sessions.
-
-If the new prompt interface in Spotter 3 is enabled, the Spotter page displays the *MCP Connectors* menu along with a '\+' icon in the prompt panel. Your application users can connect to a tool preconfigured by your ThoughtSpot administrator directly from the Spotter 3 prompt interface using the '+' icon and add resources to their conversation context.
-
-[NOTE]
-====
-The MCP connector module and the '+' icon are displayed by default if the new prompt interface is enabled in your embed. However, we do not recommend using this feature in your production environments.
-====
-
-Currently, the Visual Embed SDK does not provide any attributes or action IDs to hide these elements. As a workaround, you can use CSS selectors to hide these elements:
-
-[source,JavaScript]
-----
-init({
- thoughtSpotHost: 'https://your-thoughtspot-host', // URL of your ThoughtSpot instance
- authType: AuthType.None, // Authentication type; use appropriate AuthType for your environment
- customizations: {
- style: {
- customCSS: {
- rules_UNSTABLE: {
- // Hide the MCP connectors module in the Spotter prompt panel
- ".button-module__buttonWrapper.chat-connector-resources-module__addConnectorResourceButton": {
- "display": "none !important"
- },
- // Hide the add resources (+) icon in the Spotter prompt panel
- "button.button-module__button.button-module__buttonWithIcon.button-module__tertiary.button-module__sizeM.button-module__backgroundLight.button-module__both": {
- "display": "none !important"
- }
- }
- }
- }
- },
- // ...other configuration attributes
-});
-----
-
-=== Customizing styles and interface elements
-The Visual Embed SDK provides a comprehensive style customization framework for overriding icons, text strings, and the appearance of UI elements.
-
-The `customizations` object allows you to add custom CSS definitions, replace text strings, and override icons. If your customization framework uses external sources or hosting servers, ensure they are added to the CSP allowlist. For more information, see the xref:css-customization.adoc[CSS customization framework], xref:customize-text-strings.adoc[Customize text strings], and xref:customize-icons.adoc[Customize icons] sections.
-
-[#SpotterCSS]
-=== Customize using CSS variables
-You can customize the background color of the conversation and prompt panels, button elements, and the components of the charts generated by Spotter using xref:customize-css-styles.adoc[CSS variables].
-
-If Theme Builder is enabled on your ThoughtSpot instance, you can find the variables for Spotter customization by navigating to *Develop* > *Customizations* > *Theme Builder* in the ThoughtSpot UI and downloading the CSS variables.
-
-[source,JavaScript]
-----
-// Initialize the SDK with CSS variables with custom style definitions
-init({
- // ...
- customizations: {
- style: {
- // Use CSS variables to customize styles
- customCSS: {
- variables: {
- "--ts-var-button--primary-background": "#008000",
- "--ts-var-spotter-prompt-background": "#F0EBFF",
- "--ts-var-root-color": "#E3D9FC",
- "--ts-var-root-background": "#F7F5FF",
- },
- },
- },
- },
-----
-
-==== Customizing text strings
-To replace text strings, you can use the `stringsIDs` and `strings` properties in the content customization object.
-
-The following example shows how to replace "Spotter" and other text strings on the Spotter interface.
-
-[source,JavaScript]
-----
-// Initialize the SDK with custom text string replacements
-init({
- // ...
- customizations: {
- content: {
- // Use the strings object to replace the visible UI text with custom labels.
- strings: {
- // Change all instances of "Preview data" to "Show data"
- "Preview data": "Show data",
- // Change all instances of "Spotter" to "dataAnalyzer"
- "Spotter": "dataAnalyzer",
- }
- }
- }
-});
-----
-
-=== Customizing the Spotter icon
-To override an icon, you must find the ID of the icon, create an SVG file to replace this icon, and add the SVG hosting URL to your embed customization code. The most common icon to override is the default Spotter icon and its icon ID is `rd-icon-spotter`.
-
-The following example uses the link:https://github.com/thoughtspot/custom-css-demo/blob/main/alternate-spotter-icon.svg[alternate-spotter-icon.svg, window=_blank] file hosted on `\https://cdn.jsdelivr.net/` to override the Spotter icon.
-
-[source,JavaScript]
-----
- init({
- //...
- customizations: {
- // Specify the SVG hosting URL to override the icon, for example Spotter (`rd-icon-spotter`) icon
- iconSpriteUrl: "https://cdn.jsdelivr.net/gh/thoughtspot/custom-css-demo/alternate-spotter-icon.svg"
- }
- });
-----
-
-The following figures show the customized Spotter icon:
-[.widthAuto]
-[.bordered]
-image::./images/spotter-icon-customization.png[Spotter icon customization]
-
-=== Hiding the Spotter icon and ThoughtSpot branding from the chat interface
-To hide the Spotter logo and branding in the chat interface, use the following parameters in the `SpotterChatViewConfig` interface:
-
-* `hideToolResponseCardBranding` +
-When set to `true`, hides the ThoughtSpot logo and icon in tool response cards. The branding label prefix is controlled separately via `toolResponseCardBrandingLabel`.
-
-* `toolResponseCardBrandingLabel` +
-Custom label to replace the `ThoughtSpot` prefix in tool response cards. Set to an empty string (`''`) to hide the prefix entirely.
-
-Example::
-+
-[source,JavaScript]
-----
-import {
- SpotterEmbed,
- SpotterEmbedViewConfig,
- SpotterChatViewConfig
-} from '@thoughtspot/visual-embed-sdk';
-
-spotterChatConfig: {
- // Hide the default logo and label on tool response cards in Spotter chat UI
- hideToolResponseCardBranding: true,
- // Set a custom label to display as the branding on tool response cards
- toolResponseCardBrandingLabel: 'CompanyName',
-}
-----
-
-[#fileUpload]
-=== Allowing file uploads in Spotter chats
-To enable file uploads in the Spotter chat panel:
-
-. Ensure that `spotterFileUploadEnabled` is set to `true` in the `spotterChatConfig` object. This setting enables ** + Add files** option in the Spotter chat panel.
-. Optionally, you can restrict the types of files users can upload by specifying the file types in the `SpotterFileUploadFileTypes` array. If no file format is specified, all supported file types are allowed for uploads.
-
-[source,JavaScript]
-----
-const embed = spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), {
- //...
- spotterChatConfig: {
- spotterFileUploadEnabled: true,
- spotterFileUploadFileTypes: { types: ['pdf', 'png', 'xlsx']
- },
-});
-----
-
-[#spotterMenuActions]
-=== Customizing menu actions and elements
-
-The SDK provides action IDs to disable, show, or hide the following elements and menu actions via `disabledActions`, `visibleActions`, or `hiddenActions` arrays.
-
-For example, you can hide the *Preview data*, *Reset* in the prompt panel, or *Pin*, *Download*, and other actions from a Spotter-generated response.
-
-The following code sample disables actions and menu elements using the xref:embed-actions.adoc[`disabledActions`] array:
-
-[source,JavaScript]
-----
- // Hide these actions
- hiddenActions: [Action.Pin,Action.ResetSpotterChat,Action.DeletePreviousPrompt],
- // Disable actions
- disabledActions:[Action.PreviewDataSpotter,Action.Edit],
- disabledActionReason: "Contact your administrator to enable this feature"
-----
-For a comprehensive list of supported actions, see xref:Action.adoc[Spotter menu actions].
-
+When you embed Spotter, you'll notice that the embedded component loads an initial page with a prompt interface. The look and feel of this page vary depending on the Spotter version used for embedding. To learn about the customization options available with the Visual Embed SDK, see xref:customize-spotter-embed.adoc[Customizing the Spotter embed view].
== Code samples
@@ -465,8 +179,7 @@ import {
prefetch,
EmbedEvent,
HostEvent
-}
-from '@thoughtspot/visual-embed-sdk';
+} from '@thoughtspot/visual-embed-sdk';
// Initialize the ThoughtSpot Visual Embed SDK with your ThoughtSpot URL and authentication type.
init({
diff --git a/modules/ROOT/pages/embed-spotterViz.adoc b/modules/ROOT/pages/embed-spotterViz.adoc
index 57c089428..cf059d4dc 100644
--- a/modules/ROOT/pages/embed-spotterViz.adoc
+++ b/modules/ROOT/pages/embed-spotterViz.adoc
@@ -8,7 +8,7 @@
[earlyAccess eaBackground]#Early Access#
-The SpotterViz panel is supported in Liveboards embedded using `LiveboardEmbed` or `AppEmbed` components. ThoughtSpot link:https://docs.thoughtspot.com/cloud/26.6.0.cl/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 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.
[NOTE]
====
diff --git a/modules/ROOT/pages/embed-ts-react-app.adoc b/modules/ROOT/pages/embed-ts-react-app.adoc
index 22f191e43..2c75f3ed8 100644
--- a/modules/ROOT/pages/embed-ts-react-app.adoc
+++ b/modules/ROOT/pages/embed-ts-react-app.adoc
@@ -14,7 +14,12 @@ Before embedding ThoughtSpot, perform the following checks:
=== Prepare your environment
+* Check if link:https://docs.npmjs.com/downloading-and-installing-node-js-and-npm[NPM and Node.js are installed, window=_blank] in your setup. Any link:https://nodejs.org/en/about/previous-releases[active LTS release, window=_blank] of Node.js is recommended for build tooling.
+* Make sure you have installed React 16.8 or later and its dependencies. The SDK declares React and React DOM as peer dependencies at version 16.8 or later. If React is not installed, open a terminal window and run the following command:
+
* Check if link:https://docs.npmjs.com/downloading-and-installing-node-js-and-npm[NPM and Node.js are installed, window=_blank] in your setup.
+
+
* Make sure you have installed React framework and its dependencies. If React is not installed, open a terminal window and run the following command:
+
----
diff --git a/modules/ROOT/pages/full-app-customize.adoc b/modules/ROOT/pages/full-app-customize.adoc
index b4e60b77e..aaa4b8978 100644
--- a/modules/ROOT/pages/full-app-customize.adoc
+++ b/modules/ROOT/pages/full-app-customize.adoc
@@ -1,67 +1,65 @@
-= Customize full application embedding
+= Customize the home page and navigation for full application embedding
:toc: true
:toclevels: 3
-:page-title: Customize full application embedding
+:page-title: Customize the home page and navigation for full application embedding
:page-pageid: full-app-customize
-:page-description: Customize full application embedding
+:page-description: Customize the home page and navigation for full application embedding
-The Visual Embed SDK provides several controls to customize the embedded view, including setting the default landing page, navigation style, visibility of modules and menu items, and more.
+ThoughtSpot supports the following experience modes in full application embedding:
+
+* *V3 experience* (`HomePage.ModularWithStylingChanges`)—The default home page experience as of ThoughtSpot Cloud 26.8.0.cl. Includes the left navigation panel, customizable modules, and styling changes.
+* *V4 experience* (`HomePage.Focused`)—An enhanced home page experience with a focused layout and additional customization options.
[IMPORTANT]
====
-The classic (V1) experience and V2 experience modes will be deprecated in an upcoming release in 2026. Therefore, ThoughtSpot recommends upgrading the UI experience of your full application embedding to the V3 experience.
+The classic V1 and V2 navigation and homepage experience modes are deprecated as of ThoughtSpot Cloud 26.8.0.cl. Starting from this release, all embedded sessions render in the V3 navigation experience by default.
====
-== UI experience modes
-ThoughtSpot application supports the following UI experience modes:
-
-* xref:full-app-customize.adoc#_upgrade_to_the_v3_experience[V3 navigation and home page experience] (__Recommended__)
-* xref:full-app-customize.adoc#_upgrade_from_the_v2_experience_to_v3_experience[V2 navigation and home page experience]
-* Classic (V1) experience (__Default experience__)
-
-The key differences between these UI experience modes are listed in the following table:
-
-[div boxAuto]
---
-[width="100%", cols="2,4,4,5"]
-[options='header']
-
-|=====
-|Feature component |Classic (V1) experience | V2 experience | V3 experience
-|**UI experience**| Classic layout +
-
-Includes a standard top navigation, pages without a left navigation panel, and a static home page with limited customization options.| Improved look and feel +
-
-Includes a modular home page with customizable components, an application selector menu, and a left navigation panel for each application context. | Modern look and feel +
-Includes a left navigation panel that dynamically adjusts its menu based on context and a modular home page with enhanced visual elements and customizable components.
-|**Navigation experience**| Top navigation includes the application menu. +
-Limited customization controls |Redesigned top navigation bar with an app selector and other icons +
-Separate left navigation panel for each application context| Sliding left navigation panel with persona-based application icons +
-A dynamic left navigation menu that adjusts its contents according to the application context.
-|**Home page experience** | Static home page with limited customization control a| Modular home page with customizable components |Modular home page with customizable components, enhanced styling, and visual elements.
-
-[NOTE]
-====
-The SDK also supports a V4 focused home page experience [earlyAccess eaBackground]#Early Access#. For more information, see xref:full-app-customize.adoc#_enable_the_v4_focused_home_page_experience[Enable the V4 focused home page experience].
-====
+== UI experience modes
-|**Feature availability**| Enabled by default| Disabled by default | Disabled by default
-|=====
---
+ThoughtSpot supports V3 and V4 home page and navigation experiences for full application embedding.
+
+[width="100%", cols="5,^3,^3"]
+[options="header"]
+|====
+|Feature |V3 experience +
+`HomePage.ModularWithStylingChanges` |V4 experience +
+`HomePage.Focused`
+|Default experience as of 26.8.0.cl
+|[tag greenBackground tick]#✓# Default
+|[tag redBackground tick]#x# Not default
+|`hideHomepageLeftNav` +
+Hides the left navigation panel on the home page.
+|[tag greenBackground tick]#✓# Supported
+|[tag greenBackground tick]#✓# Supported
+|`hiddenHomepageModules` +
+Hides specific modules on the home page.
+|[tag greenBackground tick]#✓# Supported
+|[tag greenBackground tick]#✓# Supported
+|`reorderedHomepageModules` +
+Reorders modules on the home page.
+|[tag greenBackground tick]#✓# Supported
+|[tag redBackground tick]#x# Not supported
+|`homePageModules` +
+Specifies which modules to show on the home page.
+|[tag greenBackground tick]#✓# Supported
+|[tag redBackground tick]#x# Not supported
+|Left navigation panel customization
+|[tag greenBackground tick]#✓# Supported
+|[tag greenBackground tick]#✓# Supported
+|Custom reordering of left nav items
+|[tag greenBackground tick]#✓# Supported
+|[tag greenBackground tick]#✓# Supported
+|====
**V3 navigation and home page experience**
[.bordered]
[.widthAuto]
image::./images/v3-experience.png[V3 UI experience]
-**V2 navigation and home page experience**
-[.bordered]
-[.widthAuto]
-image::./images/v2-experience.png[V2 UI experience]
-
-**V1 Classic experience**
+**Classic (V1) navigation and home page experience**
[.bordered]
[.widthAuto]
image::./images/v1-experience.png[Classic experience]
@@ -94,70 +92,13 @@ Enables the modular or focused home page experience. Valid values include:
Enables the V3 modular home page experience. You must include `primaryNavbarVersion` to update the UI experience to the V3 home page.
** `HomePage.Focused` [earlyAccess eaBackground]#Early Access#
Enables the V4 focused home page experience, which consolidates the **Watchlist** and **Recents** sections into a single, focused view. +
-** `HomePage.Modular` +
-Enables the modular home page experience with customizable components. This experience does not include the styling options and visual changes available with the full V3 experience. We do not recommend using this option, as it will be deprecated in an upcoming release.
-
-
-[IMPORTANT]
-====
-* To enable the full V3 experience, both `primaryNavbarVersion` and `homePage` attributes must be set in the SDK. Not setting `primaryNavbarVersion` will result in no changes to the UI experience.
-* If you include only the `homePage: HomePage.ModularWithStylingChanges` attribute in `discoveryExperience`, it will be ignored. +
-* If you include only the homePage attribute with its value as `HomePage.Modular`, the V2 modular home page experience will be enabled.
-
-For information about these configuration combinations and their effects, see xref:full-app-customize.adoc#_ui_customization_options_and_resulting_experience[UI customization options and resulting experience].
-====
-
-==== Upgrade from classic (V1) experience to V3 experience
-To enable the V3 experience, set the `primaryNavbarVersion` and `homePage` parameters in the `discoveryExperience` object as shown in the following example.
-
-Note that these attributes use the values from the xref:PrimaryNavbarVersion.adoc[PrimaryNavbarVersion] and xref:HomePage.adoc[HomePage] enumerations.
-
-[source,JavaScript]
-----
-// Import required components and enums for V3 experience
-import {
- AppEmbed, // Main class to embed the full ThoughtSpot app
- HomePage, // Enum for home page experience settings
- PrimaryNavbarVersion // Enum for V3 navigation experience
-} from '@thoughtspot/visual-embed-sdk';
-
-const embed = new AppEmbed("#embed", {
- // Enable V3 navigation and home page experience
- discoveryExperience: {
- primaryNavbarVersion: PrimaryNavbarVersion.Sliding, // Enable V3 navigation
- homePage: HomePage.ModularWithStylingChanges, // Enable V3 home page experience
- },
- // Show navigation panels
- showPrimaryNavbar: true,
- //... other embed view configuration attributes
-});
-----
-
-==== Upgrade from the V2 experience to V3 experience
-Both V2 and V3 experience modes support a modular home page with customizable components. The V3 modular home page experience includes additional improvements to the Watchlist, Trending, Learning, and Favorites panels.
-To upgrade your UI to the V3 experience, set `homePage` to `HomePage.ModularWithStylingChanges`:
+////
-[source,JavaScript]
-----
-// Import required components and enums for V3 experience
-import {
- AppEmbed, // Main class to embed the full ThoughtSpot app
- HomePage, // Enum for home page experience settings
- PrimaryNavbarVersion // Enum for V3 navigation experience
-} from '@thoughtspot/visual-embed-sdk';
+** `HomePage.Modular` +
+Enables the modular home page experience with customizable components. This experience does not include the styling options and visual changes available with the full V3 experience. We do not recommend using this option, as it will be deprecated in an upcoming release.
+////
-const embed = new AppEmbed("#embed", {
- // Enable V3 navigation and home page experience
- discoveryExperience: {
- primaryNavbarVersion: PrimaryNavbarVersion.Sliding, // Enable V3 navigation experience
- homePage: HomePage.ModularWithStylingChanges, // Enable V3 modular home page
- },
- // Show navigation panels
- showPrimaryNavbar: true,
- //... other embed view configuration attributes
-});
-----
[#_enable_the_v4_focused_home_page_experience]
=== Enable the V4 focused home page experience
@@ -181,56 +122,27 @@ import {
} from '@thoughtspot/visual-embed-sdk';
const embed = new AppEmbed("#embed", {
- discoveryExperience: {
- primaryNavbarVersion: PrimaryNavbarVersion.Sliding, // Enable V3 navigation experience
- homePage: HomePage.Focused, // Enable V4 focused home page experience
- },
- showPrimaryNavbar: true,
- //... other embed view configuration attributes
+ discoveryExperience: {
+ primaryNavbarVersion: PrimaryNavbarVersion.Sliding, // Enable V3 navigation experience
+ homePage: HomePage.Focused, // Enable V4 focused home page experience
+ },
+ showPrimaryNavbar: true,
+ //... other embed view configuration attributes
});
----
-==== Post migration checks
+==== Post upgrade checks
After you enable the V3 experience:
-* Ensure the UI shows the V3 navigation and home page.
-
-////
-+
-The following figure shows the user interface with the V3 experience:
-+
-[.bordered]
-[.widthAuto]
-image::./images/new-nav3.png[New home page]
-////
+* Verify whether the UI shows the new navigation and home page by default.
* 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.
-////
-=== Upgrade from classic (V1) experience to V2 experience
-Setting `modularHomeExperience` to `true` in the SDK enables the V2 experience.
-
-[source,javascript]
-----
-const embed = new AppEmbed("#embed", {
- // Enable the V2 experience
- modularHomeExperience: true,
- //... other view config attributes
-});
-----
-
-[NOTE]
-====
-The V2 experience will be deprecated in an upcoming release. ThoughtSpot strongly recommends upgrading to the V3 experience to ensure continued support and access to the latest features.
-====
-
-The following figure shows the user interface with the V2 experience enabled:
-
[.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:
@@ -352,7 +264,7 @@ a|`false`
| V3 navigation and V4 home page experience
|===
--
-
+////
== Customize navigation experience
@@ -368,9 +280,9 @@ In full application embedding, the home page is set as the default landing page
A list page in ThoughtSpot refers to a page that displays a list of objects, such as Answers, Liveboards, and Liveboard schedules. The list pages include columns for sorting, filtering, tagging, sharing, or deleting objects.
=== List layouts
-If your embed has the V3 navigation and homepage experience enabled, the ListPage v3 experience will be enabled by default.
+If your embed has the V3 navigation and homepage experience enabled, the ListPage V3 experience is enabled by default.
-The list layouts in full app embedding typically include columns such as *Name*, *Author*, *Favorites*, *Tags*, *Last Viewed* and more. For Liveboard lists, a *Verified* column is available to filter the list by verified objects. In addition to these columns, the ListPage v3 experience includes the **Views** column and the following enhancements:
+The list layouts in full app embedding typically include columns such as *Name*, *Author*, *Favorites*, *Tags*, *Last Viewed* and more. For Liveboard lists, a *Verified* column is available to filter the list by verified objects. In addition to these columns, the ListPage V3 experience includes the **Views** column and the following enhancements:
* Sorting options for **Name**, **Author**, and **Views** columns.
* Filter addition by clicking the column header without opening the filter modal. This option is available for **Favorites**, **Views** columns, and **Verified** columns.
@@ -398,7 +310,8 @@ const embed = new AppEmbed("#embed", {
// hide Author, Share, and Tags columns on Answers and Liveboards listing pages
hiddenListColumns: [
ListPageColumns.Author,
- ListPageColumns.Share
+ ListPageColumns.Share,
+ ListPageColumns.Tags
],
//... other view config attributes
@@ -413,7 +326,7 @@ The `hiddenListColumns: [ListPageColumns.Share]` hides the *Share* column, but d
== Additional customization controls
xref:css-customization.adoc[CSS customization] allows overriding default styles in ThoughtSpot application pages. You can also use xref:theme-builder.adoc[Theme Builder] to explore the available CSS variables.
-If there is a page element you cannot hide using ThoughtSpot or Visual Embed SDK options, you can use a CSS selector to target the element and apply CSS properties such as `display: none`;, `visibility: hidden`;, or `height: 0px` to hide it from the UI. To find the appropriate selector, use your browser’s *Inspect* tool to examine the style element in the *Elements* section of the browser's Developer Tools.
+If there is a page element you cannot hide using ThoughtSpot or Visual Embed SDK options, you can use a CSS selector to target the element and apply CSS properties such as `display: none`, `visibility: hidden`, or `height: 0px` to hide it from the UI. To find the appropriate selector, use your browser's *Inspect* tool to examine the style element in the *Elements* section of the browser's Developer Tools.
[source,css]
----
@@ -427,7 +340,6 @@ An example of using direct selectors in a file is available in the link:https://
You can also declare direct selectors using the xref:css-customization.adoc#_css_rules_using_selectors[rules] property in the Visual Embed SDK configuration. This is useful for real-time testing, especially in the Visual Embed SDK playground. Note the required format for encoding CSS rules as JavaScript objects.
-
== Additional resources
* xref:full-embed.adoc[Embed full application]
@@ -436,4 +348,9 @@ You can also declare direct selectors using the xref:css-customization.adoc#_css
* xref:HostEvent.adoc[Host events]
* xref:EmbedEvent.adoc[Embed Events]
+== Related resources
+* xref:customize-nav-full-embed.adoc[Customize the navigation for full application embedding]
+* xref:customize-homepage-full-embed.adoc[Customize the home page for full application embedding]
+* xref:full-embed.adoc[Embed full application]
+* link:https://developers.thoughtspot.com/docs/typedoc/interfaces/AppViewConfig.html[AppViewConfig reference, window=_blank]
\ No newline at end of file
diff --git a/modules/ROOT/pages/getting-started.adoc b/modules/ROOT/pages/getting-started.adoc
index 803f62516..2a9165058 100644
--- a/modules/ROOT/pages/getting-started.adoc
+++ b/modules/ROOT/pages/getting-started.adoc
@@ -208,7 +208,15 @@ lb.trigger(HostEvent.UpdateRuntimeFilters, [{
`#container` is a selector for the DOM node which the code assumes is already attached to DOM. The SDK will render the ThoughtSpot component inside this container element.
== Embed in a React app
-ThoughtSpot provides React components for embedding Search, Liveboard, and the full ThoughtSpot application in a React app. The following code sample shows how to embed a Liveboard component in a React app:
+ThoughtSpot provides React components for embedding Search, Liveboard, and the full ThoughtSpot application in a React app.
+
+[NOTE]
+====
+If you are embedding ThoughtSpot using the React components (`@thoughtspot/visual-embed-sdk/react`), React 16.8 or later and React DOM are required as peer dependencies in your project. +
+For information about React version support, see link:https://react.dev/versions[React releases, window=_blank].
+====
+
+The following code sample shows how to embed a Liveboard component in a React app:
[source,TypeScript]
----
diff --git a/modules/ROOT/pages/mcp-server-inline-viz.adoc b/modules/ROOT/pages/mcp-server-inline-viz.adoc
new file mode 100644
index 000000000..890c50f95
--- /dev/null
+++ b/modules/ROOT/pages/mcp-server-inline-viz.adoc
@@ -0,0 +1,95 @@
+= MCP Server — Inline Visualizations
+:toc: true
+:toclevels: 2
+
+:page-title: MCP Server Inline Visualizations
+:page-pageid: mcp-server-inline-viz
+:page-description: Use the ThoughtSpot MCP Server to render non-interactive inline visualizations in AI agent workflows.
+
+// SOURCE: SCAL-303476
+// ⚠️ STATUS: HARD GATE — DO NOT PUBLISH
+// SCAL-303476 status is "In Design" as of 2026-07-10.
+// This page must not be published until all of the following are confirmed:
+// 1. Feature is confirmed GA or EA for jul.26.mt
+// 2. Engineering provides the inline visualization spec (MCP tool name, response schema, config options)
+// 3. At least one confirmed code or config example is reviewed by the MCP / AI Modeling team
+// 4. Feature name is confirmed ("Inline Visualizations" vs. "Non-Interactive Visualizations" vs. another label)
+// Owner for sign-off: Shannon Thompson / MCP team (SCAL-303476)
+// TODO: [WRITER] Remove this gate comment block and update all TODOs once feature ships and engineering provides spec.
+// TODO: [WRITER] Confirm whether this content should be a new standalone page or a section within the existing MCP Server page (mcp-server.adoc). Merge accordingly.
+// TODO: [WRITER] Confirm the exact MCP tool name(s) exposed for inline visualization rendering.
+// TODO: [WRITER] Add a cross-reference from mcp-server.adoc to this page once confirmed.
+
+[NOTE]
+====
+// TODO: [WRITER] Update this callout with the confirmed release milestone and EA/GA status.
+MCP Server inline visualizations are planned for the ThoughtSpot jul.26.mt release. This page will be updated once the feature is confirmed available.
+====
+
+The ThoughtSpot MCP (Model Context Protocol) Server Phase 2 introduces support for rendering non-interactive inline visualizations directly within AI agent responses. With inline visualizations, AI agents powered by the ThoughtSpot MCP Server can return chart and table data as rendered visual outputs alongside natural language answers, without requiring the user to navigate to ThoughtSpot or interact with the visualization.
+
+== Before you begin
+
+// TODO: [WRITER] Confirm prerequisites with the MCP / AI Modeling team.
+// TODO: [WRITER] Confirm whether inline visualizations require a specific MCP Server version, ThoughtSpot Cloud version, or SDK version.
+* The ThoughtSpot MCP Server must be configured and connected to your ThoughtSpot instance.
+* Inline visualization support requires ThoughtSpot Cloud jul.26.mt or later.
+// TODO: [WRITER] Add confirmed MCP Server version requirement here.
+
+== How inline visualizations work
+
+// TODO: [WRITER] Replace this placeholder description with the confirmed feature behavior from the engineering or product team.
+// The description below is inferred from the Jira issue (SCAL-303476) and is not confirmed.
+When an AI agent invokes a ThoughtSpot MCP tool that returns data, the MCP Server can now return the result as a rendered inline visualization in addition to (or instead of) a raw data payload. The visualization is non-interactive — it is rendered as a static image or structured data display within the agent response context, suitable for embedding in chat interfaces, AI copilots, and agent-driven dashboards.
+
+// TODO: [WRITER] Add a diagram or screenshot of inline visualization output once available from the design team.
+
+== Supported visualization types
+
+// TODO: [WRITER] Confirm which visualization types are supported for inline rendering in the initial release.
+// The list below is a placeholder inferred from the Jira description.
+* Bar charts
+* Line charts
+* Tables
+// TODO: [WRITER] Add or remove visualization types based on engineering confirmation.
+
+== Configure inline visualizations
+
+// TODO: [WRITER] Replace the placeholder configuration example with the confirmed MCP tool invocation and response schema.
+// The tool name, parameters, and response format below are illustrative only.
+
+[source,json]
+----
+// TODO: [WRITER] Replace with a confirmed MCP tool invocation example.
+// Tool name, parameters, and response shape must be confirmed by the MCP team.
+{
+ "tool": "thoughtspot_search_with_viz",
+ "parameters": {
+ "query": "total revenue by region",
+ "model_id": "",
+ "viz_type": "bar_chart",
+ "inline": true
+ }
+}
+----
+
+Expected response shape:
+
+[source,json]
+----
+// TODO: [WRITER] Replace with confirmed response schema from the MCP team.
+{
+ "text": "Total revenue by region for Q4 2025.",
+ "visualization": {
+ "type": "bar_chart",
+ "image_url": "data:image/png;base64,...",
+ "alt_text": "Bar chart showing total revenue by region"
+ }
+}
+----
+
+== Related resources
+
+// TODO: [WRITER] Update these links once the MCP Server page is confirmed.
+* xref:mcp-server.adoc[ThoughtSpot MCP Server]
+* xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]
diff --git a/modules/ROOT/pages/rest-api-csharp-sdk.adoc b/modules/ROOT/pages/rest-api-csharp-sdk.adoc
new file mode 100644
index 000000000..ee25251b4
--- /dev/null
+++ b/modules/ROOT/pages/rest-api-csharp-sdk.adoc
@@ -0,0 +1,337 @@
+= C# SDK for REST APIs
+:toc: true
+:toclevels: 3
+
+:page-title: REST API C# SDK
+:page-pageid: rest-api-sdk-csharp
+:page-description: Use the C# SDK to call ThoughtSpot REST API v2 endpoints from .NET applications.
+
+The link:https://github.com/thoughtspot/rest-api-sdk/tree/release/sdks/csharp[REST API C# SDK, window=_blank] provides a client library to interact with ThoughtSpot REST API v2 endpoints from `.NET` applications. The SDK targets `net8.0` and ships both synchronous and asynchronous variants of every API method.
+
+The SDK package is available on link:https://www.nuget.org/packages/ThoughtSpot.RestApi.Sdk[NuGet, window=_blank].
+
+== Before you begin
+
+Before you begin, check the following prerequisites:
+
+* Your environment targets .NET 8 (`net8.0`) or later.
+* You have access to a ThoughtSpot instance and the following information:
+** The URL of your ThoughtSpot instance
+** User credentials (username and password, or a secret key for trusted authentication)
+* You have user privileges and object permissions to view, edit, or create ThoughtSpot objects and resources.
+
+== Import the SDK
+
+Install the package:
+
+Using the .NET CLI::
+
+[source,bash]
+----
+dotnet add package ThoughtSpot.RestApi.Sdk --version 2.27.0
+----
+
+Using the NuGet Package Manager console::
+
+[source,bash]
+----
+Install-Package ThoughtSpot.RestApi.Sdk -Version 2.27.0
+----
+
+== API client configuration
+All SDK clients are configured with an `ApiClientConfiguration` record. Provide your ThoughtSpot instance URL and one authentication option, then build your client using `CreateAsync`.
+
+`CreateAsync` is the recommended entry point. It is required for server-sent event (SSE) streaming methods and for automatic token refresh when using `Username`+`Password`, `Username`+`SecretKey`, or `TokenProvider`.
+
+[source,csharp]
+----
+using ThoughtSpot.RestApi.Sdk;
+using ThoughtSpot.RestApi.Sdk.Api;
+using ThoughtSpot.RestApi.Sdk.Model;
+
+var config = new ApiClientConfiguration
+{
+ Host = "https://your-thoughtspot-instance.thoughtspot.cloud",
+ Username = "your-username",
+ Password = "your-password",
+};
+
+var api = await ThoughtSpotRestApi.CreateAsync(config);
+----
+
+=== Configuration options
+[width="100%", cols="2,2,4"]
+[options="header"]
+|====
+|Option|Default|Description
+|`Host`|—|Required. Base URL of your ThoughtSpot instance, for example, `\https://my-cluster.thoughtspot.cloud`.
+|`Username` / `Password`|`null`|Credentials for password-based authentication. The SDK fetches and refreshes a bearer token automatically.
+|`Username` / `SecretKey`|`null`|Credentials for trusted authentication. Use when Trusted authentication is enabled on your instance.
+|`TokenProvider`|`null`|An async callback (`Func>`) invoked before every request. You own caching and refresh logic inside this function.
+|`BearerToken`|`null`|[.version-badge.deprecated]#Deprecated# Static bearer token. Does not refresh. Requests fail with 401 after the token expires. Use `TokenProvider` or `CreateAsync` for automatic refresh instead.
+|`TokenValiditySeconds`|`300`|How long (in seconds) a fetched token is considered valid before the SDK refreshes it. The value is sent to the server and used client-side.
+|`ConnectTimeout`|60 seconds|TCP connection establishment timeout. Matches the Java SDK's `connectTimeoutMillis` default.
+|`ReadTimeout`|300 seconds|Time allowed to read a response after the connection is established. Matches the Java SDK's `readTimeoutMillis` default.
+|`WriteTimeout`|300 seconds|Time allowed to send a request body. Matches the Java SDK's `writeTimeoutMillis` default.
+|`IgnoreSslErrors`|`false`|Disables SSL certificate validation. Use only for development or test environments with self-signed certificates.
+|`EnableRetries`|`false`|Set to `true` to enable the built-in Polly retry pipeline.
+|`RetryPipeline`|`null`|A custom Polly `ResiliencePipeline`. Used only when `EnableRetries` is `true`. Falls back to `RetryConfiguration.Default` when `null`.
+|`DefaultHeaders`|Empty|Headers added to every outgoing request.
+|====
+
+== Authentication
+The SDK supports the following authentication modes. These modes use automatic token management and require `CreateAsync`.
+
+* xref:rest-api-csharp-sdk.adoc#username-and-password[Username and password]
+* xref:rest-api-csharp-sdk.adoc#username-and-secret-key[Username and secret key]
+* xref:rest-api-csharp-sdk.adoc#token-provider[Token provider]
+
+[NOTE]
+====
+The SDK also accepts a static BearerToken. However, a static token does not refresh and when it expires, all requests fail with HTTP 401. Use the `Username` and `Password`, `Username` and `SecretKey`, or `TokenProvider` modes instead.
+====
+
+[#username-and-password]
+=== Username and password
+The SDK calls the `fullAccessToken` API internally with the provided credentials to obtain a bearer token on startup. The token is cached and refreshed automatically 30 seconds before it expires. No token management is required in your application code.
+
+[source,csharp]
+----
+var config = new ApiClientConfiguration
+{
+ Host = "https://your-thoughtspot-instance.thoughtspot.cloud",
+ Username = "your-username",
+ Password = "your-password",
+};
+
+var api = await ThoughtSpotRestApi.CreateAsync(config);
+var me = await api.GetCurrentUserInfoAsync();
+Console.WriteLine($"Logged in as: {me.Name}");
+----
+
+[#username-and-secret-key]
+=== Username and secret key (trusted authentication)
+Use this mode when Trusted authentication is enabled on your ThoughtSpot instance. The SDK calls the `fullAccessToken` API internally with the provided username and xref:trusted-auth-secret-key.adoc[secret key] to obtain a bearer token on startup. The token is cached and refreshed automatically 30 seconds before it expires. No token management is required in your application code.
+
+[source,csharp]
+----
+var config = new ApiClientConfiguration
+{
+ Host = "https://your-thoughtspot-instance.thoughtspot.cloud",
+ Username = "your-username",
+ SecretKey = "your-secret-key",
+};
+
+var api = await ThoughtSpotRestApi.CreateAsync(config);
+----
+
+[#token-provider]
+=== Token provider
+Use this mode when you manage tokens externally, for example, through an identity provider or a secrets vault. The `TokenProvider` delegate is invoked before every request. Implement your own caching and refresh logic inside the delegate.
+
+[source,csharp]
+----
+var config = new ApiClientConfiguration
+{
+ Host = "https://your-thoughtspot-instance.thoughtspot.cloud",
+ TokenProvider = async cancellationToken =>
+ await myIdentityProvider.FetchBearerAsync(cancellationToken),
+};
+
+var api = await ThoughtSpotRestApi.CreateAsync(config);
+----
+
+== Per-tag API classes and the aggregate client
+The SDK exposes the ThoughtSpot REST API surface through two complementary access styles:
+
+* **28 per-tag API classes**: Each covers one functional area. Use a focused class when you only need a narrow surface (for example, `UsersApi`, `MetadataApi`, or `AIApi`).
+* **`ThoughtSpotRestApi`**: Aggregates all 28 API classes behind a single object. Use this when your application calls endpoints across multiple areas.
+
+Both styles are created with `CreateAsync` and take the same `ApiClientConfiguration`:
+
+[source,csharp]
+----
+// Using the aggregate client
+var api = await ThoughtSpotRestApi.CreateAsync(config);
+var users = await api.SearchUsersAsync(new SearchUsersRequest());
+
+// Using a focused per-tag class
+var usersApi = await UsersApi.CreateAsync(config);
+var users = await usersApi.SearchUsersAsync(new SearchUsersRequest());
+----
+
+== Synchronous and asynchronous usage
+Every method has both an asynchronous variant (`XxxAsync`) and a blocking synchronous variant (the same name without the `Async` suffix). Use the synchronous variant from code that cannot use `await`.
+
+[source,csharp]
+----
+// Async (recommended)
+var me = await api.GetCurrentUserInfoAsync();
+
+// Synchronous (blocking)
+var me = api.GetCurrentUserInfo();
+Console.WriteLine(me.Name);
+----
+
+== Access response status and headers
+Every method has a `WithHttpInfo` / `WithHttpInfoAsync` variant that returns an `ApiResponse` wrapping the HTTP status code, response headers, and deserialized data.
+
+[source,csharp]
+----
+var response = await api.GetCurrentUserInfoWithHttpInfoAsync();
+Console.WriteLine(response.StatusCode); // e.g. 200
+Console.WriteLine(response.Data.Name);
+----
+
+[#streaming-sse]
+== Streaming (SSE)
+Endpoints that return server-sent events (SSE) expose a `XxxStreamAsync` method returning `IAsyncEnumerable`. This enables real-time streaming of AI responses from Spotter endpoints. Streaming requires the API class to be built with `CreateAsync`.
+
+[source,csharp]
+----
+var aiApi = await AIApi.CreateAsync(config);
+
+await foreach (var chunk in aiApi.SendAgentConversationMessageStreamingStreamAsync(
+ conversationIdentifier: conversationId,
+ sendAgentConversationMessageStreamingRequest: new SendAgentConversationMessageStreamingRequest
+ {
+ Messages = new List { "What is the total revenue by region?" },
+ }))
+{
+ Console.Write(chunk);
+}
+----
+
+== File uploads
+Multipart endpoints, for example, dbt and Style Customization, accept a `FileParameter` built from a `Stream` with an optional filename and content type.
+
+[source,csharp]
+----
+var dbtApi = await DbtApi.CreateAsync(config);
+
+await using var stream = File.OpenRead("project.zip");
+await dbtApi.DbtConnectionAsync(
+ connectionName: "my-connection",
+ databaseName: "MY_DB",
+ importType: "ZIP_FILE",
+ fileContent: new FileParameter("project.zip", stream));
+----
+
+[NOTE]
+====
+The SDK automatically rewinds seekable upload streams before each retry attempt. If a stream is not seekable, the SDK aborts with a non-retryable error rather than sending incomplete data.
+====
+
+== File downloads
+Export endpoints return a `FileParameter` wrapping the response stream, filename, and content type.
+
+[source,csharp]
+----
+var reportsApi = await ReportsApi.CreateAsync(config);
+
+var file = await reportsApi.ExportLiveboardReportAsync(
+ new ExportLiveboardReportRequest
+ {
+ MetadataIdentifier = liveboardId,
+ FileFormat = "PDF",
+ });
+
+await using var output = File.Create("report.pdf");
+await file.Content.CopyToAsync(output);
+----
+
+== Error handling
+Failed calls throw `ThoughtSpot.RestApi.Sdk.Client.ApiException`. The exception exposes:
+
+* `ErrorCode`: the HTTP status code.
+* `Message`: a human-readable error message.
+* `ErrorContent`: the deserialized error response body.
+* `Headers`: the HTTP response headers.
+
+[source,csharp]
+----
+try
+{
+ await api.SearchUsersAsync(new SearchUsersRequest());
+}
+catch (ThoughtSpot.RestApi.Sdk.Client.ApiException ex)
+{
+ Console.WriteLine($"{ex.ErrorCode}: {ex.Message}");
+ Console.WriteLine(ex.ErrorContent);
+}
+----
+
+== Retries
+Retries are disabled by default. Set `EnableRetries = true` on `ApiClientConfiguration` to enable the built-in Polly pipeline, up to three attempts with exponential backoff (1 s / 2 s / 4 s) and up to 500 ms of random jitter, applied on network errors and `429`, `500`, `502`, and `503` responses.
+
+[source,csharp]
+----
+var config = new ApiClientConfiguration
+{
+ Host = "https://your-thoughtspot-instance.thoughtspot.cloud",
+ Username = "your-username",
+ Password = "your-password",
+ EnableRetries = true,
+};
+----
+
+To apply a custom pipeline to a single client instance, set `RetryPipeline`:
+
+[source,csharp]
+----
+var config = new ApiClientConfiguration
+{
+ Host = "https://your-thoughtspot-instance.thoughtspot.cloud",
+ Username = "your-username",
+ Password = "your-password",
+ EnableRetries = true,
+ RetryPipeline = new ResiliencePipelineBuilder()
+ .AddRetry(new RetryStrategyOptions { MaxRetryAttempts = 5 })
+ .Build(),
+};
+----
+
+To set a global fallback pipeline used by all instances that do not supply a `RetryPipeline`:
+
+[source,csharp]
+----
+RetryConfiguration.Default = new ResiliencePipelineBuilder()
+ .AddRetry(new RetryStrategyOptions { MaxRetryAttempts = 5 })
+ .Build();
+----
+
+== Runtime reconfiguration
+You can swap the host, credentials, or timeouts at runtime without restarting your application. Call `ApplyConfigurationAsync` on any API client with a new `ApiClientConfiguration`.
+
+The swap is atomic. In-flight requests complete against the old configuration before the underlying resources are disposed.
+
+[source,csharp]
+----
+var newConfig = config with
+{
+ Host = "https://new-cluster.thoughtspot.cloud",
+ Username = "new-username",
+ Password = "new-password",
+};
+
+await api.ApplyConfigurationAsync(newConfig);
+----
+
+== Supported versions
+
+[width="100%", cols="2,2"]
+[options="header"]
+|====
+|ThoughtSpot release|Recommended SDK version
+|ThoughtSpot Cloud 26.8.0.cl|v2.27.0 or later
+|====
+
+
+== Additional resources
+
+* link:https://www.nuget.org/packages/ThoughtSpot.RestApi.Sdk[ThoughtSpot.RestApi.Sdk on NuGet, window=_blank]
+* link:https://github.com/thoughtspot/rest-api-sdk/tree/release/sdks/csharp[SDK source on GitHub, window=_blank]
+* xref:authentication.adoc[REST API v2 authentication]
+* +++REST API v2 Playground+++
+* xref:rest-api-v2-reference.adoc[REST API v2 reference]
+* xref:rest-apiv2-changelog.adoc[REST API v2 changelog]
diff --git a/modules/ROOT/pages/rest-api-java-sdk.adoc b/modules/ROOT/pages/rest-api-java-sdk.adoc
index 92512748e..e4285cb47 100644
--- a/modules/ROOT/pages/rest-api-java-sdk.adoc
+++ b/modules/ROOT/pages/rest-api-java-sdk.adoc
@@ -281,6 +281,7 @@ Note the recommendation of Java SDK:
[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
diff --git a/modules/ROOT/pages/rest-api-python-sdk.adoc b/modules/ROOT/pages/rest-api-python-sdk.adoc
index b31f82a8a..a2567bc18 100644
--- a/modules/ROOT/pages/rest-api-python-sdk.adoc
+++ b/modules/ROOT/pages/rest-api-python-sdk.adoc
@@ -8,7 +8,7 @@
The ThoughtSpot Python SDK is an async-first, fully-typed client generated from the ThoughtSpot REST API v2.0 OpenAPI specification. It wraps every endpoint into a typed Python method and supports both asynchronous and synchronous invocation, transparent token refresh, server-sent event (SSE) streaming, file uploads and downloads, and typed exception handling.
-The Python SDK version 2.26.0 is available on link:https://pypi.org/project/thoughtspot-rest-api-sdk/[PyPI, window=_blank].
+The Python SDK is available on link:https://pypi.org/project/thoughtspot-rest-api-sdk/[PyPI, window=_blank].
== Prerequisites
Before you begin, ensure that:
@@ -366,13 +366,24 @@ This rebuilds the underlying API client. For continuous token refresh, you do no
need this. Set `access_token` to a callable; it is invoked
on every request.
+
+== Supported versions
+
+[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
+|====
+
== Documentation for API endpoints
The full list of available methods is on the `ThoughtSpotRestApi` class. For more information, see link:https://github.com/thoughtspot/rest-api-sdk/blob/release/sdks/python/thoughtspot_rest_api_sdk/api/thought_spot_rest_api.py[thoughtspot_rest_api_sdk/api/thought_spot_rest_api.py, window=_blank].
== Additional resources
-* xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]
+* xref:rest-apiv2-changelog.adoc[REST API v2 changelog]
* link:https://pypi.org/project/thoughtspot-rest-api-sdk/[thoughtspot-rest-api-sdk on PyPI, window=_blank]
* link:https://github.com/thoughtspot/rest-api-sdk/tree/release/sdks/python[Python SDK source on GitHub, window=_blank]
-* link:https://developers.thoughtspot.com/docs/rest-api-v2[REST API v2.0 Playground, window=_blank]
+* link:https://developers.thoughtspot.com/docs/rest-api-v2[REST API v2 Playground, window=_blank]
diff --git a/modules/ROOT/pages/rest-api-sdk-libraries.adoc b/modules/ROOT/pages/rest-api-sdk-libraries.adoc
index 06fdf52dd..5d228ef39 100644
--- a/modules/ROOT/pages/rest-api-sdk-libraries.adoc
+++ b/modules/ROOT/pages/rest-api-sdk-libraries.adoc
@@ -1,10 +1,10 @@
-= REST API v2.0 SDKs
+= SDK libraries
:toc: true
:toclevels: 1
-:page-title: REST API SDKs
-:page-pageid: rest-api-sdk
-:page-description: Use REST API SDKs to call APIs in a language-specific way.
+:page-title: SDK libraries
+:page-pageid: rest-api-sdk-libraries
+:page-description: ThoughtSpot provides SDK libraries that allow you to integrate ThoughtSpot REST APIs in your application.
ThoughtSpot provides native SDK libraries to help client applications call REST APIs in a specific language format.
@@ -13,9 +13,10 @@ The following SDKs provide client libraries to call APIs from your applications:
* xref:rest-api-sdk-typescript.adoc[TypeScript SDK]
* xref:rest-api-java-sdk.adoc[Java SDK]
* xref:rest-api-python-sdk.adoc[Python SDK]
+* xref:rest-api-sdk-csharp.adoc[C# SDK]
== Community SDKs
-You can use the following open-source, community-supported SDKs.
+The following community-maintained SDK libraries are available for ThoughtSpot REST API integration. These SDKs are not officially maintained by ThoughtSpot.
[IMPORTANT]
====
@@ -24,7 +25,6 @@ You can use the following open-source, community-supported SDKs.
* ThoughtSpot-supported SDKs may not be backward-compatible with these community-based SDKs.
====
-
[width="100%" cols="2,4"]
[options='header']
|====
@@ -34,7 +34,6 @@ You can use the following open-source, community-supported SDKs.
**Language**: Python +
|link:https://github.com/thoughtspot/thoughtspot_tml[thoughtspot_tml, window=_blank]| Package for working with ThoughtSpot Modeling Language (TML) files programmatically +
-
**Language**: Python +
|====
@@ -44,6 +43,5 @@ You can use the following open-source, community-supported SDKs.
For more information about REST APIs, use the following resources:
* For information about supported authentication types, see xref:authentication.adoc[REST API v2 authentication].
-* Browse through the +++REST API v2 Playground+++ before you start constructing your API requests. The playground offers an interactive portal with comprehensive information about the API endpoints, request and response workflows.
* For information about supported API endpoints, see xref:rest-api-v2-reference.adoc[REST API v2 reference].
-* For information about new and deprecated features and enhancements, see xref:rest-apiv2-changelog.adoc[REST API v2 Changelog].
+* For information about new and deprecated features and enhancements, see xref:rest-apiv2-changelog.adoc[REST API v2 Changelog].
\ No newline at end of file
diff --git a/modules/ROOT/pages/rest-api-sdk-typescript.adoc b/modules/ROOT/pages/rest-api-sdk-typescript.adoc
index 452dba9e6..12744fa42 100644
--- a/modules/ROOT/pages/rest-api-sdk-typescript.adoc
+++ b/modules/ROOT/pages/rest-api-sdk-typescript.adoc
@@ -203,6 +203,7 @@ Note the version recommendations for your ThoughtSpot instances:
[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
diff --git a/modules/ROOT/pages/rest-api-v2-reference.adoc b/modules/ROOT/pages/rest-api-v2-reference.adoc
index dfaf6a4ac..e9baec903 100644
--- a/modules/ROOT/pages/rest-api-v2-reference.adoc
+++ b/modules/ROOT/pages/rest-api-v2-reference.adoc
@@ -106,9 +106,19 @@ Permanently deletes a saved Spotter agent conversation and all its associated me
|ThoughtSpot Cloud: __26.7.0.cl or later__ +
ThoughtSpot Software: __Not available__ a| +++Try it out+++
+a|`POST /api/rest/2.0/ai/memory/import` +
+Imports Spotter training memory entries in bulk for backup, migration, or seeding purposes.
+|ThoughtSpot Cloud: __26.8.0.cl or later__ +
+ThoughtSpot Software: __Not available__ a| +++Try it out+++
+
+a|`POST /api/rest/2.0/ai/memory/export` +
+Exports Spotter training memory entries for audit, backup, or cross-environment migration.
+|ThoughtSpot Cloud: __26.8.0.cl or later__ +
+ThoughtSpot Software: __Not available__ a| +++Try it out+++
|=====
--
+
== Authentication
[div boxAuto]
@@ -178,7 +188,7 @@ a| +++ *Security settings*.
-. Click *Edit*.
-. In the *CSP visual embed hosts* text box, add the domain names. For valid domain name formats, See xref:security-settings.adoc#csp-cors-hosts[Domain name format for CSP and CORS configuration].
-. Click *Save changes*.
-
-
[NOTE]
====
Only users with a valid embed license can add Visual Embed hosts.
====
-*Through the REST API v2*
+In the UI::
-Send a `POST` request to `POST /api/rest/2.0/system/security-settings/configure` API endpoint. Add your application domain as a CSP visual embed host for your ThoughtSpot application instance by entering valid values for the parameter `visual_embed_hosts`.
+. On your ThoughtSpot application instance, go to the *Develop* page.
+. If your instance has Orgs, click the *All Orgs* tab.
+. Go to *Customizations* > *Security settings*.
+. Click *Edit*.
+. In the *CSP visual embed hosts* text box, add the domain names. For valid domain name formats, see xref:security-settings.adoc#csp-cors-hosts[Domain name format for CSP and CORS configuration].
+. Click *Save changes*.
+Through the REST API v2::
+Send a request to the `POST /api/rest/2.0/system/security-settings/configure` API endpoint. Add your application domain as a CSP visual embed host for your ThoughtSpot application instance by entering valid values for the parameter `visual_embed_hosts`.
++
[source,cURL]
----
curl -X POST 'https://{ThoughtSpot-Host}/api/rest/2.0/system/security-settings/configure' \
@@ -141,18 +140,19 @@ curl -X POST 'https://{ThoughtSpot-Host}/api/rest/2.0/system/security-settings/c
==== Add URLs to CSP connect-src allowlist
If you plan to use a custom action or webhook to send data to an external endpoint or application, you must add the domains of the target endpoints or applications to the `CSP connect-src` allowlist.
-. On your ThoughtSpot application instance, go to *Develop* page.
+In the UI::
+. On your ThoughtSpot application instance, go to the *Develop* page.
. If your instance has Orgs, click the *All Orgs* tab.
. Go to *Customizations* > *Security settings*.
. Click *Edit*.
-. In the *CSP connect-src domains* text box, add the domain names. For valid domain name formats, See xref:security-settings.adoc#csp-cors-hosts[Domain name format for CSP and CORS configuration].
+. In the *CSP connect-src domains* text box, add the domain names. For valid domain name formats, see xref:security-settings.adoc#csp-cors-hosts[Domain name format for CSP and CORS configuration].
. Click *Save changes*.
-*Through the REST API v2*
-
-Send a `POST` request to `POST /api/rest/2.0/system/security-settings/configure` API endpoint. Add domains of the target endpoints or applications to the `connect_src_urls` parameter for your ThoughtSpot application instance.
+Through the REST API v2::
+Send a request to the `POST /api/rest/2.0/system/security-settings/configure` API endpoint. Add domains of the target endpoints or applications to the `connect_src_urls` parameter for your ThoughtSpot application instance.
++
[source,cURL]
----
curl -X POST \
@@ -173,11 +173,11 @@ curl -X POST \
[#csp-trusted-domain]
==== Add other trusted domains
-
To import images, fonts, and stylesheets from external sites, or load the content from an external site using an iFrame element, you must add the source URLs as trusted domains in the CSP allowlist.
For example, in the Liveboard Note tiles, if you want to insert an image from an external site or embed content from an external site in an iFrame, you must add domain URLs of these sites to the CSP allowList. Similarly, to import fonts and custom styles from an external source, you must add the source URL as a trusted domain in ThoughtSpot.
-. On your ThoughtSpot application instance, go to *Develop* page.
+In the UI::
+. On your ThoughtSpot application instance, go to the *Develop* page.
. If your instance has Orgs, click the *All Orgs* tab.
. Go to *Customizations* > *Security settings* and configure the settings: +
@@ -195,14 +195,16 @@ Add the domains from which you want host scripts. For more information, see xref
Add the iframe source URL domains.
////
+Through the REST API v2::
+Send a request to the `POST /api/rest/2.0/system/security-settings/configure` API endpoint. Add source URLs of sites, where from you can import images, fonts, and stylesheets, as trusted domains to the `img_src_urls`, `font_src_urls`, `style_src_urls`, `script_src_urls` parameters.
-*Through the REST API v2*
-
-Send a `POST` request to `POST /api/rest/2.0/system/security-settings/configure` API endpoint. Add source URLs of sites, where from you can import images, fonts, and stylesheets, as trusted domains to the `img_src_urls`, `font_src_urls`, `style_src_urls`, `script_src_urls` parameters.
-
++
[NOTE]
+====
To be able to add allowed urls for custom JavaScript through `script_src_urls`, `enabled` should be set to `true` for script-src customization.
+====
++
[source,cURL]
----
curl -X POST \
@@ -232,11 +234,11 @@ curl -X POST \
}'
----
-
==== Add permitted iFrame domains
-Features such as link:https://docs.thoughtspot.com/software/latest/liveboard-notes[Liveboard Note tiles, window=_blank] and link:https://docs.thoughtspot.com/cloud/latest/chart-custom[custom charts, window=_blank] allow iFrame content. If you are planning to embed content from an external site, make sure the domain URLs of these sites are added to the iFrame domain allowlist:
+Features such as link:https://docs.thoughtspot.com/software/latest/liveboard-notes[Liveboard Note tiles, window=_blank] and link:https://docs.thoughtspot.com/cloud/latest/chart-custom[custom charts, window=_blank] allow iFrame content. If you are planning to embed content from an external site, make sure the domain URLs of these sites are added to the iFrame domain allowlist.
-. On your ThoughtSpot application instance, go to *Develop* page.
+In the UI::
+. On your ThoughtSpot application instance, go to the *Develop* page.
. If your instance has Orgs, click the *All Orgs* tab.
. Go to *Customizations* > *Security settings*.
. Click *Edit*.
@@ -244,10 +246,10 @@ Features such as link:https://docs.thoughtspot.com/software/latest/liveboard-not
. Click *Save changes*.
-*Through the REST API v2*
-
-Send a `POST` request to `POST /api/rest/2.0/system/security-settings/configure` API endpoint. Add domain URLs of external sites using iFrame content are added to the `iframe_src_urls` parameter for your ThoughtSpot application instance.
+Through the REST API v2::
+Send a request to the `POST /api/rest/2.0/system/security-settings/configure` API endpoint. Add domain URLs of external sites using iFrame content to the `iframe_src_urls` parameter for your ThoughtSpot application instance.
++
[source,cURL]
----
curl -X POST \
@@ -267,31 +269,32 @@ curl -X POST \
[#cors-hosts]
==== Enable CORS
-
To allow your embedding application to call ThoughtSpot, access its resources, and render embedded content, add your host application domain URL as a trusted host for CORS.
The CORS configuration on your instance controls which domains can access and modify your application content. To allow your application to call ThoughtSpot or its REST API endpoints, and request resources, you must add your application domain to the CORS allowlist. For example, if your website is hosted on the `example.com` domain and the embedded ThoughtSpot content is hosted on the `example.thoughtspot.com`, you must add the `example.com` domain to the CORS allowlist for cross-domain communication. You can also add `\http://localhost:8080` to the CORS allowlist to test your deployments locally. However, we recommend that you disable `localhost` access in production environments.
If you enable CORS for your application domain, ThoughtSpot adds the `Access-Control-Allow-Origin` header in its API responses when your host application sends a request to ThoughtSpot.
-To add domain names to the CORS allowlist, follow these steps:
+In the UI::
+To add domain names to the CORS allowlist, complete these steps:
. On your ThoughtSpot instance, navigate to the *Develop* page.
-. If your instance has Orgs, you can configure CORS allowlists for all Orgs globally at the cluster-level or per Org. +
+. If your instance has Orgs, you can configure CORS allowlists for all Orgs globally at the cluster level or per Org. +
* For cluster-wide configuration, click the *All Orgs* tab.
* To configure settings at the Primary Org level, click the *Primary Org* tab.
-* To configure CORS settings at the Org-level, switch the Org context via Org switcher in the top navigation bar.
+* To configure CORS settings at the Org level, switch the Org context via the Org switcher in the top navigation bar.
-. On *Develop* page, go to *Customizations* > *Security settings*.
+. On the *Develop* page, go to *Customizations* > *Security settings*.
. Click *Edit*.
-. In the *CORS whitelisted domains* text box, add the domain names. For valid domain name formats, See xref:security-settings.adoc#csp-cors-hosts[Domain name format for CSP and CORS configuration].
+. In the *CORS whitelisted domains* text box, add the domain names. For valid domain name formats, see xref:security-settings.adoc#csp-cors-hosts[Domain name format for CSP and CORS configuration].
. Click *Save changes*.
-*Through the REST API v2*
+Through the REST API v2::
-Send a `POST` request to `POST /api/rest/2.0/system/security-settings/configure` API endpoint. Add CORS allowlist for cross-domain communication to the parameter `cors_whitelisted_urls` for the cluster or for the Org.
+Send a request to the `POST /api/rest/2.0/system/security-settings/configure` API endpoint. Add CORS allowlist for cross-domain communication to the parameter `cors_whitelisted_urls` for the cluster or for the Org.
++
[source,cURL]
----
curl -X POST \
@@ -315,6 +318,77 @@ 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.
+
+To allow these origins to embed ThoughtSpot content, add the custom scheme URL to the *CSP visual embed hosts* and *CORS whitelisted domains* allowlists.
+
+[IMPORTANT]
+====
+Before allowlisting custom schemes, note that allowlisting a shared app scheme such as `capacitor://localhost` or `ionic://localhost` does not uniquely identify your application. Any application on the same device that uses the same framework presents the same origin to the browser. This means:
+
+* Allowlisting `capacitor://localhost` grants embedding access to *all* Capacitor-based apps on that device, not just yours.
+* Treat custom-scheme allowlisting as *enabling functionality*, not as an access control boundary.
+* Security for these embeds must be enforced through *authentication* — use xref:trusted-auth-sdk.adoc[`AuthType.TrustedAuthTokenCookieless`] (cookieless trusted auth) to ensure that only authenticated users in your application can access ThoughtSpot content.
+* Do *not* rely on origin allowlisting alone as a security mechanism for custom-scheme embeds.
+====
+
+===== Add a custom scheme to CSP visual embed hosts
+
+. On your ThoughtSpot application instance, go to *Develop* > *Customizations* > *Security settings*.
+. Click *Edit*.
+. In the *CSP visual embed hosts* text box, add your custom scheme URL. For example:
++
+----
+capacitor://localhost
+----
+. Click *Save changes*.
+
+===== Add a custom scheme to CORS whitelisted domains
+. On your ThoughtSpot application instance, go to *Develop* > *Customizations* > *Security settings*.
+. Click *Edit*.
+. In the *CORS whitelisted domains* text box, add your custom scheme URL. For example: +
+`capacitor://localhost`
+. Click *Save changes*.
+
+===== Add a custom scheme via REST API
+Send a request to the `POST /api/rest/2.0/system/security-settings/configure` endpoint and add the custom scheme URL to the `visual_embed_hosts` and `cors_whitelisted_urls` arrays:
+
+[source,cURL]
+----
+curl -X POST 'https://{ThoughtSpot-Host}/api/rest/2.0/system/security-settings/configure' \
+ -H 'Authorization: Bearer {token}' \
+ -H 'Content-Type: application/json' \
+ --data-raw '{
+ "org_preferences": [
+ {
+ "visual_embed_hosts": [
+ "capacitor://localhost"
+ ],
+ "cors_whitelisted_urls": [
+ "capacitor://localhost"
+ ]
+ }
+ ]
+}'
+----
+
+After allowlisting the custom scheme, initialize the Visual Embed SDK using `AuthType.TrustedAuthTokenCookieless` in your Capacitor or Ionic application:
+
+[source,JavaScript]
+----
+import { init, AuthType } from '@thoughtspot/visual-embed-sdk';
+
+init({
+ thoughtSpotHost: 'https://your-thoughtspot-instance.thoughtspot.cloud',
+ authType: AuthType.TrustedAuthTokenCookieless,
+ getAuthToken: () => fetch('/api/get-token')
+ .then(r => r.json())
+ .then(d => d.token),
+ });
+----
+
[#csp-cors-hosts]
==== Domain name format for CSP and CORS configuration
@@ -324,8 +398,8 @@ curl -X POST \
* You can add multiple domains to the CORS and CSP Visual Embed allowlists on the **Develop** **Customizations** > **Security Settings** page. Ensure that the CORS and CSP allowlists do not exceed 4096 characters.
* *Protocol in the domain URL*:
-** CSP hosts — The UI allows adding a domain URL with or without the protocol (`http/https`). However, to avoid long URLs in the CSP header, you can exclude the protocol in the domain URL strings.
-** CORS hosts — The UI allows adding a domain URL with the protocol (`http/https`). If the domain URLs are using `https`, you can exclude the protocol in domain URL strings, because ThoughtSpot assigns `https` to the URLs by default.
+** CSP hosts - The UI allows adding a domain URL with or without the protocol (`http/https`). However, to avoid long URLs in the CSP header, you can exclude the protocol in the domain URL strings.
+** CORS hosts — The UI allows adding a domain URL with the protocol (`http/https`). If the domain URLs are using `https`, you can exclude the protocol in domain URL strings, because ThoughtSpot assigns `https` to the URLs by default.
** For localhost and non-HTTPS URLs — For non-HTTPs domains or localhost such as `localhost:3000`, if you add the domain without the protocol, the `https` protocol will be assigned to the URL by default. Due to this, the localhost domain with `http` (`\http://localhost:3000`) might result in a CSP or CORS error. Therefore, include the `http` protocol in the domain name strings for non-HTTPS domains and localhost.
* **Port**: If your domain URL has a non-standard port such as 8080, specify the port number in the domain name string.
* **Websocket endpoints**: +
@@ -424,10 +498,12 @@ If you have embedded ThoughtSpot content in your app, you may want your users to
*Through the REST API v2*
-Send a `POST` request to `POST /api/rest/2.0/system/security-settings/configure` API endpoint. Set `block_full_app_access` to `true` to restrict user access to non-embedded application pages from the embedding application context. Enter values for `groups_identifiers_with_access` to selectively grant access to specific user groups.
+Send a request to the `POST /api/rest/2.0/system/security-settings/configure` API endpoint. Set `block_full_app_access` to `true` to restrict user access to non-embedded application pages from the embedding application context. Enter values for `groups_identifiers_with_access` to selectively grant access to specific user groups.
[NOTE]
+====
To be able to gives access through `groups_identifiers_with_access`, the selective user access feature must be turned on in the *Admin settings*.
+====
[source,cURL]
----
@@ -460,7 +536,7 @@ Many web browsers do not allow third-party cookies. If you are using authenticat
However, if your implementation uses cookie-based authentication or xref:embed-authentication.adoc#none[AuthType.None], ensure that you enable partitioned cookies:
-. On your ThoughtSpot application instance, go to *Develop* page.
+. On your ThoughtSpot application instance, go to the *Develop* page.
. If your instance has Orgs, click the *All Orgs* tab.
. Go to *Customizations* > *Security settings*.
. Click *Edit*.
@@ -476,7 +552,7 @@ Safari blocks all third-party cookies and does not support partitioned cookies.
*Through the REST API v2*
-Send a `POST` request to `POST /api/rest/2.0/system/security-settings/configure` API endpoint. Set `enable_partitioned_cookies` to `true` to ensure a cookie is set with the partitioned attribute for applications using cookie-based authentication .
+Send a request to the `POST /api/rest/2.0/system/security-settings/configure` API endpoint. Set `enable_partitioned_cookies` to `true` to ensure a cookie is set with the partitioned attribute for applications using cookie-based authentication.
[source,cURL]
----
@@ -498,12 +574,12 @@ To find the trusted authentication configuration for the specified auth type at
For more information on the trusted authentication configuration through APIs, see xref:authentication.adoc[Configuring authentication settings].
-See xref:trusted-authentication.adoc[Trusted authentication] and xref:_secret_key_management[Secret key management] for other related information.
+See xref:trusted-authentication.adoc[Trusted authentication] and xref:trusted-auth-secret-key.adoc[Secret key management] for other related information.
== Retrieve security settings
-You can retrieve the security settings for your ThoughtSpot instance by sending a `POST` request to `POST /api/rest/2.0/system/security-settings/search` API endpoint.
+You can retrieve the security settings for your ThoughtSpot instance by sending a request to the `POST /api/rest/2.0/system/security-settings/search` API endpoint.
You can define the `scope` to get the cluster-level settings (`scope` as `CLUSTER`), or the Org-level settings for the current Org (`scope` as `ORG`). If the `scope` is not specified, the API returns both cluster and Org settings based on user privileges.
[source,cURL]
diff --git a/modules/ROOT/pages/spotter-ai-memory-api.adoc b/modules/ROOT/pages/spotter-ai-memory-api.adoc
new file mode 100644
index 000000000..ce4546424
--- /dev/null
+++ b/modules/ROOT/pages/spotter-ai-memory-api.adoc
@@ -0,0 +1,691 @@
+= Spotter memory migration API
+:toc: true
+:toclevels: 2
+
+:page-title: Spotter memory migration API
+:page-pageid: spotter-memory-migration
+: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.
+* To replicate a gold-standard Spotter configuration across multiple Orgs at scale.
+* To back up and restore Spotter memory as part of your deployment pipeline.
+
+[NOTE]
+====
+The API endpoints support importing and exporting memory defined at the model level. Exporting or importing user memory and analyst memory are currently not supported.
+====
+
+== Memory migration workflow
+Spotter accumulates memory, which includes rules (business logic) and recipes (query patterns), as users interact with data models. To migrate Spotter memory from one data model to another, or from a source environment to a target environment:
+
+. <> +
+Call `POST /api/rest/2.0/ai/memory/export` with the GUIDs of the data models to migrate.
+. <> +
+Save and modify the exported file as needed.
+. <> +
+Call `POST /api/rest/2.0/ai/memory/import` to import Spotter memory content into ThoughtSpot. You can validate the import operation using the dry run operation and review `import_summaries` and `failures` before proceeding.
+
+=== Required permissions
+To use Spotter memory migration APIs, the user requires the following privileges:
+
+* *Can manage Spotter* and at least view access to the data model.
+* *Can use Spotter* and edit access to the data model, or `SPOTTER_COACHING_PRIVILEGE` to import memory entries.
+
+Users with administration access can also export and import Spotter memory.
+
+[#export-memory]
+== Exporting Spotter memory
+The `/api/rest/2.0/ai/memory/export` API endpoint lets you export Spotter memory records for the specified data models as a single YAML payload. You can review the exported data, modify its contents, and re-import it into a ThoughtSpot Org or another environment. While the exported payload is human-readable, we do not recommend modifying its structure before re-importing it, as doing so may corrupt or invalidate the memory.
+
+=== Request parameters
+[cols="2,4", options="header"]
+|===
+|Parameter | Description
+| `sources`
+a|__Array of strings__. A list of data models from which you want to export.
+Specify the following attributes:
+
+* `type`. __String__. The source object type. Default value is `DATA_MODEL`. This is the default source type for Spotter memory, which includes the rules, recipes, and always-apply rules attached directly to a data model.
+* `identifiers`. __Array of strings__. GUIDs or object IDs of the data models.
+||
+|===
+
+=== Example request
+
+[source,cURL]
+----
+curl -X POST \
+ --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/memory/export' \
+ -H 'Accept: application/json' \
+ -H 'Content-Type: application/json' \
+ -H 'Authorization: Bearer {AUTH_TOKEN}' \
+ --data-raw '{
+ "sources": [
+ {
+ "type": "DATA_MODEL",
+ "identifiers": [
+ "cd252e5c-b552-49a8-821d-3eadaa049cca"
+ ]
+ }
+ ]
+}'
+----
+
+=== Example response
+The API returns a response object with the following details:
+
+* `content` +
+The serialized memory payload in YAML format. The exported file includes an array of memories, including rules and recipes added to Spotter memory, and data model GUID and object ID if present.
+* `type` +
+Indicates if the memory type is `RULE` or `RECIPE`. If the type is `RULE`, the response shows the rule definition. If the type is `RECIPE`, the contents of the recipe such as task, steps, TML tokens are included in the response.
+* `datamodel_sources` +
+GUID and object ID of the data model object.
+
+You can edit it locally and import it into your environment using the import memory API endpoint.
+
+[source,JSON]
+----
+{
+ "content":{
+ "memories":[
+ {
+ "type":"RULE",
+ "content":{
+ "rule_definition":"Revenue is defined as Sales Monthly."
+ },
+ "datamodel_sources":[
+ {
+ "guid":"cd252e5c-b552-49a8-821d-3eadaa049cca",
+ "obj_id":"SampleRetail-Apparel-cd252e5c"
+ }
+ ],
+ "tags":[
+
+ ]
+ },
+ {
+ "type":"RULE",
+ "content":{
+ "rule_definition":"Hot products: top 20 products by sales."
+ },
+ "datamodel_sources":[
+ {
+ "guid":"cd252e5c-b552-49a8-821d-3eadaa049cca",
+ "obj_id":"SampleRetail-Apparel-cd252e5c"
+ }
+ ],
+ "tags":[
+ "GLOBAL"
+ ]
+ },
+ {
+ "type":"RULE",
+ "content":{
+ "rule_definition":"Sales operations are organized into three geographic regions: east, midwest, and west."
+ },
+ "datamodel_sources":[
+ {
+ "guid":"cd252e5c-b552-49a8-821d-3eadaa049cca",
+ "obj_id":"SampleRetail-Apparel-cd252e5c"
+ }
+ ],
+ "tags":[
+ "GLOBAL"
+ ]
+ },
+ {
+ "type":"RECIPE",
+ "content":{
+ "user_query":"Weekly sales for June",
+ "recipe":{
+ "task":"Show total sales by week for the month of June",
+ "steps":[
+ {
+ "instruction":"Query sales by weekly date filtered to June month",
+ "analytical_mappings":{
+ "tml_tokens":[
+ "[sales]",
+ "[date].weekly",
+ "[date] = 'june'"
+ ],
+ "formulas":[
+
+ ]
+ }
+ }
+ ]
+ }
+ },
+ "datamodel_sources":[
+ {
+ "guid":"cd252e5c-b552-49a8-821d-3eadaa049cca",
+ "obj_id":"SampleRetail-Apparel-cd252e5c"
+ }
+ ],
+ "tags":[
+
+ ]
+ },
+ {
+ "type":"RECIPE",
+ "content":{
+ "user_query":"What is the total sales by date?",
+ "recipe":{
+ "brief_summary":"Visualizes total sales revenue over time on a daily basis.",
+ "nl_query":"What is the total sales by date?",
+ "lossy_tml_tokens":"[date] [sales]",
+ "lossy_formulas":[
+
+ ]
+ }
+ },
+ "datamodel_sources":[
+ {
+ "guid":"cd252e5c-b552-49a8-821d-3eadaa049cca",
+ "obj_id":"SampleRetail-Apparel-cd252e5c"
+ }
+ ],
+ "tags":[
+
+ ]
+ },
+ {
+ "type":"ALWAYS_APPLY_RULES",
+ "content":{
+ "rules":[
+ "When asking for 'top' results without specifying a number, default to top 20",
+ "Use sales column as primary metric; if sales data unavailable, fall back to quantity purchased column"
+ ]
+ },
+ "datamodel_sources":[
+ {
+ "guid":"cd252e5c-b552-49a8-821d-3eadaa049cca",
+ "obj_id":"SampleRetail-Apparel-cd252e5c"
+ }
+ ],
+ "tags":[
+
+ ]
+ }
+ ]
+ }
+}
+----
+
+[#update-memory-file]
+== Updating the memory file content
+The export memory API endpoint returns a YAML payload with a single top-level `memories` key holding a list of memory items. It includes the following object properties:
+
+* `type` +
+A typed `content` block, indicating `RULE` or `RECIPE`.
+* `datamodel_sources` list +
+GUID and object ID of the data models.
+* `tags` __Optional__.
+
+You can modify this file, add target data models, and submit it back through the import memory API endpoint.
+
+[IMPORTANT]
+====
+When editing a memory record, do not manually add new entries, especially under ALWAYS_APPLY_RULES. You can modify the values or remove the existing entries. If you must add new entries, use the UI workflow to ensure the memory entries are created in the correct format.
+====
+
+[source,yaml]
+----
+memories:
+- type: RULE
+ content:
+ rule_definition: "Revenue is defined as Sales Monthly."
+ datamodel_sources:
+ - guid: 62f3e9b5-4fcc-4352-b8ad-fdddc2287506
+ obj_id: RetailSales-3bc18302
+ tags: []
+
+- type: RULE
+ content:
+ rule_definition: "Hot products: top 20 products by sales."
+ datamodel_sources:
+ - guid: 62f3e9b5-4fcc-4352-b8ad-fdddc2287506
+ obj_id: RetailSales-3bc18302
+ tags:
+ - GLOBAL
+
+- type: RULE
+ content:
+ rule_definition: "Sales operations are organized into three geographic regions: east, midwest, and west."
+ datamodel_sources:
+ - guid: 62f3e9b5-4fcc-4352-b8ad-fdddc2287506
+ obj_id: RetailSales-3bc18302
+ tags:
+ - GLOBAL
+
+- type: RECIPE
+ content:
+ user_query: "Weekly sales for June"
+ recipe:
+ task: "Show total sales by week for the month of June"
+ steps:
+ - instruction: "Query sales by weekly date filtered to June month"
+ analytical_mappings:
+ tml_tokens:
+ - "[sales]"
+ - "[date].weekly"
+ - "[date] = 'june'"
+ formulas: []
+ datamodel_sources:
+ - guid: 62f3e9b5-4fcc-4352-b8ad-fdddc2287506
+ obj_id: RetailSales-3bc18302
+ tags: []
+
+- type: RECIPE
+ content:
+ user_query: "What is the total sales by date?"
+ recipe:
+ brief_summary: "Visualizes total sales revenue over time on a daily basis."
+ nl_query: "What is the total sales by date?"
+ lossy_tml_tokens: "[date] [sales]"
+ lossy_formulas: []
+ datamodel_sources:
+ - guid: 62f3e9b5-4fcc-4352-b8ad-fdddc2287506
+ obj_id: RetailSales-3bc18302
+ tags: []
+
+- type: ALWAYS_APPLY_RULES
+ content:
+ rules:
+ - "When asking for 'top' results without specifying a number, default to top 20"
+ - "Use sales column as primary metric; if sales data unavailable, fall back to quantity purchased column"
+ datamodel_sources:
+ - guid: 62f3e9b5-4fcc-4352-b8ad-fdddc2287506
+ obj_id: RetailSales-3bc18302
+ tags: []
+----
+
+A file can contain multiple `RULE` and multiple `RECIPE` items for a data model, but at most one `ALWAYS_APPLY_RULES` item per data model.
+
+=== Memory item fields
+[cols="2,4", options="header"]
+|===
+| Field | Description
+| `type` | Type can be `RULE`, `RECIPE`, or `ALWAYS_APPLY_RULES`. +
+
+* `RULE`. A single semantic rule. The content for this type must include `rule_definition` and the data model IDs.
+* `RECIPE`. A serialized string that includes responses to the natural-language query.
+* `ALWAYS_APPLY_RULES`. Mandatory rules that must always apply when generating queries for the data model. The content must include a `rules` list.
+| `content` | Type-specific content block.
+| `datamodel_sources` a| The data models the memory attaches to. Each item must list at least one source. Each entry identifies a data model via:
+
+* `guid`: the data model GUID.
+* `obj_id`: A stable object ID, resolved to a GUID server-side.
+
+If both are supplied, `obj_id` takes precedence and `guid` is ignored entirely; `guid` takes effect only when `obj_id` is absent. Exported files populate `guid` and, if present, `obj_id` as well.
+
+[IMPORTANT]
+====
+When `obj_id` is present, the accompanying `guid` is not used as a fallback. If an `obj_id` does not exist in the target environment, that item fails with `UNRESOLVED_SOURCE`. Remove or replace the stale `obj_id` values before importing across environments.
+====
+
+| `tags` |Free-form labels.
+||
+|===
+
+[#memory-file-limits]
+=== Limits
+Note the following limits for the import file and its content:
+
+[cols="2,1", options="header"]
+|===
+| Limit | Default
+| Uploaded file size | 10 MiB
+| Total memory items | 10,000
+| `rule_definition` length | 1,000 characters
+| `user_query` length | 1,000 characters
+| `recipe` length | 2,000 characters
+| `rules` combined length (`ALWAYS_APPLY_RULES`) | 2,000 characters +
+The `rules` limit in `ALWAYS_APPLY_RULES` applies to the combined length across all entries in the list, not per entry.
+| Tags per item | 10
+| Characters per tag | 50
+||
+|===
+
+[#structure-rules]
+=== Structural rules
+* The document must be a mapping with a `memories` key whose value is a list.
+* Unknown keys at the top level, within an item, or under `content` are rejected.
+* Each item's `type` must be one of the three supported values, and `content` must match that type's shape.
+* Null, empty-string, or incorrect type values in a required field are treated as missing.
+* Non-string or empty `tags` entries are dropped; certain tags reserved for internal use are stripped automatically before the item is stored.
+
+[#cross-item-rules]
+=== Cross-item rules
+A data model referenced by more than one `ALWAYS_APPLY_RULES` item is rejected. Combine them into a single item's `rules` list.
+
+[#import-memory]
+== Importing Spotter memory
+The `/api/rest/2.0/ai/memory/import` API endpoint imports Spotter memory content from a YAML payload into a target data model in your ThoughtSpot environment. Use this API endpoint to migrate Spotter memory with rules and recipes when seeding a new data model, or moving content across Orgs or between different environments.
+
+[IMPORTANT]
+====
+* The import operation *replaces* the existing memory of the target data models with the YAML content. The import operation uses a targeted replacement model, not an append.
+//To incrementally sync changes, export the relevant memory filtered by time window using the export memory API endpoint, merge with your existing file manually, and upload the merged result.
+* The import replaces memory entries only for the data models referenced in the uploaded file.
+* Since import replaces the existing memory entries, ThoughtSpot strongly recommends using the `dry_run` mode to validate before committing the content to the data model.
+* The API operation does not include semantic or column-level validation, so you must ensure that the column names are valid in the target environment.
+* If any part of the import fails, all changes are rolled back.
+====
+
+=== Request parameters
+
+Pass the following parameters in the API request body.
+
+[cols="2,4", options="header"]
+|===
+| Parameter | Description
+| `content`
+|__String__. The full contents of the Spotter memory payload YAML file passed as a string. The content structure is the same as the payload received from the export memory API endpoint. The memory payload will be imported to the data models specified in the `datamodel_sources` property of the content string. For more information about the contents and structure of the import file, see xref:spotter-ai-memory-api.adoc#update-memory-file[Updating the memory file content].
+
+| `dry_run`
+a|__Boolean__. Controls whether the import runs as a preview or executes for real. +
+
+* When set to `true`, the API validates the memory payload and returns preview counts without writing anything to the target data models. ThoughtSpot recommends running a dry run first to inspect validation errors before committing. +
+* When set to `false`, the API executes the import. The import replaces the existing global memories on the data models referenced in the payload with the entries supplied in the payload. If the import fails, ThoughtSpot rolls back the target to its pre-import state. +
+||
+|===
+
+=== Dry run operation
+The import operation deletes and replaces the existing global memories on the referenced data models. ThoughtSpot strongly recommends using a `dry_run` to validate the payload and preview the results.
+
+* If the API returns validation errors, verify the `validation_failures` and `diagnostics` fields in the API response and fix errors if any.
+* If the API returns a clean preview without any validation errors, call the API again with `dry_run` set as `false`.
+
+=== Example request
+
+[source,cURL]
+----
+curl -X POST \
+ --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/memory/export' \
+ -H 'Accept: application/json' \
+ -H 'Content-Type: application/json' \
+ -H 'Authorization: Bearer {AUTH_TOKEN}' \
+ --data-raw '{
+ "content": "{ \"content\": \"memories:\\n- type: RULE\\n content:\\n rule_definition: Revenue is defined as Sales Monthly.\\n datamodel_sources:\\n - guid: 62f3e9b5-4fcc-4352-b8ad-fdddc2287506\\n obj_id: RetailSales-3bc18302\\n tags: []\\n- type: RULE\\n content:\\n rule_definition: \\\"Hot products: top 20 products by sales.\\\"\\n datamodel_sources:\\n - guid: 62f3e9b5-4fcc-4352-b8ad-fdddc2287506\\n obj_id: RetailSales-3bc18302\\n tags: []\\n- type: RULE\\n content:\\n rule_definition: \\\"Sales operations are organized into three geographic regions: east, midwest, and west.\\\"\\n datamodel_sources:\\n - guid: 62f3e9b5-4fcc-4352-b8ad-fdddc2287506\\n obj_id: RetailSales-3bc18302\\n tags:\\n - GLOBAL\\n- type: RECIPE\\n content:\\n user_query: Weekly sales for June\\n recipe: \\\"{\\\\\\\"task\\\\\\\": \\\\\\\"Show total sales by week for the month of June\\\\\\\", \\\\\\\"steps\\\\\\\": [{\\\\\\\"instruction\\\\\\\": \\\\\\\"Query sales by weekly date filtered to June month\\\\\\\", \\\\\\\"analytical_mappings\\\\\\\": {\\\\\\\"tml_tokens\\\\\\\": [\\\\\\\"[sales]\\\\\\\", \\\\\\\"[date].weekly\\\\\\\", \\\\\\\"[date] = '\''june'\''\\\\\\\"], \\\\\\\"formulas\\\\\\\": []}}]}\\\"\\n datamodel_sources:\\n - guid: 62f3e9b5-4fcc-4352-b8ad-fdddc2287506\\n obj_id: RetailSales-3bc18302\\n tags: []\\n- type: RECIPE\\n content:\\n user_query: Compare this quarter'\''s sales with previous quarter by region\\n recipe: \\\"{\\\\\\\"task\\\\\\\": \\\\\\\"Compare total sales by region for this quarter versus previous quarter\\\\\\\", \\\\\\\"steps\\\\\\\": [{\\\\\\\"instruction\\\\\\\": \\\\\\\"Query total sales by region for this quarter compared to previous quarter\\\\\\\", \\\\\\\"analytical_mappings\\\\\\\": {\\\\\\\"tml_tokens\\\\\\\": [\\\\\\\"sales\\\\\\\", \\\\\\\"date = '\''this quarter'\''\\\\\\\", \\\\\\\"date = '\''last quarter'\''\\\\\\\", \\\\\\\"region\\\\\\\"], \\\\\\\"formulas\\\\\\\": []}}]}\\\"\\n datamodel_sources:\\n - guid: 62f3e9b5-4fcc-4352-b8ad-fdddc2287506\\n obj_id: RetailSales-3bc18302\\n tags: []\\n- type: RECIPE\\n content:\\n user_query: What is the total sales by date?\\n recipe: |-\\n 1. Brief Answer Summary\\n {\\n \\\"brief_summary\\\": \\\"Visualizes total sales revenue over time on a daily basis.\\\",\\n \\\"nl_query\\\": \\\"What is the total sales by date?\\\",\\n \\\"display_tml_tokens\\\": \\\"\\\"\\n }\\n\\n 2. Call NLSV2_Tool with these arguments\\n {\\n \\\"lossy_tml_tokens\\\": \\\"[date] [sales]\\\",\\n \\\"lossy_formulas\\\": []\\n }\\n datamodel_sources:\\n - guid: 62f3e9b5-4fcc-4352-b8ad-fdddc2287506\\n obj_id: RetailSales-3bc18302\\n tags: []\\n- type: ALWAYS_APPLY_RULES\\n content:\\n rules:\\n - \\\"When asking for '\''top'\'' results without specifying a number, default to top 20\\\"\\n - \\\"Use sales column as primary metric; if sales data unavailable, fall back to quantity purchased column\\\"\\n datamodel_sources:\\n - guid: 62f3e9b5-4fcc-4352-b8ad-fdddc2287506\\n obj_id: RetailSales-3bc18302\\n tags: []\\n\" }",
+ "dry_run": true
+}'
+----
+
+=== Example response
+
+[source,JSON]
+----
+{
+ "status": "SUCCESS",
+ "summary": [
+ {
+ "memory_type": "RULES",
+ "source": {
+ "identifier": "62f3e9b5-4fcc-4352-b8ad-fdddc2287506",
+ "type": "DATA_MODEL"
+ },
+ "existing_record_count": 3,
+ "deleted_record_count": 3,
+ "inserted_record_count": 3,
+ "failed_record_count": 0
+ },
+ {
+ "memory_type": "RECIPES",
+ "source": {
+ "identifier": "62f3e9b5-4fcc-4352-b8ad-fdddc2287506",
+ "type": "DATA_MODEL"
+ },
+ "existing_record_count": 3,
+ "deleted_record_count": 3,
+ "inserted_record_count": 3,
+ "failed_record_count": 0
+ },
+ {
+ "memory_type": "ALWAYS_APPLY_RULES",
+ "source": {
+ "identifier": "62f3e9b5-4fcc-4352-b8ad-fdddc2287506",
+ "type": "DATA_MODEL"
+ },
+ "existing_record_count": 0,
+ "deleted_record_count": 0,
+ "inserted_record_count": 1,
+ "failed_record_count": 0
+ }
+ ],
+ "validation_failures": [],
+ "diagnostics": [],
+ "operation_id": "62f3e9b5-4fcc-4352-b8ad-fdddc2287506"
+ }
+----
+
+
+=== Response parameters
+Based on the status of the import operation, the API returns a response code. Note that the `200` response does not guarantee a successful import. Verify the `status` field in the response body to ensure there are no validation errors.
+
+[cols="2,5", options="header"]
+|===
+| Parameter | Description
+| `status`
+| Terminal status of the import operation. After an import operation, the 200 response can include one of the following status values:
+
+* `SUCCESS` to indicate a successful import.
+* `VALIDATION_FAILED`. File or row-level validation failed before any data was written. Inspect `validation_failures` for per-item error details.
+* `FAILED` to indicate that the import operation has failed. Verify the diagnostics section. +
+A `sub_status` of `ROLLED_BACK` means all changes are rolled back and the original memory is intact. +
+A `sub_status` of `FAILURE` indicates a non-rollback error.
+| `summary`
+a| Per data model and memory type result entries. Null when the import failed before any record processing occurred. Each entry in the `summary` array covers one (memory type, target data model) combination.
+
+* `memory_type`: Type of memory these counts apply to: `RULES`, `RECIPES`, or `ALWAYS_APPLY_RULES`.
+* `source`: Data source type and ID. Type is always `DATA_MODEL`.
+* `existing_record_count`: Number of memory entries of this type that existed on the target data model before the import.
+* `deleted_record_count`: Number of existing entries that were deleted during the import operation.
+* `inserted_record_count`: Number of entries from the memory file that were inserted.
+* `failed_record_count`: Number of records of this type that failed validation or processing.
+
+| `validation_failures`
+a| Per-item validation failure entries.
+
+* `line_number`: Best-effort line number of the offending item in the YAML file. May be null when the line cannot be determined.
+* `reason`: Machine-readable category for the failure. For more information, see xref:spotter-ai-memory-api.adoc#validation-error-reference[Validation errors].
+* `field_name`: Dotted path to the offending field within the item. For example, `content.rule_definition`. Absent when the failure is at the item level rather than the field level.
+* `message`: Human-readable description of the failure.
+
+| `diagnostics`
+a| Diagnostic message groups for fatal errors, rollbacks, and non-fatal warnings, each grouped by severity.
+
+`sub_status`::
+Severity or disposition of this diagnostic group: +
+** `WARNING`: The import succeeded but with non-fatal caveats. For example, some older memory entries could not be fully cleaned up.
+** `FAILURE`: A fatal error prevented the import from completing. The state of memory on the target may be unpredictable.
+** `ROLLED_BACK`: The insert of new memory entries failed. Every successful insert was undone and the original memory is intact.
+** `UNKNOWN`: Uncategorized diagnostic.
+
+`messages`::
+Human-readable messages for this diagnostic group.
+
+| `operation_id`
+a| Server-generated identifier for this import operation. Include this value in support tickets to correlate server-side logs with the request.
+||
+|===
+
+=== Validations reference
+The payload is fully validated before anything is written irrespective of the `dry_run` parameter setting. If any item fails validation, the entire import is rejected, with the failure details returned in the response.
+
+To avoid validation errors:
+
+* Ensure that the memory file and its content do not exceed the xref:spotter-ai-memory-api.adoc#memory-file-limits[limits]. A data model referenced by more than one `ALWAYS_APPLY_RULES` item is rejected. Ensure that you combine them into a single item's `rules` list.
+* The content string does not include any unknown keys at the top level, within an item, or under `content`.
+* Ensure that the `type` for each item is set to the three supported values (`RULE`, `RECIPE`, and `ALWAYS_APPLY_RULES`), and the `content` string for each memory entry matches that type's shape and all required fields are defined.
+* Ensure that there are no non-string or empty `tags`. Certain tags reserved for internal use are stripped automatically before the item is stored.
+
+[#validation-error-reference]
+=== Validation error reference
+
+If the validation fails, the API returns `200` with a terminal `status` of `VALIDATION_FAILED` or `FAILED`, and includes the details in the `validation_failures` and `diagnostics` sections of the API response.
+
+* *VALIDATION_FAILED*: Indicates schema or semantic validation failure. Inspect `validation_failures` and fix the items. Each entry in `validation_failures` carries one of the following error types:
+
+** `SCHEMA`: Indicates that YAML structure is invalid or malformed.
+** `VALIDATION`: Indicates that a required field is missing, exceeds the limit, or an incorrect GUID.
+** `CHAR_LIMIT`: Indicates that a content field exceeds the character limit.
+** `UNRESOLVED_SOURCE`: A referenced data model GUID could not be resolved on the target. Check that all GUIDs in the memory file correspond to data models that exist on the target environment.
+** `ACCESS_DENIED`: The user making the API request does not have edit access on a referenced data model.
+* *FAILED*: Indicates incomplete import. Inspect `diagnostics` to verify the errors.
+
+==== Validation failure response
+
+Invalid data model::
+[source,json]
+----
+{
+ "status": "VALIDATION_FAILED",
+ "summary": null,
+ "validation_failures": [
+ {
+ "line_number": 2,
+ "reason": "UNRESOLVED_SOURCE",
+ "field_name": "datamodel_sources[0].guid",
+ "message": "unknown datamodel guid: 62f3e9b5-4fcc-4352-b8ad-fdddc228750"
+ }
+ ],
+ "diagnostics": [
+ {
+ "sub_status": "FAILURE",
+ "messages": [
+ "unknown datamodel guid: 62f3e9b5-4fcc-4352-b8ad-fdddc228750"
+ ]
+ }
+ ],
+ "operation_id": null
+}
+----
+
+Inaccessible data models::
+[source,json]
+----
+{
+ "status": "VALIDATION_FAILED",
+ "summary": null,
+ "validation_failures": [
+ {
+ "line_number": 2,
+ "reason": "ACCESS_DENIED",
+ "field_name": "datamodel_sources[0]",
+ "message": "Insufficient permissions on datamodel '62f3e9b5-4fcc-4352-b8ad-fdddc2287506'"
+ },
+ {
+ "line_number": 8,
+ "reason": "ACCESS_DENIED",
+ "field_name": "datamodel_sources[0]",
+ "message": "Insufficient permissions on datamodel '62f3e9b5-4fcc-4352-b8ad-fdddc2287506'"
+ }
+ ],
+ "diagnostics": [
+ {
+ "sub_status": "FAILURE",
+ "messages": [
+ "Memory import validation failed with 2 error(s): Insufficient permissions on datamodel '44444444-4444-4444-4444-444444444444'; Insufficient permissions on datamodel '33333333-3333-3333-3333-333333333333'"
+ ]
+ }
+ ],
+ "operation_id": null
+}
+----
+
+Character-limit validations::
+[source,json]
+----
+{
+ "status": "VALIDATION_FAILED",
+ "summary": [],
+ "validation_failures": [
+ {
+ "line_number": 3,
+ "reason": "CHAR_LIMIT",
+ "field_name": "content.rule_definition",
+ "message": "content.rule_definition is 1073 characters; max allowed is 1000"
+ },
+ {
+ "line_number": 49,
+ "reason": "CHAR_LIMIT",
+ "field_name": "content.user_query",
+ "message": "content.user_query is 1150 characters; max allowed is 1000"
+ },
+ {
+ "line_number": 49,
+ "reason": "CHAR_LIMIT",
+ "field_name": "content.recipe",
+ "message": "content.recipe is 3574 characters; max allowed is 2000"
+ }
+ ],
+ "diagnostics": [
+ {
+ "sub_status": "FAILURE",
+ "messages": [
+ "Validation failures present; fix them and re-run to see the DRY_RUN preview."
+ ]
+ }
+ ],
+ "operation_id": "f0c0b5f3-6b48-4f20-9ebf-67e1b6bcd4e5"
+}
+----
+
+Import success response::
+
+[source,JSON]
+----
+{
+ "status": "SUCCESS",
+ "summary": [
+ {
+ "memory_type": "RULES",
+ "source": {
+ "identifier": "62f3e9b5-4fcc-4352-b8ad-fdddc2287506",
+ "type": "DATA_MODEL"
+ },
+ "existing_record_count": 3,
+ "deleted_record_count": 3,
+ "inserted_record_count": 2,
+ "failed_record_count": 0
+ },
+ {
+ "memory_type": "RECIPES",
+ "source": {
+ "identifier": "62f3e9b5-4fcc-4352-b8ad-fdddc2287506",
+ "type": "DATA_MODEL"
+ },
+ "existing_record_count": 7,
+ "deleted_record_count": 7,
+ "inserted_record_count": 4,
+ "failed_record_count": 0
+ },
+ {
+ "memory_type": "ALWAYS_APPLY_RULES",
+ "source": {
+ "identifier": "62f3e9b5-4fcc-4352-b8ad-fdddc2287506",
+ "type": "DATA_MODEL"
+ },
+ "existing_record_count": 0,
+ "deleted_record_count": 0,
+ "inserted_record_count": 1,
+ "failed_record_count": 0
+ }
+ ],
+ "validation_failures": [],
+ "diagnostics": [],
+ "operation_id": "10f7b113-7872-403b-a3ab-0152dc591b54"
+}
+----
+
+== Additional resources
+
+* link:https://docs.thoughtspot.com/cloud/latest/spotter-memory[Spotter memory documentation, window=_blank]
+* +++ REST API Playground - Export memory endpoint +++
+* +++REST API Playground - Import memory endpoint+++
diff --git a/modules/ROOT/pages/tml.adoc b/modules/ROOT/pages/tml.adoc
index 9ffba0d70..8619546fb 100644
--- a/modules/ROOT/pages/tml.adoc
+++ b/modules/ROOT/pages/tml.adoc
@@ -5,6 +5,7 @@
:page-title: TML
:page-pageid: tml
:page-description: The TML API endpoints allow you to export and import TML files
+// SOURCE: SCAL-307283, SCAL-317357
ThoughtSpot Modeling Language (TML) is a scriptable format developed by ThoughtSpot for exporting, modifying, and migrating metadata objects such as Models, Views, Tables, Liveboards, and Answers. TML files allow you to manage and version control these objects outside the ThoughtSpot UI, supporting workflows like bulk changes, migration between environments, and programmatic edits via REST API. Users can use link:https://docs.thoughtspot.com/cloud/latest/tml[TML] to model data and build analytics content in the test environment in a flat-file format, and then import and deploy it in their environments.
@@ -17,6 +18,7 @@ The TML syntax varies per object type. However, all TMLs follow a general patter
See the following pages for the detailed syntax of TML files for each object type: +
* link:https://docs.thoughtspot.com/cloud/latest/tml-answers[TML for Answers, window=_blank] +
+* link:https://docs.thoughtspot.com/cloud/latest/tml-collections[TML for Collections, window=_blank] +
* link:https://docs.thoughtspot.com/cloud/latest/tml-connections[TML for Connections, window=_blank] +
* link:https://docs.thoughtspot.com/cloud/latest/tml-joins[TML for Joins, window=_blank] +
* link:https://docs.thoughtspot.com/cloud/latest/tml-liveboards[TML for Liveboards, window=_blank] +
@@ -76,6 +78,63 @@ 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.
====
+[#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.
+
+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.
@@ -323,6 +382,7 @@ If Orgs are enabled on your instance, the API returns task status only for objec
|**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.
diff --git a/modules/ROOT/pages/tse-eco-mode.adoc b/modules/ROOT/pages/tse-eco-mode.adoc
index 5b5fc8b2c..08904dbfc 100644
--- a/modules/ROOT/pages/tse-eco-mode.adoc
+++ b/modules/ROOT/pages/tse-eco-mode.adoc
@@ -1,88 +1,77 @@
= Cluster maintenance and upgrade
:toc: true
-:toclevels: 1
+:toclevels: 2
:page-title: Update cluster state
:page-pageid: tse-cluster
-:page-description: If you are using a ThoughtSpot Cloud cluster in the economy mode in your embedded deployments, use the APIs to restart an inactive cluster.
+:page-description: If you are using a ThoughtSpot Cloud cluster in the economy mode in your embedded deployments, use the APIs to restart an inactive cluster.
At any given time, a ThoughtSpot application instance can be in any one of the following states:
* `ACTIVE` +
-Indicates that the cluster is active and user activity is detected.
+When the cluster is running and user activity is detected.
* `UNDER_MAINTENANCE` +
-Indicates that the cluster is down for maintenance due to upgrade or patching.
-* `STOPPED`
-Indicates that the cluster is stopped and no user activity is detected.
+When the cluster is temporarily unavailable because maintenance, upgrade, or patching is in progress.
+* `STOPPED` +
+When the cluster is inactive and no user activity is detected.
* `STARTING`/`PENDING` +
-The cluster is currently starting, or some other workflow is running on the cluster.
+When the cluster is starting, or another workflow is currently in progress.
-== Cluster status during upgrade
-With ThoughtSpot’s Minimal Downtime Ephemeral Mode upgrade option, we upgrade ThoughtSpot in the background while users can use ThoughtSpot in Ephemeral mode. This means that during the upgrade, the system will be in transient state, yet it allows users to create and view data. However, any new objects created during the upgrade will be lost.
+== Check whether a cluster is under maintenance
+To determine whether a cluster is under maintenance, send a `GET` request to one of the following endpoints:
-When the upgrade starts, the ThoughtSpot instance operates in the Ephemeral (Read-Only mode) and the cluster state changes to `UNDER_MAINTENANCE`.
+* `GET /api/rest/2.0/system/banner` (Recommended)
+* `GET /tspublic/v1/admin/banner` (legacy REST API framework)
-ThoughtSpot users can determine if their instance is under maintenance by sending a `GET` request to one of the following API endpoints:
+These APIs return banner information that indicates whether maintenance is in progress. Embedded applications can also use the banner text to inform users about the current cluster status.
-* REST API v1 endpoint +
-`GET /tspublic/v1/admin/banner`
-* REST API v2 endpoint +
-`GET /api/rest/2.0/system/banner`
+=== REST API v2 request
-ThoughtSpot Embedded application users can also view the banner text by calling the above APIs.
-
-=== REST v1 API request
-
-.cURL
[source,cURL]
----
curl -X GET \
--header 'Accept: application/json' \
-'https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/admin/banner'
-----
-
-.Request URL
-
-----
-https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/admin/banner
+'https://{ThoughtSpot-Host}/api/rest/2.0/system/banner'
----
-=== REST v2 API request
+=== REST API v1 request
-.cURL
[source,cURL]
----
curl -X GET \
--header 'Accept: application/json' \
-'https://{ThoughtSpot-Host}/api/rest/2.0/system/banner'
+'https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/admin/banner'
----
-.Request URL
-----
-https://{ThoughtSpot-Host}/api/rest/2.0/system/banner
-----
=== API response
+In the API response, check the following fields:
-If the cluster in maintenance mode, the API returns the following response:
+* `under_maintenance`: A Boolean value that indicates whether the cluster is currently under maintenance.
+* `banner_text`: A user-facing message that describes the current system state.
+
+[NOTE]
+====
+Administrators of an embedded application can configure custom banner text to communicate maintenance status to users.
+====
+
+.Example response when the cluster is under maintenance
----
-{"banner_text":"This system is currently being upgraded and is in ephemeral mode. You can continue to use it to visualize data. Any objects you create or modify during this period will be lost when the upgrade is complete.","under_maintenance":true}
+{"banner_text":"This system is currently under maintenance. Check back in a few hours.","under_maintenance":true}
----
-If the cluster is not in maintenance mode, the API returns the following response:
+.Example response when the cluster is operating normally
----
{"banner_text":"This system is functioning normally. No maintenance is in progress.","under_maintenance":false}
----
-Administrators of the ThoughtSpot Embedded app can create their custom banner text and display it to indicate the cluster upgrade status.
-
-== Idle sensing
-If you are using a ThoughtSpot Cloud instance for embedded deployments in your development or production environment, you can enable idle sensing to save costs and allow your cluster to operate in `economy` mode.
+== Idle sensing and economy mode
+If you use a ThoughtSpot Cloud instance for embedded deployments, you can enable idle sensing to reduce cost and allow the cluster to operate in economy mode.
-If idle sensing is enabled on your cluster, your cluster will be automatically stopped if there is no user activity detected for a given time threshold. By default, the idle time threshold is set to 120 minutes. To enable this feature on your clusters, contact ThoughtSpot Support.
+When idle sensing is enabled, the cluster automatically stops after a period of inactivity. The default idle threshold is 120 minutes. To enable this feature on your cluster, contact ThoughtSpot Support.
-=== Get information about the status of a cluster
-By default, a ThoughtSpot cluster running the `economy` mode stops if there is no user activity for two hours. When a user tries to access a cluster that's in the `STOPPED` state, the API calls will return the `"cluster-state": "Stopped"` in the response header.
+=== Get the status of an inactive cluster
+When a cluster in economy mode has no user activity for 120 minutes, it transitions to the `STOPPED` state. If a user accesses a stopped cluster, the response headers include the cluster state.
[source,cURL]
----
@@ -96,65 +85,65 @@ By default, a ThoughtSpot cluster running the `economy` mode stops if there is n
Cluster-State: Stopped
----
-To restart the cluster, complete the steps described in the following section.
+If the cluster is stopped, restart it by using the API described in the next section.
-== Start an inactive cluster using API
-On a regular ThoughtSpot Cloud cluster, users can restart an inactive cluster using `CAPTCHA`. However, on embedded instances, the `CAPTCHA`-based cluster activation is not supported. Instead, the embedded application user can send a `GET` request to their instance with the following query parameters in the request URL:
+=== Start an inactive cluster using API
+On a standard ThoughtSpot Cloud cluster, users can restart an inactive cluster by using a Completely Automated Public Turing test to tell Computers and Humans Apart (CAPTCHA). For embedded deployments, CAPTCHA-based activation is not supported. Instead, send a GET request with the required query parameters:
* `tse=true`
* `start_cluster=true`
-For example, to start an inactive cluster, send a `GET` request in the following parameters:
-
.Production environment
[source,http]
----
https://{ThoughtSpot-Host}/?tse=true&start_cluster=true
----
-**Staging environment**
-
+.Staging environment
[source,http]
----
https://{cluster-name}.thoughtspotstaging.cloud/?tse=true&start_cluster=true
----
-**Development environment**
-
+.Development environment
[source,http]
----
https://{cluster-name}.thoughtspotdev.cloud/?tse=true&start_cluster=true
----
-In the request header, you must include the `security-key`. This `security-key` is used to authenticate your request when xref:trusted-auth-secret-key.adoc#trusted-auth-enable[trusted authentication is enabled]. ThoughtSpot Embedded users can obtain the `security key` for their instance or Org context from their ThoughtSpot administrator.
+=== Required headers
+In the request header, you must include `security-key` and `X-Thoughtspot-Org-Id`.
-If your instance has Orgs:
+`security-key`::
+Is required to authenticate your request when xref:trusted-auth-secret-key.adoc#trusted-auth-enable[trusted authentication is enabled]. ThoughtSpot Embedded users can obtain the `security-key` for their instance or Org context from their ThoughtSpot administrator.
+`X-Thoughtspot-Org-Id`::
+If your instance has Orgs:
* Specify the Org ID in the request header along with the security key of that specific Org context. If the security key does not match the Org ID, the API returns an error.
-* If the request header includes only the security key with no Org ID, it's considered to be the security key of the global Org context (ALL Orgs). If it does not match the key generated for the All Orgs context, the API returns an error.
-
+* If the request header includes only the security key with no Org ID, it's considered to be the security key of the global Org context (**All Orgs**). If it does not match the key generated for the All Orgs context, the API returns an error.
++
When the cluster becomes available, users are logged into the Org context based on the key provided in the request.
The following example shows the cURL request for restarting a cluster:
-[source, cURL]
+[source,cURL]
----
$ curl -X GET 'https://.thoughtspot.cloud/?tse=true&start_cluster=true' \
-H 'X-Thoughtspot-Org-Id: {Org_Id}' \
-H 'security-key: e8ade677-c3f1-461d-8b7f-7f0fe4e024f0'
----
-If the `GET` request is successful, the cluster starts.
+If the `GET` request is successful, the cluster starts. When the cluster becomes available, users are signed in to the Org context associated with the provided key.
-== Response header
+=== Response header values
Note the cluster state in the response header:
* `STARTING` +
-Indicates that the cluster is starting. It may take a few minutes for the cluster to become active.
+If the cluster is starting. It may take a few minutes to become active.
* `UNKNOWN` +
-Indicates a possible error. Contact your administrator or ThoughtSpot Support if the cluster does not start in 5-10 minutes.
+A possible error occurred. If the cluster does not start within 5 to 10 minutes, contact your administrator or ThoughtSpot Support.
-[source,]
+[source,http]
----
HTTP/1.1 200 OK
Server: awselb/2.0
@@ -165,11 +154,11 @@ Indicates a possible error. Contact your administrator or ThoughtSpot Support if
Cluster-State: Starting
----
-== Response codes
+=== Response codes
[options="header", cols="1,4"]
|===
|HTTP status code|Description
|**200**|Successful operation
|**400**|Invalid request
|**401**|Unauthorized access
-|===
\ No newline at end of file
+|===
diff --git a/modules/ROOT/pages/whats-new.adoc b/modules/ROOT/pages/whats-new.adoc
index e81daa1b5..5b2e4581b 100644
--- a/modules/ROOT/pages/whats-new.adoc
+++ b/modules/ROOT/pages/whats-new.adoc
@@ -23,6 +23,107 @@ This page lists new features, enhancements, and deprecated functionality introdu
// *Affects:* Developers, Administrators, End Users
// ============================================================
+== 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]. +
+*Recommended SDK versions*: Visual Embed SDK v1.51.0 and later
+
+[.cl-table, cols="2,4", frame=none, grid=none]
+|===
+a|
+[.cl-label]
+*Version 26.8.0.cl*
+
+a|
+[discrete]
+==== 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].
+
+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].
+
+---
+
+
+[discrete]
+==== Liveboard embedding
+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.
+* Compact header (`isLiveboardCompactHeaderEnabled`) +
+Enables 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) +
+Enables the xref:embed-pinboard.adoc#_liveboard_grouping_and_styling[Liveboard styling and grouping] feature.
+* Filter interactivity (`isEnhancedFilterInteractivityEnabled`) +
+Enables interactive filter chips that allow users to add, update, or remove filters in an embedded Liveboard.
+
+---
+
+[discrete]
+==== Navigation and homepage V1/V2 deprecated [.version-badge.deprecated]#Deprecated#
+Starting from ThoughtSpot Cloud 26.8.0.cl, the classic V1 and V2 navigation and homepage experience modes are deprecated. All ThoughtSpot Embedded sessions now render in the V3 navigation experience by default. For more information, see xref:full-app-customize.adoc#nav-v1-v2-deprecation[V1 and V2 deprecation].
+
+---
+
+[discrete]
+==== Wide logo dimension [.version-badge.breaking]#Breaking#
+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].
+
+---
+
+
+[discrete]
+==== 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).
+
+These privileges can be assigned independently per user or group. Update privilege assignments in your embedded application accordingly.
+
+---
+
+[discrete]
+==== Personalized Views portability [earlyAccess eaBackground]#Early Access#
+ThoughtSpot improves the portability of Personalized Views across environments. Import operations use smart merge logic to avoid duplicating Personalized Views.
+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].
+
+---
+
+[discrete]
+==== Discoverability checkbox deprecation [.version-badge.breaking]#Breaking#
+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]
+==== 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].
+
+---
+
+[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].
+
+---
+
+|===
+
== July 2026
**Release version**: ThoughtSpot Cloud 26.7.0.cl +
@@ -30,7 +131,7 @@ This page lists new features, enhancements, and deprecated functionality introdu
*Recommended SDK versions*: Visual Embed SDK v1.50.0 and later
[.cl-table, cols="2,4", frame=none, grid=none]
-|=====
+|===
a|
[.cl-label]
*Version 26.7.0.cl*
@@ -103,7 +204,7 @@ The xref:webhooks-api.adoc#_updating_a_webhook[webhook update API endpoint] supp
[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.
+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].
---
@@ -119,7 +220,7 @@ For information about REST API v2 enhancements in this release, see the xref:res
---
-|=====
+|===
== June 2026
@@ -128,7 +229,7 @@ For information about REST API v2 enhancements in this release, see the xref:res
*Recommended SDK versions*: Visual Embed SDK v1.49.0 and later
[.cl-table, cols="2,4", frame=none, grid=none]
-|=====
+|===
a|
[.cl-label]
*Version 26.6.0.cl*
@@ -175,7 +276,7 @@ The menu link to the GraphQL playground has been removed from the UI.
[discrete]
==== Liveboard browser cache refresh
-To improve load performance and reduce, you can now enable the Liveboard cache option with a **Refresh** button to allow your users to clear cache and refresh visualization data when required. For more information, see xref:api-changelog.adoc#_liveboard_browser_cache_refresh[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].
---
@@ -189,7 +290,7 @@ The Visual Embed SDK version 1.49.0 includes several new features and enhancemen
==== 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
@@ -200,7 +301,7 @@ This release introduces new API endpoints for Spotter, connections and trusted a
[.cl-table, cols="2,4", frame=none, grid=none]
-|=====
+|===
a|
[.cl-label]
*Version 26.5.0.cl*
@@ -271,7 +372,7 @@ The Visual Embed SDK version 1.48.0 includes several new features and enhancemen
==== 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
@@ -292,7 +393,7 @@ 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.
+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].
diff --git a/modules/tutorials/pages/rest-api/rest-api_lesson-02.adoc b/modules/tutorials/pages/rest-api/rest-api_lesson-02.adoc
index 3f551f338..5e08236a5 100644
--- a/modules/tutorials/pages/rest-api/rest-api_lesson-02.adoc
+++ b/modules/tutorials/pages/rest-api/rest-api_lesson-02.adoc
@@ -5,6 +5,10 @@
:page-pageid: rest-api__lesson-02
:description: A lesson on a simple implementation of the V2.0 using Python
+[IMPORTANT]
+====
+The workflows and examples in this tutorial use a legacy version of the ThoughtSpot REST API link:https://github.com/thoughtspot/thoughtspot_rest_api_python[ThoughtSpot Community SDK, window=_blank]. We recommend using the xref:python-sdk.adoc[ThoughtSpot-provided Python SDK for REST API v2], which supports both asynchronous and synchronous invocation, transparent token refresh, server-sent event (SSE) streaming, file uploads and downloads, and error handling.
+====
== Get started
We'll use the files from the link:https://github.com/thoughtspot/tse-api-tutorial[tse-api-tutorial GitHub repository, window=_blank] that you downloaded at the beginning of the tutorial.
@@ -65,9 +69,8 @@ import requests
import json
thoughtspot_url = 'https://{}.thoughtspot.cloud'
-org_id = 1613534286
+org_id = 0
api_version = '2.0'
-
----
Now, let's construct the starting portion of any API endpoint URL and define the most basic headers that will be used by every call:
@@ -77,12 +80,12 @@ Now, let's construct the starting portion of any API endpoint URL and define the
...
base_url = '{thoughtspot_url}/api/rest/{version}/'.format(thoughtspot_url=thoughtspot_url, version=api_version)
api_headers = {
- 'X-Requested-By': 'ThoughtSpot',
+ 'X-Requested-By': 'ThoughtSpot',
'Accept': 'application/json'
}
----
-== 02 - Use a Session object
+== 02 - Use a session object
Rather than setting the full configuration for each HTTP request, you can construct a `Session` object from the `requests` library, which keeps an open HTTP connection and maintains settings like headers and cookies between individual HTTP actions.
@@ -99,7 +102,7 @@ requests_session = requests.Session()
requests_session.headers.update(api_headers)
# Define the JSON message, in Python object syntax (close but not exactly JSON)
-json_post_data = { // a request body }
+json_post_data = { # a request body }
# Set the URL of the endpoint
url = base_url + "{api_endpoint_ending}"
@@ -123,7 +126,7 @@ In the REST API V2.0 Playground:
. Go to *Authentication* > *Get Full Access Token*.
. Specify the parameters.
-. Copy the JSON body from the right side of the Playground. Python dicts use the same syntax, but you must update booleans to be *uppercase*.
+. Copy the JSON body from the right side of the Playground. Python dicts use the same syntax, but you must capitalize Python's boolean keywords (`True`/`False`).
. Replace any hard-coded values with the *global variables* you declared so that you can easily update requests at the top of your script and ensure those values change everywhere they are used:
+
[,python]
@@ -137,13 +140,13 @@ json_post_data = {
"password": "y0urP@ssword",
"validity_time_in_sec": 3600,
"org_id": org_id,
- "auto_create": False # make sure to uppercase in Python
+ "auto_create": False # capitalize booleans in Python
}
----
. Make a `.post()` request using the `Session` object. +
+
-We expect a JSON response on success, which you can access using the `.json()` method of the `Response` object.
+We expect a JSON response on success, which you can access using the `.json()` method of the `Response` object.
+
From the Playground, we can see that there is a `token` property in the response.
@@ -152,14 +155,13 @@ From the Playground, we can see that there is a `token` property in the response
+
[,python]
----
-....
+...
resp = requests_session.post(url=url, json=json_post_data)
resp_json = resp.json()
print(json.dumps(resp_json, indent=2))
token = resp_json["token"]
print("Here's the token:")
print(token)
-....
----
==== Run the script to test
@@ -199,7 +201,7 @@ Unfortunately, making a REST API request to a web server can result in any numbe
Good coding involves testing for and handling error situations.
=== Using try and except in Python
-Python code raises `link:https://docs.python.org/3/tutorial/errors.html[Exceptions, target=_blank]` when an error is encountered.
+Python code raises `link:https://docs.python.org/3/tutorial/errors.html[Exceptions, window=_blank]` when an error is encountered.
If an `Exception` is raised and is not *handled*, the script exits and displays the message provided with the Exception and other details of what failed.
@@ -210,28 +212,28 @@ Every HTTP request can potentially result in an error, and we don't want to cont
The most generic `try...except` block will capture *any* `Exception`:
[,python]
----
-try:
+try:
resp = requests_session.post(url=url, json=json_post_data)
resp_json = resp.json() # Returns JSON body of resp to Python Dict
print(resp_json)
token = resp_json["token"]
-except Exception as e:
- # do whatever is necessary in exception case
+except Exception as e:
+ # do whatever is necessary in exception case
# Code after the try block will now run even after Exception
----
=== Checking for requests HTTPError exceptions
-The `requests` library does not raise an `Exception` when an HTTP request completes "properly", that is to say a well-formed HTTP response is received from a request.
+The `requests` library does not raise an `Exception` when an HTTP request completes "properly," that is to say a well-formed HTTP response is received from a request.
However, as you saw in the previous lesson, HTTP responses include a *Status Code* that indicates if the requested action was a *Success* or an *Error*.
-To raise `Exceptions` when the response does not include a *Success* status code, call the `Response.raise_for_status()` method for each call, which throws the specific `requests.exceptions.HTTPError` `Exception` when a 400 series or 500 status code is returned:
+To raise `Exceptions` when the response does not include a *Success* status code, call the `Response.raise_for_status()` method for each call, which throws the specific `requests.exceptions.HTTPError` `Exception` when a 400 or 500 series status code is returned:
[source,python]
----
-try:
+try:
resp = requests_session.post(url=url, json=json_post_data)
resp.raise_for_status()
print(resp)
@@ -265,7 +267,7 @@ json_post_data = {
"password": "y0urP@ssword",
"validity_time_in_sec": 3600,
"org_id": org_id,
- "auto_create": False # make sure to uppercase in Python
+ "auto_create": False # capitalize booleans in Python
}
try:
@@ -309,7 +311,7 @@ try:
...
----
-You may have noticed many steps that are repeated each time for any given request.
+You may have noticed many steps that are repeated each time for any given request.
In the next lesson, we'll cover using a *library* that wraps most of these repeated steps, so that you can focus simply on the logic of your API workflows.
diff --git a/src/configs/doc-configs.js b/src/configs/doc-configs.js
index 2164dba81..19ebabe2b 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.7.0.cl?pageid=whats-new',
- linkText: 'Version 26.7.0.cl',
+ linkHref: '/docs/26.8.0.cl?pageid=whats-new',
+ linkText: 'Version 26.8.0.cl',
openInNewTab: true,
},
TYPE_DOC_PREFIX: 'typedoc',
@@ -48,10 +48,10 @@ module.exports = {
},
VERSION_DROPDOWN: [
{
- label: '26.7.0.cl',
- link: '26.7.0.cl',
+ label: '26.8.0.cl',
+ link: '26.8.0.cl',
subLabel: 'Cloud (Latest)',
- iframeUrl: 'https://developer-docs-26-7-0-cl.vercel.app/docs/',
+ iframeUrl: 'https://developer-docs-26-8-0-cl.vercel.app/docs/',
},
],
CUSTOM_PAGE_ID: {
diff --git a/static/doc-images/images/style-applogo.png b/static/doc-images/images/style-applogo.png
index cad220b36..f88923e23 100644
Binary files a/static/doc-images/images/style-applogo.png and b/static/doc-images/images/style-applogo.png differ
diff --git a/static/doc-images/images/style-widelogo.png b/static/doc-images/images/style-widelogo.png
index 69bee0157..dfa82108f 100644
Binary files a/static/doc-images/images/style-widelogo.png and b/static/doc-images/images/style-widelogo.png differ