diff --git a/modules/ROOT/pages/api-changelog.adoc b/modules/ROOT/pages/api-changelog.adoc index da7ec9f9f..366e72b15 100644 --- a/modules/ROOT/pages/api-changelog.adoc +++ b/modules/ROOT/pages/api-changelog.adoc @@ -8,6 +8,184 @@ 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]. +// ============================================================ +// SOURCE: src/embed/conversation.ts, src/embed/spotter-viz-utils.ts, +// src/types.ts (visual-embed-sdk main branch, verified 2026-07-10) +// SOURCE: SCAL-310399, SCAL-312622, SCAL-293483, SCAL-309017 +// TODO: [WRITER] Confirm calendar month label — "August 2026" if release ships in +// late July / early August 2026. Verify with release team. +// TODO: [WRITER] Confirm whether Action enum values for Analyst actions +// (Action.ShowAnalysts, Action.CreateAnalyst, Action.EditAnalyst, +// Action.MakeCopyAnalyst, Action.ShareAnalyst, Action.DeleteAnalyst) +// are present in the released types.ts for SDK 1.51.0. They are referenced +// in SCAL-312622 but were not confirmed in types.ts source at time of authoring. +// Run a grep on the tagged SDK 1.51.0 release before publishing. +// ============================================================ + +== Version 1.51.x, August 2026 + +[width="100%", cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| + +[discrete] +===== Spotter Analysts +// SOURCE: src/embed/conversation.ts @version SDK: 1.51.0 | ThoughtSpot: 26.8.0.cl +// SOURCE: SCAL-310399, SCAL-312622 +The Visual Embed SDK 1.51.0 introduces controls for the Spotter Analysts feature in embedded applications. The Analysts section in the Spotter sidebar is disabled by default in TSE mode. + +New properties in `SpotterSidebarViewConfig` (supported on `SpotterEmbed`, `LiveboardEmbed`, and `AppEmbed`): + +`spotterAnalystLabel`:: +Custom singular label for the Analyst entity shown in the sidebar. + +Default: `"Analyst"` + +`spotterAnalystsLabel`:: +Custom label for the Analysts sidebar section header. + +Default: `"Analysts"` + + + +// SOURCE: src/embed/conversation.ts — SpotterChatViewConfig.enableStarterPrompts +`enableStarterPrompts` property in `SpotterChatViewConfig`:: + +When set to `true`, displays onboarding starter prompts in the Spotter chat interface on initial load. Supported on `SpotterEmbed`, `LiveboardEmbed`, and `AppEmbed`. + +Default: `false` + + + +// TODO: [WRITER] Verify these Action enum values exist in the SDK 1.51.0 release of types.ts. +// Source: SCAL-312622 Jira description. Not yet confirmed in types.ts grep at authoring time. + +New action IDs for (Analyst actions):: + +* `Action.ShowAnalysts` + +Controls visibility of the Analysts section in the sidebar. +* `Action.CreateAnalyst` + +Controls the Create Analyst action. +* `Action.EditAnalyst` + +Controls the Edit Analyst action. +* `Action.MakeCopyAnalyst` + +Controls the Make a Copy action. +* `Action.ShareAnalyst` + +Controls the Share Analyst action. +* `Action.DeleteAnalyst` + +Controls the Delete Analyst action. + +Example: embed Spotter with custom Analyst labels and restricted actions: + +[source,JavaScript] +---- +import { + SpotterEmbed, + Action, + AuthType, + init, +} from '@thoughtspot/visual-embed-sdk'; + +init({ + thoughtSpotHost: 'https://your-thoughtspot-host', + authType: AuthType.TrustedAuthTokenCookieless, + getAuthToken: () => fetch('/api/token').then(r => r.json()).then(d => d.token), +}); + +const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { + frameParams: { width: '100%', height: '100%' }, + worksheetId: '<%=datasourceGUID%>', + spotterSidebar: { + spotterAnalystLabel: 'Assistant', // Default: "Analyst" + spotterAnalystsLabel: 'My Assistants', // Default: "Analysts" + }, + spotterChat: { + enableStarterPrompts: true, // Default: false + }, + hideActions: [ + Action.CreateAnalyst, + Action.DeleteAnalyst, + ], +}); + +spotterEmbed.render(); +---- + +For more information, see xref:embed-spotter.adoc#spotter-analysts[Spotter Analysts in embedded applications]. + +|[tag greenBackground]#NEW FEATURE# a| + +[discrete] +===== SpotterViz loading state customization +// SOURCE: src/embed/spotter-viz-utils.ts @version SDK: 1.51.0 | ThoughtSpot Cloud: 26.8.0.cl +// SOURCE: SCAL-309017 +The Visual Embed SDK 1.51.0 extends the `SpotterVizConfig` interface with two new properties for customizing the SpotterViz panel loading state on embedded Liveboards and full-application embeds. + +`loaderHeadline`:: +Custom headline text shown in the SpotterViz loading state. Replaces the default loading headline. + + +`loaderTips`:: +Custom array of `SpotterVizLoaderTip` objects displayed as tips during the SpotterViz loading state. Replaces the default loading tips. + + +`SpotterVizLoaderTip` interface: + +[source,TypeScript] +---- +interface SpotterVizLoaderTip { + label: string; // Short label rendered alongside the tip (e.g., "Tip") + text: string; // Tip body text +} +---- + +Example usage: + +[source,JavaScript] +---- +const embed = new LiveboardEmbed('#embed-container', { + liveboardId: '<%=liveboardGUID%>', + spotterViz: { + brandName: 'MyBrand', + brandHeadline: "Hi, I'm", + description: 'Ask questions about your data', + inputChatPlaceholder: 'What would you like to know?', + loaderHeadline: 'Crunching the numbers...', + loaderTips: [ + { label: 'Tip', text: 'Try asking about revenue by region' }, + { label: 'Tip', text: 'Use natural language — no SQL needed' }, + { label: 'Tip', text: 'Ask for comparisons, trends, and breakdowns' }, + ], + }, + frameParams: { width: '100%', height: '100%' }, +}); + +embed.render(); +---- + +// TODO: [WRITER] Confirm with the SpotterViz team whether there is a maximum +// recommended or enforced limit on the number of loaderTips entries. + +For more information, see xref:embed-spotterViz.adoc[SpotterViz in embedded Liveboards]. + +|[tag greenBackground]#NEW FEATURE# a| + +[discrete] +===== HostEvent.Navigate — object format support +// SOURCE: src/types.ts (visual-embed-sdk main) — HostEvent.Navigate object format comment +// SOURCE: SDK: 1.51.0 | ThoughtSpot Cloud: 26.8.0.cl (confirmed from types.ts source) +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`. + +// TODO: [WRITER] Confirm whether `replace: false` is a valid option (push behavior) +// or whether omitting `replace` defaults to push behavior. + +|==== == Version 1.50.x, July 2026 @@ -23,6 +201,7 @@ A new `SpotterVizConfig` interface is available on `LiveboardViewConfig` and `Ap To customize app interactions, visibility of the UI elements, and style and appearance of the SpotterViz panel, the SDK also introduces CSS variables, action IDs, and embed and host event identifiers. For more information, see xref:embed-spotterViz.adoc[SpotterViz in embedded Liveboards]. + |[tag greenBackground]#NEW FEATURE# a| [discrete] diff --git a/modules/ROOT/pages/common/nav-in-product-help.adoc b/modules/ROOT/pages/common/nav-in-product-help.adoc index cf7312ff9..0b8df2ccb 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 62dc5391c..a77e23b94 100644 --- a/modules/ROOT/pages/common/nav-rest-api.adoc +++ b/modules/ROOT/pages/common/nav-rest-api.adoc @@ -20,23 +20,27 @@ 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}}/input-tables-api[Input Tables API] ** 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 diff --git a/modules/ROOT/pages/embed-pinboard.adoc b/modules/ROOT/pages/embed-pinboard.adoc index 3d8d67eee..93c78c350 100644 --- a/modules/ROOT/pages/embed-pinboard.adoc +++ b/modules/ROOT/pages/embed-pinboard.adoc @@ -10,6 +10,90 @@ 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. +// ============================================================ +// SOURCE: SCAL-309481, SCAL-292918, SCAL-295712, SCAL-312731 +// TODO: [WRITER] Review all four change notes in this section before publishing. +// Each TODO inline identifies a specific verification item. +// ============================================================ + +[#embed-pinboard-26-8] +== Changes in ThoughtSpot Cloud 26.8.0.cl [.version-badge.new]#New# + +=== WYSIWYG Liveboard PDF export +// SOURCE: SCAL-309481 +// TODO: [WRITER] Confirm with the SDK team whether Action.DownloadAsPdf behavior changes in 26.8.0.cl — specifically whether a new Action enum is introduced for the legacy PDF format. +// TODO: [WRITER] Confirm whether `enableV2Shell: true` is still required for the new PDF experience or is now the default in 26.8.0.cl. + +Starting from ThoughtSpot Cloud 26.8.0.cl, the WYSIWYG Liveboard PDF export experience is generally available (GA) for all users, including embedded deployments. The new PDF export renders the Liveboard exactly as it appears on screen — layout, filters, chart styles, and tab structure included. + +*Impact on embedded applications:* + +* `Action.DownloadAsPdf` — No code changes required. The WYSIWYG PDF experience is applied automatically on upgrade. +* If your application suppresses or customizes the PDF download action using `disabledActions` or `hiddenActions`, verify that behavior is unchanged after the upgrade. + +[source,JavaScript] +---- +// Example: suppress PDF download in an embedded Liveboard +const embed = new LiveboardEmbed('#embed', { + liveboardId: '<%=liveboardGUID%>', + disabledActions: [Action.DownloadAsPdf], + disabledActionReason: 'PDF export is disabled in this view.', +}); +---- + +=== Discoverability removed — explicit sharing required +// SOURCE: SCAL-292918 +// TODO: [WRITER] Confirm whether any REST API endpoint related to Liveboard sharing is affected by this change. Add a cross-reference to the REST API changelog if so. +// TODO: [WRITER] Confirm with the product team what the recommended migration path is for customers who relied on discoverability to distribute embedded content. + +The *Make this Liveboard discoverable* option has been removed in ThoughtSpot Cloud 26.8.0.cl. Liveboards are no longer discoverable by default — access is granted exclusively through explicit sharing. This is a backend behavior change; no SDK code changes are required. + +*Impact on embedded applications:* + +* Embedded users who previously relied on Liveboard discoverability to find shared content must now receive explicit sharing access from a ThoughtSpot administrator or Liveboard owner. +* Embedded applications that manage sharing programmatically via the REST API are not affected. + +=== TSE GA defaults — Compact Header, Hide Irrelevant Filters, Cover Filter Panel, Aether +// SOURCE: SCAL-295712 +// TODO: [WRITER] Confirm the exact list of features defaulted to GA in TSE for 26.8.0.cl with the TSE/product team (Navan Phase 1, Aether, Cover Filter Panel, Compact Header, Hide Irrelevant Filters). +// TODO: [WRITER] Confirm whether any feature requires an explicit opt-out flag if an embedded application relied on the previous non-default behavior. If so, document the opt-out property and its value. + +The following features are now generally available (GA) and enabled by default for all ThoughtSpot embedded deployments in 26.8.0.cl: + +[width="100%", cols="3,6"] +[options="header"] +|==== +|Feature |Description +|Compact Header |Renders a compact, space-efficient Liveboard header. Previously required explicit opt-in. +|Hide Irrelevant Filters |Automatically hides filters that are not applicable to the current Liveboard tab. +|Cover Filter Panel |Shows the filter panel as an overlay instead of inline. +|Aether UI |Updated ThoughtSpot Aether design system applied to embedded Liveboards. +// TODO: [WRITER] Confirm "Aether UI" is the correct product name for this feature. Verify with the design/product team. +|==== + +=== Navigation V3 is now the default +// SOURCE: SCAL-312731 +// TODO: [WRITER] Confirm the exact release in which Navigation V1 and V2 will be fully removed (not just deprecated). +// TODO: [WRITER] Confirm whether passing `navVersion: 'V1'` or `'V2'` in AppEmbed silently falls back to V3 or throws a console error in 26.8.0.cl. + +Starting from ThoughtSpot Cloud 26.8.0.cl, Navigation V3 is the default navigation experience for all embedded deployments. Navigation V1 and V2 are deprecated and will be removed in a future release. + +If your application explicitly sets `navVersion` to `V1` or `V2`, update your configuration: + +[source,JavaScript] +---- +// Deprecated — remove navVersion property in 26.8.0.cl +// navVersion: 'V2', + +// V3 is now the default — no explicit setting required +const embed = new AppEmbed('#embed', { + pageId: Page.Home, + // navVersion is no longer required; V3 is applied automatically +}); +---- + +For more information, see xref:full-app-customize.adoc[Customize the full app experience]. + == 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..30080e97d 100644 --- a/modules/ROOT/pages/embed-spotter.adoc +++ b/modules/ROOT/pages/embed-spotter.adoc @@ -8,6 +8,205 @@ You can embed the full Spotter experience in your applications using the `SpotterEmbed` component in the Visual Embed SDK. Using the customization settings available in the SDK for each Spotter version, you can configure the Spotter interface to suit the needs of your embedding application. +// SOURCE: SCAL-310399, SCAL-312622, SCAL-293483, SCAL-314448, SCAL-299746 +// ============================================================ +// NEW IN 26.8.0.cl / SDK 1.51.0 — WRITER REVIEW REQUIRED +// ============================================================ +// The following sections document new features shipping in ThoughtSpot Cloud 26.8.0.cl +// and Visual Embed SDK 1.51.0. Review all TODO comments before publishing. +// ============================================================ + +[#whats-new-26-8] +== What's new in 26.8.0.cl (SDK 1.51.0) + +// SOURCE: SCAL-310399, SCAL-312622 +=== [EA] Spotter Analysts + +// TODO: [WRITER] Confirm EA vs GA status for Analysts with Karamveer Singh / Agents Experience team (SCAL-310399). +// TODO: [WRITER] Verify these exact Action enum values exist in the published SDK 1.51.0 types.ts: +// Action.CreateAnalyst, Action.EditAnalyst, Action.CopyAnalyst, Action.ShareAnalyst, Action.DeleteAnalyst +// Check: https://github.com/thoughtspot/visual-embed-sdk/blob/main/src/types.ts +// TODO: [WRITER] Confirm whether showAnalysts defaults to false in TSE embed (Analysts disabled by default per SCAL-312622). +// TODO: [WRITER] Verify that spotterAnalystLabel and spotterAnalystsLabel are the confirmed property names +// in SpotterEmbedViewConfig. Source: src/embed/conversation.ts @version SDK: 1.51.0 + +ThoughtSpot Cloud 26.8.0.cl introduces *Spotter Analysts* [.version-badge.new]#New# — a feature that allows users to create and manage AI agents (Analysts) directly within the Spotter interface. Each Analyst is scoped to a data model and can be configured with custom instructions, personas, and conversation starters. + +In embedded applications, Analysts are *disabled by default*. You can enable and customize the Analysts experience using the configuration options described in this section. + +==== Enable the Analysts panel + +To show the Analysts panel in the embedded Spotter interface, set `showAnalysts` to `true` in `SpotterEmbedViewConfig`: + +[source,JavaScript] +---- +const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { + frameParams: { width: '100%', height: '100%' }, + worksheetId: '<%=datasourceGUID%>', + // Enable the Analysts panel (disabled by default in embedded mode) + // Requires SDK 1.51.0 | ThoughtSpot Cloud 26.8.0.cl + showAnalysts: true, +}); +spotterEmbed.render(); +---- + +==== Embed a single Analyst + +// TODO: [WRITER] Confirm the exact property name for embedding a single Analyst by GUID. +// Verify with the SDK team whether it is 'analystId', 'defaultAnalystId', or another name. +To embed a single, pre-selected Analyst, pass the Analyst GUID in the embed configuration: + +[source,JavaScript] +---- +const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { + frameParams: { width: '100%', height: '100%' }, + worksheetId: '<%=datasourceGUID%>', + showAnalysts: true, + // TODO: [WRITER] Replace with confirmed property name for single-Analyst embed. + // analystId: '<%=analystGUID%>', +}); +spotterEmbed.render(); +---- + +==== Disable Analyst actions + +Use `disabledActions`, `hiddenActions`, or `visibleActions` arrays to control which Analyst-related menu actions are available to users. The following action IDs apply to Analysts: + +// TODO: [WRITER] Verify ALL of these action names in the published types.ts for SDK 1.51.0. +// Source: https://github.com/thoughtspot/visual-embed-sdk/blob/main/src/types.ts + +[width="100%",cols="2,3"] +[options="header"] +|==== +|Action ID |Description +|`Action.CreateAnalyst` |Create a new Analyst +|`Action.EditAnalyst` |Edit an existing Analyst +|`Action.CopyAnalyst` |Duplicate an Analyst +|`Action.ShareAnalyst` |Share an Analyst with other users +|`Action.DeleteAnalyst` |Delete an Analyst +|==== + +Example — hide Create and Delete Analyst actions: + +[source,JavaScript] +---- +const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { + frameParams: { width: '100%', height: '100%' }, + worksheetId: '<%=datasourceGUID%>', + showAnalysts: true, + // Hide specific Analyst menu actions from all users + // Requires SDK 1.51.0 | ThoughtSpot Cloud 26.8.0.cl + hiddenActions: [ + Action.CreateAnalyst, + Action.DeleteAnalyst, + ], +}); +spotterEmbed.render(); +---- + +==== Customize Analysts label strings + +// SOURCE: src/embed/conversation.ts @version SDK: 1.51.0 | ThoughtSpot: 26.8.0.cl (SCAL-312622) +Use `spotterAnalystLabel` and `spotterAnalystsLabel` to replace the default "Analyst" / "Analysts" label text in the Spotter interface with custom terminology suited to your application: + +[source,JavaScript] +---- +const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { + frameParams: { width: '100%', height: '100%' }, + worksheetId: '<%=datasourceGUID%>', + showAnalysts: true, + // Custom label for a single Analyst (default: "Analyst") + // Requires SDK 1.51.0 | ThoughtSpot Cloud 26.8.0.cl + spotterAnalystLabel: 'Assistant', + // Custom label for the Analysts section heading (default: "Analysts") + spotterAnalystsLabel: 'Assistants', +}); +spotterEmbed.render(); +---- + +// SOURCE: SCAL-293483, SCAL-314448 +=== Spotter onboarding starter prompts + +// TODO: [WRITER] Confirm exact EA/GA status for Spotter onboarding with the Agents Experience team (SCAL-293483). +// TODO: [WRITER] Verify that enableStarterPrompts is the correct property name and that the default is false. +// Source: src/embed/conversation.ts @version SDK: 1.51.0 | ThoughtSpot: 26.8.0.cl + +ThoughtSpot Cloud 26.8.0.cl adds a Spotter *onboarding* experience [.version-badge.new]#New# that displays starter prompts to guide new users when they first open an embedded Spotter session. Starter prompts are hidden by default in embedded mode. + +To enable starter prompts, set `enableStarterPrompts` to `true`: + +// SOURCE: src/embed/conversation.ts confirmed property @version SDK: 1.51.0 +[source,JavaScript] +---- +const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { + frameParams: { width: '100%', height: '100%' }, + worksheetId: '<%=datasourceGUID%>', + // Show onboarding starter prompts to new users (default: false) + // Requires SDK 1.51.0 | ThoughtSpot Cloud 26.8.0.cl + enableStarterPrompts: true, +}); +spotterEmbed.render(); +---- + +// SOURCE: SCAL-299746, PR https://github.com/thoughtspot/visual-embed-sdk/pull/450 +=== New Action IDs for Spotter chat controls + +// TODO: [WRITER] Verify these three Action enum values are present in the published SDK 1.51.0 types.ts. +// PR reference: https://github.com/thoughtspot/visual-embed-sdk/pull/450 +// Previous workaround (CSS selectors) documented in the MCP connectors section below is now superseded. +Visual Embed SDK 1.51.0 adds three new `Action` enum values to control Spotter chat interface elements [.version-badge.new]#New#: + +[width="100%",cols="2,3"] +[options="header"] +|==== +|Action ID |Controls +|`Action.SpotterChatConnectors` |The MCP Connectors menu in the Spotter prompt panel +|`Action.SpotterChatConnectorResources` |The *+* (Add resources) icon in the Spotter prompt panel +|`Action.SpotterChatModeSwitcher` |The mode switcher control in the Spotter chat interface +|==== + +Use these action IDs with `hiddenActions` or `disabledActions` to control visibility of these interface elements without requiring CSS workarounds. + +Example — hide the MCP Connectors menu and resource icon: + +[source,JavaScript] +---- +import { + SpotterEmbed, + Action, + AuthType, + init, +} from '@thoughtspot/visual-embed-sdk'; + +init({ + thoughtSpotHost: 'https://your-thoughtspot-host', + authType: AuthType.TrustedAuthTokenCookieless, + getAuthToken: () => fetch('/api/token').then(r => r.json()).then(d => d.token), +}); + +const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { + frameParams: { width: '100%', height: '100%' }, + worksheetId: '<%=datasourceGUID%>', + updatedSpotterChatPrompt: true, + // Hide MCP connector controls using Action IDs (SDK 1.51.0+) + // Replaces CSS-selector workaround documented in earlier SDK versions. + hiddenActions: [ + Action.SpotterChatConnectors, + Action.SpotterChatConnectorResources, + ], +}); +spotterEmbed.render(); +---- + +[NOTE] +==== +Prior to SDK 1.51.0, hiding the MCP Connectors menu and the *+* icon required CSS selector workarounds. The `Action.SpotterChatConnectors` and `Action.SpotterChatConnectorResources` action IDs introduced in SDK 1.51.0 are the recommended approach. The CSS workaround documented in the xref:embed-spotter.adoc#mcp-connectors[MCP connectors] section remains functional but is no longer the preferred method. +==== + +// ============================================================ +// END OF NEW 26.8.0.cl CONTENT +// ============================================================ + == Before you begin To embed Spotter, you need the following access and setup: @@ -271,7 +470,7 @@ const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { 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] ==== 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. @@ -282,7 +481,12 @@ If the new prompt interface in Spotter 3 is enabled, the Spotter page displays t 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: SCAL-299746, PR https://github.com/thoughtspot/visual-embed-sdk/pull/450 +// TODO: [WRITER] Update the NOTE below once SDK 1.51.0 is confirmed published — +// the Action ID approach is now the recommended method; the CSS workaround is a fallback only. +In Visual Embed SDK 1.51.0 and later, use `Action.SpotterChatConnectors` and `Action.SpotterChatConnectorResources` to hide these elements. See xref:embed-spotter.adoc#whats-new-26-8[What's new in 26.8.0.cl] for details and a code example. + +For earlier SDK versions, you can use CSS selectors as a workaround: [source,JavaScript] ---- diff --git a/modules/ROOT/pages/embed-spotterViz.adoc b/modules/ROOT/pages/embed-spotterViz.adoc index 9c74008b6..88bd82873 100644 --- a/modules/ROOT/pages/embed-spotterViz.adoc +++ b/modules/ROOT/pages/embed-spotterViz.adoc @@ -6,14 +6,22 @@ :page-pageid: spotterViz-agent :page-description: Customize the SpotterViz panel in embedded Liveboards using the Visual Embed SDK. +// SOURCE: src/embed/spotter-viz-utils.ts @version SDK: 1.51.0 | ThoughtSpot Cloud: 26.8.0.cl +// SOURCE: SCAL-309017, SCAL-312622 +// TODO: [WRITER] Confirm whether SpotterViz Insight Tiles (SCAL-309017) are GA or Early Access in 26.8.0.cl. The Jira status is Closed but EA vs GA status was not confirmed at authoring time. Add the appropriate badge ([earlyAccess eaBackground]#Early Access# or remove the EA label) after confirming with the product team. +// TODO: [WRITER] Add a screenshot of the SpotterViz loading state UI (loaderHeadline + loaderTips in action) once available from the design or product team. +// TODO: [WRITER] Confirm with the SpotterViz team whether there is an enforced or recommended maximum number of entries in the `loaderTips` array. +// TODO: [WRITER] Confirm the badge status for the overall SpotterViz feature in 26.8.0.cl — update the [earlyAccess eaBackground]#Early Access# badge to GA if the feature is fully GA for embedded use. + [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. +The SpotterViz panel is supported in Liveboards embedded using `LiveboardEmbed` or `AppEmbed` components. 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] ==== * SpotterViz is an early access feature and is disabled by default on ThoughtSpot instances. To enable this feature on your instance, contact ThoughtSpot Support. -* The SpotterViz panel in Liveboard embedding is supported in Visual Embed SDK v1.50.0 and ThoughtSpot instances with 26.7.0.cl or later versions only. +* The SpotterViz panel in Liveboard embedding is supported in Visual Embed SDK v1.50.0 and later, and ThoughtSpot instances with 26.7.0.cl or later versions. +* The loading state customization properties (`loaderHeadline`, `loaderTips`) and Insight Tiles support require Visual Embed SDK v1.51.0 and ThoughtSpot Cloud 26.8.0.cl or later. ==== == Before you begin diff --git a/modules/ROOT/pages/full-app-customize.adoc b/modules/ROOT/pages/full-app-customize.adoc index b4e60b77e..4baddff9f 100644 --- a/modules/ROOT/pages/full-app-customize.adoc +++ b/modules/ROOT/pages/full-app-customize.adoc @@ -8,9 +8,18 @@ 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. +// SOURCE: SCAL-312731 +// TODO: [WRITER] Confirm the exact release in which V1 and V2 will be fully REMOVED +// (that is, not just deprecated but unsupported) with the product team. +// Update "a future release" with the specific version once known. +// TODO: [WRITER] Verify with the SDK team whether existing embeds that omit +// `discoveryExperience` automatically fall back to V3 from 26.8.0.cl, +// or whether explicit SDK configuration is required. + [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. +*Deprecation notice* [.version-badge.deprecated]#Deprecated# ThoughtSpot Cloud 26.8.0.cl + +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. V1 and V2 configuration parameters will be removed in a future release. ThoughtSpot recommends migrating to the V3 experience now. See xref:full-app-customize.adoc#_upgrade_to_the_v3_experience[Upgrade to the V3 experience]. ==== == UI experience modes diff --git a/modules/ROOT/pages/input-tables-api.adoc b/modules/ROOT/pages/input-tables-api.adoc new file mode 100644 index 000000000..12fe8437b --- /dev/null +++ b/modules/ROOT/pages/input-tables-api.adoc @@ -0,0 +1,203 @@ += Input Tables API reference +:toc: true +:toclevels: 2 + +:page-title: Input Tables API +:page-pageid: input-tables-api +:page-description: Use the Input Tables REST API v2.0 endpoints to create, update, and delete input table records in ThoughtSpot programmatically. +:keywords: input tables, REST API, create input table, update input table, delete input table, writable tables +:product-version: 26.8.0.cl +:jira-ref: SCAL-319440 + +// SOURCE: SCAL-319440 | ThoughtSpot Cloud 26.8.0.cl +// TODO: [WRITER] Confirm the Jira key for the Input Tables REST API feature — SCAL-319440 is the +// best match found at time of authoring. Verify with the Data platform / DM team. +// TODO: [WRITER] Confirm whether Input Tables require a specific license or feature flag to be +// enabled on the ThoughtSpot instance before these APIs are available. +// TODO: [WRITER] Confirm whether `input_table_identifier` accepts both the GUID and the table +// name, or only one of these. Verify with the platform team. +// TODO: [WRITER] Confirm the required privilege name for input table write operations. +// "Can manage data" is assumed — verify with the access control team. +// TODO: [WRITER] Add a conceptual overview link once an Input Tables concept page exists. +// TODO: [WRITER] Request confirmed example payloads from the Data platform team to replace +// the illustrative examples in this page before publishing. + +ThoughtSpot introduces REST API v2.0 endpoints for managing input table records +programmatically. Input tables are writable tables in ThoughtSpot that allow you to push +data directly into ThoughtSpot without an external data pipeline. Use these APIs to create +new input tables, insert or update records, and delete records at scale. + + +== Supported operations + +* <> — `POST /api/rest/2.0/input-tables/create` +* <> — `POST /api/rest/2.0/input-tables/{input_table_identifier}/update` +* <> — `POST /api/rest/2.0/input-tables/{input_table_identifier}/delete` + +=== Required permissions + +// TODO: [WRITER] Confirm the exact privilege required. "Can manage data" is assumed. +To use Input Tables API endpoints, `DATAMANAGEMENT` (*Can manage data*) or `ADMINISTRATION` (*Can administer ThoughtSpot*) privilege is required. If Role-Based Access Control (RBAC) is enabled on your ThoughtSpot instance, the `CAN_MANAGE_INPUT_TABLES` (*Can manage input tables*) privilege is required. + +// ───────────────────────────────────────────────────────────────────────────────────────── +[#create-input-table] +== Create an input table + +Creates an input table and links it to a ThoughtSpot model (worksheet). An input table is a user-editable table stored in the model's external Cloud Data Warehouse (CDW) connection. It lets analysts enter or import data directly from the ThoughtSpot UI without requiring access to the underlying warehouse. + +=== Resource URL + +---- +POST /api/rest/2.0/input-tables/create +---- + +=== Request parameters + +[cols="1,1,1,3", options="header"] +|=== +|Parameter |Type |Required |Description + +|`table_name` +|string +|Yes +|Name of the input table to create. Must be unique within the Org. + +|`table_definition` +|array of objects +|Yes +a|Describes the table schema. Each object requires: + + +* `referenced_columns` - List of column GUIDs from the linked model to include as read-only reference columns in the input table. These columns anchor the input data to existing model dimensions. + +* `name` (string) — Column display name. + +* `data_type` (string) — Warehouse data type. For example, `VARCHAR`, `INT64`, `DATE`, `BOOL`. + +* `type` (string) — Semantic role of the column: `ATTRIBUTE` for dimension columns or `MEASURE` for numeric columns. + + +|`model_identifier` +|string +|Yes +|GUID or name of the Model to link the input table to. + +|=== + +=== Example request + +[source,cURL] +---- +curl -X POST \ + 'https://{ThoughtSpot-Host}/api/rest/2.0/input-tables/create' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + -H 'Content-Type: application/json' \ + -d '{ + "table_name": "table_name4", + "model_identifier": "model_identifier4", + "table_definition": { + "new_columns": [ + { + "name": "name2", + "data_type": "data_type0", + "type": "ATTRIBUTE" + } + ], + "referenced_columns": [ + "referenced_columns9" + ] + } +}' +---- + +=== Example response + +[source,JSON] +---- +{ + "input_table_identifier": "f47ac10b-58cc-4372-a567-0e02b2c3d479" +} +---- + + +// ───────────────────────────────────────────────────────────────────────────────────────── +[#update-input-table] +== Update records in an input table + +Writes rows of data into an existing input table. The supplied rows replace the current contents of the table. Partial updates to individual rows are not supported; re-submit all rows on every write. + +=== Resource URL + +---- +POST /api/rest/2.0/input-tables/{input_table_identifier}/update +---- +=== Request parameters + +[cols="1,1,1,3", options="header"] +|=== +|Parameter |Type |Required |Description +|`input_table_identifier` |string |Yes |GUID or name of the input table to update. Pass the input table GUID as the path parameter in the API request. +|`rows` |array of objects |Yes |Rows to insert or update. Each object maps column name to value. Column names must match the table schema. +|=== + +=== Example request + +[source,cURL] +---- +curl -X POST \ + 'https://{ThoughtSpot-Host}/api/rest/2.0/input-tables/f47ac10b-58cc-4372-a567-0e02b2c3d479/update' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + -H 'Content-Type: application/json' \ + -d '{ + "columns": ["region", "target_revenue", "effective_date"], + "rows": [ + ["West", "1500000", "2025-01-01"], + ["East", "2000000", "2025-01-01"] + ] + }' +---- + +=== Example response + +[source,JSON] +---- +{ + "rows_loaded": 2 +} +---- + +// ───────────────────────────────────────────────────────────────────────────────────────── +[#delete-input-table] +== Delete an input table + +This operation unlinks the input table from its Model, removes it from the connection metadata, and drops the physical table from the Cloud Data Warehouse. + +Deleting an input table does not delete the linked model. However, any Answers or Liveboards that reference columns from the deleted input table will lose access to that data and may return errors until the affected visualizations are updated. + +=== Resource URL + +---- +POST /api/rest/2.0/input-tables/{input_table_identifier}/delete +---- + +=== Request parameters + +[cols="1,1,1,3", options="header"] +|=== +|Parameter |Type |Required |Description +|`input_table_identifier` |string |Yes |GUID or name of the input table. Pass the input table GUID as the path parameter in the API request. +|=== + +=== Example request + +[source,cURL] +---- +curl -X POST \ + 'https://{ThoughtSpot-Host}/api/rest/2.0/input-tables/f47ac10b-58cc-4372-a567-0e02b2c3d479/delete' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + +---- + +=== Example response +A successful deletion returns the 204 response code. + +== Additional resources + +* xref:rest-api-v2-reference.adoc[REST API v2.0 reference] +* xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog] + 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/python-sdk.adoc b/modules/ROOT/pages/python-sdk.adoc new file mode 100644 index 000000000..d08e57eb9 --- /dev/null +++ b/modules/ROOT/pages/python-sdk.adoc @@ -0,0 +1,422 @@ += Python SDK for REST API v2.0 +:toc: true +:toclevels: 3 + +:page-title: Python SDK for REST API v2.0 +:page-pageid: python-sdk +:page-description: Use the ThoughtSpot Python SDK to integrate REST API v2.0 in Python applications. The SDK is an async-first, fully-typed client generated from the ThoughtSpot OpenAPI specification. + +// SOURCE: SCAL-323283, SCAL-216861 +// SOURCE: Python SDK Design Doc — https://docs.google.com/document/d/1AQBCymDS7xGHztMGNzyryjoKkb2em9vW11pTZfyztEA +// SOURCE: PyPI — https://pypi.org/project/thoughtspot-rest-api-sdk/ version 2.26.0b1 +// ⚠️ STATUS: BETA — Package is published as 2.26.0b1 (pre-release). +// Do NOT remove the BETA callout or the gate comments until Piyush Tayal confirms stable release. +// TODO: [WRITER] Confirm stable PyPI version number once SCAL-216861 exits Pending Verification. +// TODO: [WRITER] Confirm the GitHub repository URL for the Python SDK source (design doc references sdks/python/ in rest-api-sdk repo — verify if public). +// TODO: [WRITER] Confirm minimum Python version. Design doc states >= 3.9. PyPI page may differ — verify with Piyush Tayal. +// TODO: [WRITER] Add a link to the nav file once this page is added to the navigation. + +ThoughtSpot provides an official Python SDK for REST API v2.0 — an async-first, fully-typed client generated from the ThoughtSpot OpenAPI specification. The SDK wraps every REST API v2.0 endpoint into typed Python methods, supporting both synchronous and asynchronous invocation, transparent token refresh, automatic retries, server-sent event (SSE) streaming, file upload and download, and typed error handling. + +[IMPORTANT] +==== +// SOURCE: PyPI listing — version 2.26.0b1 +// TODO: [WRITER] Remove this callout once the stable version is published and SCAL-216861 is confirmed shipped. +The Python SDK is currently available as a *beta pre-release* (`2.26.0b1`) on PyPI. The API surface and behavior may change before the stable release. Do not use this SDK in production without verifying the current stable version with your ThoughtSpot account team. +==== + +[NOTE] +==== +The Python SDK for REST API v2.0 is introduced in the ThoughtSpot Cloud `jul.26.mt` release. For the latest REST API information, see xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. +==== + +== Prerequisites + +// SOURCE: Design doc Section 3.2 Non-Functional Requirements — N8: "Broad Python support — >= 3.9" +// TODO: [WRITER] Cross-check minimum Python version against the published PyPI package metadata before publishing. + +* Python 3.9 or later +* A ThoughtSpot Cloud instance with REST API v2.0 enabled +* A valid ThoughtSpot user account with API access +* `pip` package manager + +== Install the SDK + +// SOURCE: PyPI — https://pypi.org/project/thoughtspot-rest-api-sdk/ +// Package name confirmed: thoughtspot-rest-api-sdk +// Current version: 2.26.0b1 (beta) + +Install the latest release: + +[source,bash] +---- +pip install thoughtspot-rest-api-sdk +---- + +To install the current beta pre-release explicitly: + +[source,bash] +---- +pip install thoughtspot-rest-api-sdk==2.26.0b1 +---- + +To install the latest pre-release version: + +[source,bash] +---- +pip install --pre thoughtspot-rest-api-sdk +---- + +== Authentication + +// SOURCE: Design doc Section 5.1 Master capability matrix — C11, C12, C13 +// SOURCE: Design doc Section 3.1 Functional Requirements — F3 +// The SDK supports three authentication modes — all confirmed from the design doc. + +The Python SDK supports three authentication modes, all configured through the `Configuration` object: + +[width="100%",cols="1,2,3"] +[options="header"] +|==== +|Mode |Configuration |Description +|Static bearer token |`Configuration(access_token="")` |Pass a pre-obtained bearer token directly. The SDK injects it into every request. Suitable for short-lived scripts. +|Token callable |`Configuration(token_provider=my_callable)` |Supply a callable (sync or async) that returns a fresh token. The SDK calls it when the current token expires. Suitable for long-running applications. +|Built-in token provider |`ThoughtSpotTokenProvider(...)` |The SDK mints and transparently refreshes a token from `/api/rest/2.0/auth/token/full`. The recommended approach for production use. +|==== + +=== Option 1 — Static bearer token + +// SOURCE: Design doc Section 5.1, C11 +// Obtain a bearer token first using the ThoughtSpot REST API authentication endpoint. +[source,python] +---- +import asyncio +from thoughtspot_rest_api_sdk import Configuration, ThoughtSpotRestApi + +configuration = Configuration( + host="https://your-instance.thoughtspot.cloud", # Replace with your ThoughtSpot host + access_token="your-bearer-token", # Replace with a valid bearer token +) + +async def main(): + async with ThoughtSpotRestApi(configuration=configuration) as client: + # Make API calls here + users = await client.search_users(body={}) + print(users) + +asyncio.run(main()) +---- + +=== Option 2 — Built-in token provider (recommended for production) + +// SOURCE: Design doc Section 5.2 — ThoughtSpotTokenProvider +// The built-in provider mints tokens via /api/rest/2.0/auth/token/full and refreshes transparently. +// TODO: [WRITER] Confirm exact ThoughtSpotTokenProvider constructor parameters +// and the module path from the SDK team before publishing. +[source,python] +---- +import asyncio +from thoughtspot_rest_api_sdk import Configuration, ThoughtSpotRestApi +from thoughtspot_rest_api_sdk import ThoughtSpotTokenProvider + +# TODO: [WRITER] Confirm ThoughtSpotTokenProvider constructor parameters with the SDK team. +token_provider = ThoughtSpotTokenProvider( + host="https://your-instance.thoughtspot.cloud", + username="your-username", + password="your-password", # Or use secret_key for trusted auth + validity_time_in_sec=3600, +) + +configuration = Configuration( + host="https://your-instance.thoughtspot.cloud", + token_provider=token_provider, +) + +async def main(): + async with ThoughtSpotRestApi(configuration=configuration) as client: + users = await client.search_users(body={}) + print(users) + +asyncio.run(main()) +---- + +=== Synchronous usage + +// SOURCE: Design doc Section 5.1, C9 — "Synchronous methods: client.search_users_sync(req)" +// Every async method has a _sync variant. No separate library or bridge is required. + +Every method has a `_sync` variant for use in synchronous code. Add `_sync` to the method name: + +[source,python] +---- +# SOURCE: Design doc Section 5.1, C9 +from thoughtspot_rest_api_sdk import Configuration, ThoughtSpotRestApi +from thoughtspot_rest_api_sdk import ThoughtSpotTokenProvider + +token_provider = ThoughtSpotTokenProvider( + host="https://your-instance.thoughtspot.cloud", + username="your-username", + password="your-password", +) + +configuration = Configuration( + host="https://your-instance.thoughtspot.cloud", + token_provider=token_provider, +) + +client = ThoughtSpotRestApi(configuration=configuration) +# Use _sync suffix for synchronous calls — no asyncio.run() needed +users = client.search_users_sync(body={}) +print(users) +---- + +== Client patterns + +// SOURCE: Design doc Section 4.1 Runtime object model, Section 5.1 + +=== Mega-facade — all endpoints on one class + +// SOURCE: Design doc Section 5.1, C1 — "Mega-facade: ThoughtSpotRestApi — a single class exposing every endpoint as a method" + +`ThoughtSpotRestApi` exposes every REST API v2.0 endpoint as a typed method on a single class: + +[source,python] +---- +async with ThoughtSpotRestApi(configuration=configuration) as client: + # Users + users = await client.search_users(body={"record_size": 10}) + # Metadata + liveboards = await client.search_metadata(body={"metadata": [{"type": "LIVEBOARD"}]}) + # TML export + tml = await client.export_metadata_tml(body={"metadata": [{"identifier": "lb-guid-here"}]}) +---- + +=== Per-tag classes — focused endpoint groups + +// SOURCE: Design doc Section 5.1, C2 — "29 per-tag classes" +// SOURCE: Design doc — confirmed: UsersApi, MetadataApi, AuthenticationApi +// TODO: [WRITER] Confirm the full list of 29 per-tag class names from the SDK team. + +Use per-tag classes to work with a specific endpoint group: + +[source,python] +---- +# TODO: [WRITER] Confirm full import paths for per-tag classes with the SDK team. +from thoughtspot_rest_api_sdk import ApiClient, Configuration +from thoughtspot_rest_api_sdk.api.users_api import UsersApi +from thoughtspot_rest_api_sdk.api.metadata_api import MetadataApi + +async with ApiClient(configuration=configuration) as api_client: + users_api = UsersApi(api_client) + metadata_api = MetadataApi(api_client) + + users = await users_api.search_users(body={}) + liveboards = await metadata_api.search_metadata( + body={"metadata": [{"type": "LIVEBOARD"}]} + ) +---- + +=== Shared connection pool + +// SOURCE: Design doc Section 5.1, C6 + +[source,python] +---- +from thoughtspot_rest_api_sdk import ApiClient, Configuration +from thoughtspot_rest_api_sdk.api.users_api import UsersApi +from thoughtspot_rest_api_sdk.api.metadata_api import MetadataApi + +async with ApiClient(configuration=configuration) as api_client: + users_api = UsersApi(api_client) # Shares the same connection pool + metadata_api = MetadataApi(api_client) # Shares the same connection pool +---- + +== Configure timeouts and retries + +// SOURCE: Design doc Section 5.1, C15 (timeouts), C20 (retries) +// SOURCE: Design doc F4 (timeout), F5 (retries with exponential backoff) + +=== Timeouts + +// TODO: [WRITER] Confirm the exact Configuration parameter names for timeouts +// (connect_timeout, read_timeout vs a single timeout param) with the SDK team. +[source,python] +---- +configuration = Configuration( + host="https://your-instance.thoughtspot.cloud", + access_token="your-bearer-token", + timeout=30.0, # Default timeout in seconds for all requests +) +---- + +Per-call timeout override: + +// SOURCE: Design doc Section 5.1, C16 — "per-call timeout override" +// TODO: [WRITER] Confirm per-call timeout override syntax from the SDK team. +[source,python] +---- +result = await client.search_users(body={}, timeout=60.0) +---- + +=== Automatic retries + +// SOURCE: Design doc F5 — "opt-in automatic retries with exponential backoff and jitter for transient failures (network errors, 429/5xx)" +// TODO: [WRITER] Confirm the exact Configuration parameter name for retries +// and the max_retries default value with the SDK team. +[source,python] +---- +configuration = Configuration( + host="https://your-instance.thoughtspot.cloud", + access_token="your-bearer-token", + max_retries=3, # Retry up to 3 times on network errors or 429/5xx responses +) +---- + +== Error handling + +// SOURCE: Design doc F8 — "Raise typed exceptions per HTTP status, all derived from a common base, +// exposing status/reason/body/data/headers" +// TODO: [WRITER] Confirm the exact exception class names (e.g., ApiException, UnauthorizedException) +// and the import path from the SDK team before publishing. + +[source,python] +---- +from thoughtspot_rest_api_sdk.exceptions import ApiException # TODO: confirm import path + +try: + users = await client.search_users(body={}) +except ApiException as e: + print(f"HTTP {e.status}: {e.reason}") + print(f"Response body: {e.body}") + print(f"Response headers: {e.headers}") +---- + +== SSE streaming + +// SOURCE: Design doc F6 — "Stream server-sent events for flagged endpoints as an async generator of decoded event dicts" +// SOURCE: Design doc — "x-streaming vendor extension marks endpoints for SSE; drives generation of a *_stream method" +// TODO: [WRITER] Confirm which specific REST API v2.0 endpoints are SSE-enabled +// (marked with x-streaming in the spec) and replace the placeholder example +// with real endpoint names. Design doc confirms the _stream naming convention +// but the specific endpoint list was not available at time of authoring. + +For endpoints that support server-sent events (SSE), the SDK generates a `_stream` variant that returns an async generator: + +[source,python] +---- +# TODO: [WRITER] Replace with a confirmed SSE endpoint name from the SDK team. +async for event in client.some_streaming_endpoint_stream(body={}): + print(event) # Each event is a decoded dict +---- + +== File upload and download + +// SOURCE: Design doc F7 — "Support file upload (multipart) and binary download for the relevant endpoints" +// TODO: [WRITER] Confirm which endpoints use multipart upload vs JSON body. + +[source,python] +---- +# Example: export a Liveboard as PDF (binary download) +# TODO: [WRITER] Confirm the exact method name and body parameters with the SDK team. +pdf_bytes = await client.export_liveboard_report( + body={ + "metadata": [{"identifier": "your-liveboard-guid"}], + "file_format": "PDF", + } +) +with open("liveboard.pdf", "wb") as f: + f.write(pdf_bytes) +---- + +== TLS and proxy configuration + +// SOURCE: Design doc F9 — "Support custom TLS (custom CA, mutual-TLS client cert, verification toggle) and HTTP proxy" +// TODO: [WRITER] Confirm the exact Configuration parameter names for TLS +// (ssl_ca_cert, cert_file, verify_ssl, proxy) with the SDK team. + +[source,python] +---- +configuration = Configuration( + host="https://your-instance.thoughtspot.cloud", + access_token="your-bearer-token", + verify_ssl=True, # Set to False only for local dev/testing + ssl_ca_cert="/path/to/ca.pem", # Custom CA certificate (optional) + proxy="http://proxy.example.com:8080", # HTTP proxy (optional) +) +---- + +== Runtime reconfiguration + +// SOURCE: Design doc Section 5.1, C7 — "Runtime reconfiguration: client.apply_configuration(new_cfg)" + +Update the client configuration at runtime without creating a new client instance: + +[source,python] +---- +new_cfg = Configuration( + host="https://your-instance.thoughtspot.cloud", + access_token="refreshed-bearer-token", +) +client.apply_configuration(new_cfg) +---- + +== Available endpoint groups + +// SOURCE: Design doc Section 2 — "500+ models, ~29 endpoint groups" +// SOURCE: Design doc Section 5.1, C2 — "29 per-tag classes" +// TODO: [WRITER] Expand this table with all 29 confirmed per-tag class names +// and representative methods from Piyush Tayal / SDK team before publishing. +// The design doc confirms the total count (29) but the full list was not +// available in the excerpted sections at time of authoring. + +The Python SDK exposes all REST API v2.0 endpoints through approximately 29 per-tag API classes. The following groups are confirmed from the design document: + +[width="100%",cols="2,3,2"] +[options="header"] +|==== +|Class |Description |Example methods +|`UsersApi` |User management — create, update, delete, search |`search_users`, `create_user`, `delete_users` +|`MetadataApi` |Metadata object management — Liveboards, Answers, Models |`search_metadata`, `export_metadata_tml`, `import_metadata_tml` +|`AuthenticationApi` |Token acquisition and session management |`get_full_access_token`, `get_object_access_token` +|`ThoughtSpotRestApi` |Mega-facade — all endpoints on one class |All methods from all groups +|_(additional groups)_ |_TODO: [WRITER] Confirm and add all remaining per-tag class names from the SDK team_ | +|==== + +== Supported features + +// SOURCE: Design doc Section 5.1 Master capability matrix — all entries confirmed + +[width="100%",cols="3,1"] +[options="header"] +|==== +|Feature |Status +|Async-first with `await` |✅ +|Synchronous `_sync` variants for every method |✅ +|Static bearer token authentication |✅ +|Token callable — supply your own refresh function |✅ +|Built-in token provider with automatic refresh (`ThoughtSpotTokenProvider`) |✅ +|Configurable request timeouts (client-level and per-call) |✅ +|Automatic retries with exponential backoff and jitter (429/5xx) |✅ +|SSE streaming via `_stream` method variants |✅ +|File upload (multipart) |✅ +|Binary file download |✅ +|Typed exceptions with `status`, `reason`, `body`, `headers` |✅ +|Custom TLS (CA cert, mutual-TLS, verification toggle) |✅ +|HTTP proxy support |✅ +|Runtime reconfiguration (`apply_configuration`) |✅ +|Shared connection pool across per-tag classes |✅ +|Custom default headers + per-call header overrides |✅ +|Fully typed with `py.typed` marker (mypy/IDE-friendly) |✅ +|Lazy imports (fast cold-start) |✅ +|Python 3.9+ |✅ +|==== + +== Related resources + +* link:https://pypi.org/project/thoughtspot-rest-api-sdk/[thoughtspot-rest-api-sdk on PyPI, window=_blank] +* xref:rest-api-v2-reference.adoc[REST API v2.0 reference] +* xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog] +* xref:rest-api-sdk-libraries.adoc[SDK libraries] +* xref:authentication.adoc[Authentication] +// TODO: [WRITER] Add a link to the Python SDK GitHub repository once confirmed as public. +// TODO: [WRITER] Add a link to the SDK API reference documentation once available. diff --git a/modules/ROOT/pages/rest-api-sdk-libraries.adoc b/modules/ROOT/pages/rest-api-sdk-libraries.adoc index 0db64352d..5b103a7a1 100644 --- a/modules/ROOT/pages/rest-api-sdk-libraries.adoc +++ b/modules/ROOT/pages/rest-api-sdk-libraries.adoc @@ -1,45 +1,67 @@ -= 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. +ThoughtSpot provides official SDK libraries for integrating REST API v2.0 into your applications. -Currently, the REST API client libraries are available for xref:rest-api-sdk-typescript.adoc[TypeScript] and xref:rest-api-java-sdk.adoc[Java]. These SDKs provide language-specific client libraries to call APIs from client applications. +== Python SDK for REST API v2.0 [.version-badge.new]#New in jul.26.mt# -== Community SDKs -You can use the following open-source, community-supported SDKs. +// SOURCE: SCAL-323283, SCAL-216861 +// SOURCE: PyPI — https://pypi.org/project/thoughtspot-rest-api-sdk/ version 2.26.0b1 +// SOURCE: Python SDK Design Doc — https://docs.google.com/document/d/1AQBCymDS7xGHztMGNzyryjoKkb2em9vW11pTZfyztEA +// ⚠️ GATE — Do not publish until SCAL-216861 is confirmed shipped and stable version is on PyPI. +// TODO: [WRITER] Remove BETA callout and gate comment once stable release is confirmed by Piyush Tayal. +// TODO: [WRITER] Confirm the GitHub repository URL for the Python SDK once available. + +ThoughtSpot provides an official Python SDK for REST API v2.0, enabling Python developers to integrate ThoughtSpot analytics, data operations, and AI workflows directly into Python applications. The SDK is an async-first, fully-typed client generated from the ThoughtSpot OpenAPI specification. [IMPORTANT] ==== -* ThoughtSpot reserves the right to publish its own SDKs to replace or improve upon these community-based SDKs based on customer feedback. -* These community SDKs may not be reviewed or updated periodically for accuracy or completeness, and are not included in ThoughtSpot product support. -* ThoughtSpot-supported SDKs may not be backward-compatible with these community-based SDKs. +// SOURCE: PyPI — version 2.26.0b1 +// TODO: [WRITER] Remove this callout once the stable version is confirmed shipped. +The Python SDK is currently available as a *beta pre-release* (`2.26.0b1`) on PyPI. Confirm the current stable version before using in production. ==== +* *Package name:* `thoughtspot-rest-api-sdk` +* *PyPI:* link:https://pypi.org/project/thoughtspot-rest-api-sdk/[pypi.org/project/thoughtspot-rest-api-sdk, window=_blank] +* *Python:* 3.9 or later +// TODO: [WRITER] Confirm minimum Python version — design doc says 3.9, verify against PyPI metadata. -[width="100%" cols="2,4"] -[options='header'] -|==== -|SDK/ library|Purpose -|link:https://github.com/thoughtspot/thoughtspot_rest_api_python[thoughtspot_rest_api_python, window=_blank] |Python SDK for working with ThoughtSpot's REST APIs + +Install the SDK: -**Language**: Python + +[source,bash] +---- +pip install thoughtspot-rest-api-sdk +---- -|link:https://github.com/thoughtspot/thoughtspot_tml[thoughtspot_tml, window=_blank]| Package for working with ThoughtSpot Modeling Language (TML) files programmatically + +For the full SDK reference, authentication setup, and code examples, see xref:python-sdk.adoc[Python SDK for REST API v2.0]. -**Language**: Python + -|==== +== TypeScript SDK +ThoughtSpot provides an official TypeScript SDK for REST API v2.0, generated from the ThoughtSpot OpenAPI specification. -== Additional resources +// TODO: [WRITER] Confirm the TypeScript SDK section is complete and up to date. +// Add npm package name, install command, and link to TypeScript SDK docs page if available. + +== Java SDK + +ThoughtSpot provides an official Java SDK for REST API v2.0, generated from the ThoughtSpot OpenAPI specification. + +// TODO: [WRITER] Confirm the Java SDK section is complete and up to date. +// Add Maven/Gradle dependency and link to Java SDK docs page if available. -For more information about REST APIs, use the following resources: +== Community SDKs + +The following community-maintained SDK libraries are available for ThoughtSpot REST API integration. These SDKs are not officially supported by ThoughtSpot. + +// TODO: [WRITER] Add confirmed community SDK entries here. + +== Additional 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]. +* xref:rest-api-v2-reference.adoc[REST API v2.0 reference] +* xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog] +* xref:python-sdk.adoc[Python SDK for REST API v2.0] diff --git a/modules/ROOT/pages/rest-api-v2-reference.adoc b/modules/ROOT/pages/rest-api-v2-reference.adoc index dfaf6a4ac..8f8a7f0b9 100644 --- a/modules/ROOT/pages/rest-api-v2-reference.adoc +++ b/modules/ROOT/pages/rest-api-v2-reference.adoc @@ -106,9 +106,24 @@ 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. +// SOURCE: SCAL-307522 +// TODO: [WRITER] Confirm endpoint path, required request body fields, and privilege requirements with Balakrishna Moravineni / Agent Coaching team before publishing. +|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. +// SOURCE: SCAL-307522 +// TODO: [WRITER] Confirm endpoint path, response schema, and privilege requirements with the Agent Coaching team before publishing. +|ThoughtSpot Cloud: __26.8.0.cl or later__ + +ThoughtSpot Software: __Not available__ a| +++Try it out+++ |===== -- + == Authentication [div boxAuto] @@ -583,6 +598,30 @@ ThoughtSpot Software: __9.0.1.sw or later__ a| |===== -- +== Input tables +[div boxAuto] +-- +[width="100%" cols="8,5,3"] +[options='header'] +|===== +|API endpoint| Release version | Playground link +a|`POST /api/rest/2.0/input-tables/create` + +Creates a new input table in ThoughtSpot. +|ThoughtSpot Cloud: __26.8.0.cl or later__ + +ThoughtSpot Software: __Not available__ a| +++Try it out+++ + +a|`POST /api/rest/2.0/input-tables/{input_table_identifier}/update` + +Writes rows of data into an existing input table. +|ThoughtSpot Cloud: __26.8.0.cl or later__ + +ThoughtSpot Software: __Not available__ a| +++Try it out+++ + +a|`POST /api/rest/2.0/input-tables/{input_table_identifier}/delete` + +Deletes an input table. +|ThoughtSpot Cloud: __26.8.0.cl or later__ + +ThoughtSpot Software: __Not available__ a| +++Try it out+++ +|===== +-- + == Jobs [div boxAuto] diff --git a/modules/ROOT/pages/rest-apiv2-changelog.adoc b/modules/ROOT/pages/rest-apiv2-changelog.adoc index 0cad327a6..e75df6e3e 100644 --- a/modules/ROOT/pages/rest-apiv2-changelog.adoc +++ b/modules/ROOT/pages/rest-apiv2-changelog.adoc @@ -8,6 +8,94 @@ This changelog lists the features and enhancements introduced in REST API v2.0. For information about new features and enhancements available for embedded analytics, see xref:whats-new.adoc[What's New]. +// ============================================================ +// SOURCE: SCAL-307283, SCAL-317357, SCAL-273333, SCAL-307522, SCAL-313088, SCAL-244749, SCAL-319440 +// TODO: [WRITER] Confirm the release month label. "August 2026" is inferred from the 26.8.0.cl version pattern. Verify with the release team before publishing. +// TODO: [WRITER] SCAL-307522 Spotter ST Memory Migration APIs — verify endpoint paths, request/response schemas, and privilege requirements with Balakrishna Moravineni / Agent Coaching team before publishing. +// TODO: [WRITER] SCAL-273333 — Confirm the exact REST API privilege enum string values for "Can Download Visuals" and "Can Download Detailed Data" with the access control / product team before publishing. +// TODO: [WRITER] SCAL-317357 — Confirm the exact API endpoint path for updating Collections obj_id. Path `POST /api/rest/2.0/metadata/identity/update` is inferred from the Jira description; verify with the platform team. +// TODO: [WRITER] SCAL-244749 — Confirm whether the schedule frequency deprecation affects REST API schedule endpoints directly, or only the UI. If the API is affected, add a deprecation callout to the schedules API reference page. +// TODO: [WRITER] SCAL-319440 — Confirm the correct Jira reference for Input Tables API with the Data Management / Embrace team. Confirm request body schemas and privilege requirements before publishing. +// ============================================================ + +== Version 26.8.0.cl, August 2026 + +=== TML import and export + +Personalized Views portability::: [earlyAccess eaBackground]#Early Access# + +// SOURCE: SCAL-307283 +Starting from 26.8.0.cl, Personalized Views support improved portability across ThoughtSpot environments: + +* A new `author` field is added to the Personalized View TML during export. This field is used to assign ownership during import. +* Personalized Views now carry an `obj_id` field for stable cross-environment object identity, consistent with other object types. +* Import operations apply smart merge logic: if a Personalized View with a matching `obj_id` already exists in the target environment, the import updates the existing view rather than creating a duplicate. ++ +// TODO: [WRITER] Confirm these exact TML field names (`owned_by`, `obj_id`) in the Personalized View TML schema with the TML or deployment team. Also confirm whether the merge-on-match behavior updates or skips the existing view. +For more information, see xref:tml.adoc#personalized-views-portability[Personalized Views portability in TML]. + +Collections `obj_id` support::: +// SOURCE: SCAL-317357 +The `obj_id` attribute is now supported for the *Collections* object type in TML import and export. This enables stable cross-environment identification for Collections, matching the behavior already available for Models, Liveboards, Answers, and other object types. ++ +To assign or update the `obj_id` for a Collections object, use the `POST /api/rest/2.0/metadata/identity/update` API endpoint. ++ +// TODO: [WRITER] Confirm: (1) `POST /api/rest/2.0/metadata/identity/update` is the correct endpoint. (2) Confirm that `COLLECTION` is the correct metadata type value. Verify with the platform team. + +=== Spotter AI APIs + +Spotter training memory APIs::: +// SOURCE: SCAL-307522 +// TODO: [WRITER] Verify endpoint paths, request/response schemas, and privilege requirements with Balakrishna Moravineni / Agent Coaching team before publishing. +ThoughtSpot 26.8.0.cl introduces two new REST API v2.0 endpoints for managing Spotter training memory programmatically: + +* `POST /api/rest/2.0/ai/memory/import` — Imports Spotter training memory entries in bulk. Use this endpoint to seed training data or migrate Spotter memory across environments. +* `POST /api/rest/2.0/ai/memory/export` — Exports all current Spotter training memory entries. Use this endpoint to back up training data or audit the current training state. + +Both endpoints require administrator privileges. ++ +// TODO: [WRITER] Confirm the exact privilege requirement (for example, `ADMINISTRATION` or `CAN_MANAGE_SPOTTER`) with the Agent Coaching team before publishing. + +=== Input Tables + +// SOURCE: SCAL-319440 +// TODO: [WRITER] Confirm the correct Jira reference for Input Tables API with the Data Management / Embrace team. +// TODO: [WRITER] Confirm request body schemas and privilege requirements for each endpoint before publishing. + +ThoughtSpot introduces three new REST API v2.0 endpoints for managing input tables programmatically. Input tables allow structured data to be written directly into ThoughtSpot for use in Worksheets and Liveboards. + +`POST /api/rest/2.0/input-tables/create`::: +Creates a new input table. Accepts the table name, column schema, and connection configuration in the request body. +// TODO: [WRITER] Confirm the exact request body schema with the Data Management / Embrace team. + +`POST /api/rest/2.0/input-tables/{input_table_identifier}/update`::: +Updates (upserts) rows in the specified input table. The `input_table_identifier` is the GUID of the target input table. + +`POST /api/rest/2.0/input-tables/{input_table_identifier}/delete`::: +Deletes rows from the specified input table matching the supplied filter criteria. +// TODO: [WRITER] Confirm whether this endpoint deletes individual rows (filter-based) or the entire table. Verify with engineering. + +=== Access control + +Granular download privileges::: +// SOURCE: SCAL-273333 +ThoughtSpot introduces two new granular download privileges that give administrators finer control over what users can export: + +* *Can Download Visuals* — Permits downloading chart and visualization images. +* *Can Download Detailed Data* — Permits downloading raw tabular data in CSV or XLSX format. ++ +// TODO: [WRITER] Confirm the exact REST API privilege enum string values for these two new privileges (e.g., `DOWNLOAD_VISUAL`, `DOWNLOAD_DETAILED_DATA`). Verify with the access control / product team before publishing. +// TODO: [WRITER] Confirm whether existing privilege assignments for the general download privilege are automatically migrated to the new granular privileges. Verify migration behavior with the engineering team. ++ +These privileges are configurable via the `POST /api/rest/2.0/roles/create` and `POST /api/rest/2.0/roles/update` API endpoints. + +=== Schedules + +every-N-minutes frequency deprecated::: +// SOURCE: SCAL-244749 +// TODO: [WRITER] Confirm the exact API field name (e.g., `frequency.type` = `EVERY_N_MINUTES`) in the schedule create/update REST API request body. Verify whether the API rejects this value in 26.8.0.cl or only warns. +The `every_n_minutes` schedule frequency option is deprecated in 26.8.0.cl. Schedules configured with this frequency will continue to run during the transition period; however, ThoughtSpot recommends updating existing schedules to supported frequency options (hourly, daily, weekly, or monthly). Support for the `every_n_minutes` frequency will be removed in a future release. + == Version 26.7.0.cl, July 2026 === Spotter AI APIs @@ -80,7 +168,6 @@ Uploads a custom font file to ThoughtSpot. * `POST /api/rest/2.0/customization/styles/fonts/search` + Returns custom fonts uploaded to the instance. -//Use the `include_font_assignments` parameter to include information about which visualization elements each font is assigned to. * `PUT /api/rest/2.0/customization/styles/fonts/{font_identifier}/update` + Updates the display name, weight, style, or color of an existing custom font. @@ -475,8 +562,6 @@ The variable API enhancements are listed in the following sections. For addition * The variable creation endpoint `/api/rest/2.0/template/variables/create` does not support assigning values to a variable. To assign values to a variable, use the `/api/rest/2.0/template/variables/update-values` endpoint. * The `sensitive` parameter is renamed as `is_sensitive`. -//* You can define the data type for variables using the `data_type`property. -//* You can now create formula variables. To create a formula variable, use define the variable type as `FORMULA_VARIABLE` variable type in your API request . ==== Variables update APIs [tag redBackground]#BREAKING CHANGE# @@ -522,9 +607,6 @@ Breaks down a user-submitted query into a series of analytical sub-questions usi * `POST /api/rest/2.0/ai/agent/converse/sse` + Allows sending a follow-up message or question to an ongoing conversation session and returns the AI agent's response, including answers, tokens, and visualization details. + -//* `POST /api/rest/2.0/ai/data-source-suggestions` + -//Returns a list of relevant data sources, such as Models, based on a query and thus helping users and agents choose the most appropriate data source for analytics. + - For more information, see xref:spotter-apis.adoc[Spotter AI APIs]. Email customization:: @@ -706,10 +788,6 @@ For information about how to install and use the SDK, see xref:rest-api-java-sdk === New API endpoints This version introduces the following endpoints: -//// -* `POST /api/rest/2.0/ai/analytical-questions` + -Allows using an existing ThoughtSpot Answer or Liveboard, and include content to improve query response. -//// * `POST /api/rest/2.0/metadata/update-obj-id` + Update object IDs for given metadata objects. + @@ -763,12 +841,6 @@ The `/api/rest/2.0/report/answer` and `/api/rest/2.0/report/liveboard` now allow * `number_format_locale` * `date_format_locale` -//// -=== Custom authentication token API - -The `/api/rest/2.0/auth/token/custom` API endpoint now allows you to define the `reset_option` to specify if the attributes assigned to the token should persist or be reset. -//// - === Custom object ID in TML and Metadata APIs The following API endpoints allow you to specify a custom object ID (`obj_identifier`) in the metadata object properties: @@ -815,11 +887,6 @@ Indicates if the TMLs with large and complex metadata should be validated before + For more information about these attributes, see xref:tml.adoc#_import_tml_objects_asynchronously[Import TML objects asynchronously]. -//// -* `skip_diff_check` + -Allows skipping checks that find differences in TML content before processing TML objects for import. -//// - TML import API:: The `/api/rest/2.0/metadata/tml/import` API also supports setting the `enable_large_metadata_validation` attribute for large and complex metadata objects during TML import. @@ -893,14 +960,6 @@ User session:: ** `POST /api/rest/2.0/users/create` + ** `POST /api/rest/2.0/users/{user_identifier}/update` -//// -TML import API:: -You can specify the following attributes in TML import requests to `/api/rest/2.0/metadata/tml/import`: - -* `skip_cdw_validation_for_tables` + -Indicates if the Cloud Data Warehouse (CDW) validation for table imports should be skipped. -//// - Report API:: The `POST /api/rest/2.0/report/answer` API endpoint supports downloading an Answer generated by the Spotter AI APIs: 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..b2bc9702a --- /dev/null +++ b/modules/ROOT/pages/spotter-ai-memory-api.adoc @@ -0,0 +1,344 @@ += Spotter memory migration API reference +:toc: true +:toclevels: 2 + +:page-title: Spotter memory migration API +:page-pageid: spotter-memory-migration +:page-description: Use the AI memory REST API v2.0 endpoints to export and import Spotter training memory across ThoughtSpot environments. +:keywords: Spotter memory, AI memory, memory migration, memory export, memory import, Spotter training, REST API +:product-version: 26.8.0.cl +:jira-ref: SCAL-307522 + + +[beta betaBackground]#Beta# + +// SOURCE: SCAL-307522 +// SOURCE: Engineering design doc — https://docs.google.com/document/d/1YvnVNIkNQ5_vW4TY7rvR2x8uGXk2fHqwri4n6vCTTRc +// API schemas (ExportMemory, ImportMemory, ImportStatus, ImportMemoryItemFailureReason) +// confirmed from design doc. Public REST endpoint paths are inferred from naming convention. +// +// TODO: [WRITER] Confirm the public REST API v2.0 endpoint paths with the Agent Coaching team +// (Balakrishna Moravineni / SCAL-307522). Internal gRPC endpoints are +// eureka.dataindexer.EurekaDataIndexerService/ExportMemory and /ImportMemory. +// The paths POST /api/rest/2.0/ai/memory/export and /import are inferred — verify +// against the published OpenAPI spec before publishing. +// TODO: [WRITER] Confirm whether memory export/import requires a specific privilege beyond +// standard coaching access. Design doc states: "access checks same as coaching migration." +// TODO: [WRITER] Confirm the public request body parameter names — REST API v2.0 naming +// convention (snake_case) is used here. Verify against the OpenAPI spec. +// TODO: [WRITER] Confirm the export file format label ("memory-export-v2"). Clarify whether +// the output is JSON, YAML, or a custom TML-like format, and document the schema. +// TODO: [WRITER] Confirm export size limit — design doc states export fails if data models +// exceed 10,000 memory records combined. Verify the exact limit and error message. + +Spotter accumulates training memory — *rules* (business logic) and *recipes* (query patterns) — +as users interact with data models. ThoughtSpot 26.8.0.cl introduces public REST API v2.0 +endpoints to export and import this memory, enabling you to: + +* Promote validated Spotter knowledge from a development environment to production. +* Replicate a gold-standard Spotter configuration across multiple Orgs at scale. +* Back up and restore Spotter memory as part of your deployment pipeline. + +// SOURCE: Design doc — "The core problem is the inability to migrate Spotter Memory between +// environments, leading to a 'cold start' for the AI agent in new environments." + +[NOTE] +==== +Spotter memory migration APIs are available from ThoughtSpot Cloud 26.8.0.cl onwards. + +User memory and analyst memory are *not* supported in this release — only model-level rules +and recipes are included. +==== + +// SOURCE: Design doc — "User Memory is explicitly out of scope for V1." + +== Supported operations + +* <> — `POST /api/rest/2.0/ai/memory/export` +* <> — `POST /api/rest/2.0/ai/memory/import` + +=== Required permissions + +// TODO: [WRITER] Confirm exact privilege name with the Agent Coaching team. +// SOURCE: Design doc — "Export and import must follow the same access checks as coaching migration." +To use Spotter memory migration APIs, you must have coaching access or administrator privilege +on the data models being exported or imported. The Org and tenant context is resolved from the +authentication token. + +// ───────────────────────────────────────────────────────────────────────────────────────── +[#export-memory] +== Export Spotter memory + +[.version-badge.new]#New# ThoughtSpot Cloud 26.8.0.cl + +Exports Spotter training memory (rules and recipes) for one or more data models as a +structured, human-readable file. The exported file can be reviewed, edited, and imported +into another ThoughtSpot environment or Org. + +[TIP] +==== +Filter the export by data model GUIDs and a time window to export only memory entries +created or updated within a specific period. +==== + +=== Resource URL + +---- +POST /api/rest/2.0/ai/memory/export +---- + +=== Request parameters + +// SOURCE: Design doc — ExportMemoryRequest { memory_types, filter_groups, time_window } +// SOURCE: Design doc — enum MemoryType { RULES, RECIPES } +// SOURCE: Design doc — message TimeWindow { from_epoch, to_epoch, TimeField } + +[cols="1,1,1,3", options="header"] +|=== +|Parameter |Type |Required |Description + +|`memory_types` +|array of strings +|No +|Types of memory to export. Accepted values: `RULES`, `RECIPES`. If not specified, all +supported types are exported. + +|`data_model_identifiers` +|array of strings +|No +|GUIDs of the data models to export memory for. If not specified, memory for all accessible +data models is exported, up to the size limit. + +// TODO: [WRITER] Confirm parameter name. Design doc uses filter_groups with ContextFilter +// { type: WORKSHEET, ids: [...] }. The public REST API may simplify this to +// data_model_identifiers. Verify with the Agent Coaching team. + +|`time_window` +|object +|No +|Filters memory entries by time. Contains: + +* `from_epoch` (integer) — Start of window as Unix timestamp in milliseconds. + +* `to_epoch` (integer) — End of window as Unix timestamp in milliseconds. + +* `field` (string) — Time field to filter on: `CREATED_AT` (default) or `UPDATED_AT`. + +|=== + +=== Example request + +// TODO: [WRITER] Replace with a confirmed working example from the Agent Coaching team. +[source,cURL] +---- +curl -X POST \ + 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/memory/export' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + -H 'Content-Type: application/json' \ + -d '{ + "memory_types": ["RULES", "RECIPES"], + "data_model_identifiers": [ + "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", + "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy" + ], + "time_window": { + "from_epoch": 1768099200000, + "to_epoch": 1769099200000, + "field": "UPDATED_AT" + } + }' +---- + +=== Example response + +// SOURCE: Design doc — ExportMemoryResponse { export_json, export_tml } +// TODO: [WRITER] Confirm response format — JSON envelope with a file string field, or a +// direct file download? Design doc mentions export_json and export_tml as fields. +// Document the full memory-export-v2 format so users know what they can edit. +[source,JSON] +---- +{ + "export_tml": "# memory-export-v2\nversion: \"2.0\"\ndata_models:\n - id: \"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\"\n rules:\n - ...\n recipes:\n - ..." +} +---- + +=== Response codes + +[cols="1,3", options="header"] +|=== +|HTTP code |Description +|`200` |Memory exported successfully. Response body contains the export file. +|`400` |Bad request. Invalid memory type, malformed GUID, or export exceeds size limit (10,000 memory records). +|`401` |Unauthorized. Authentication token is missing or invalid. +|`403` |Forbidden. Insufficient coaching access on one or more specified data models. +|`404` |One or more specified data model GUIDs were not found. +|`500` |Internal server error. Contact ThoughtSpot Support. +|=== + +// ───────────────────────────────────────────────────────────────────────────────────────── +[#import-memory] +== Import Spotter memory + +[.version-badge.new]#New# ThoughtSpot Cloud 26.8.0.cl + +Imports a Spotter memory export file into the target ThoughtSpot environment. +The import *replaces* the existing memory of the target data models with the file contents — +it is an all-or-nothing operation. If any part of the import fails, all changes are rolled back. + +[IMPORTANT] +==== +The import operation is *destructive* — it replaces all existing Spotter memory for the +target data models. Use `dry_run` mode to validate before committing. + +// SOURCE: Design doc — "Import must replace the target's existing memory with the uploaded +// file (all-or-nothing migration). The file is the source of truth." +==== + +=== Resource URL + +---- +POST /api/rest/2.0/ai/memory/import +---- + +=== Request parameters + +// SOURCE: Design doc — ImportMemoryRequest { import_tml, mode } +// SOURCE: Design doc — enum ImportMode { EXECUTE_IMPORT = 0, DRY_RUN = 1 } + +[cols="1,1,1,3", options="header"] +|=== +|Parameter |Type |Required |Description + +|`import_tml` +|string +|Yes +|Full content of the memory export file as a string — produced by the export API or manually edited. + +|`mode` +|string +|No +|Import execution mode. Accepted values: + +* `DRY_RUN` (default) — Validates the file and returns a preview without making changes. + +* `EXECUTE_IMPORT` — Executes the import and replaces target memory. + +|=== + +=== Import statuses + +// SOURCE: Design doc — enum ImportStatus +After an import operation, the response includes one of these status values: + +[cols="1,3", options="header"] +|=== +|Status |Description +|`OK` |Import succeeded. `import_summaries` contains actual record counts. +|`DRY_RUN_OK` |Dry run completed. `import_summaries` contains a preview. +|`VALIDATION_FAILED` |File or row-level validation failed before any data was written. Review `failures` in the response. +|`ROLLED_BACK` |Import started but failed mid-execution. All changes rolled back to pre-import state. +|`FAILED` |Unexpected error. Contact ThoughtSpot Support. +|=== + +=== Import failure reasons + +// SOURCE: Design doc — enum ImportMemoryItemFailureReason + +[cols="1,3", options="header"] +|=== +|Failure reason |Description +|`VALIDATION` |Schema or format violation in the row. +|`UNRESOLVED_SOURCE` |Referenced data model GUID cannot be resolved in the target Org. +|`ACCESS_DENIED` |Insufficient coaching access on the referenced data model. +|`CHAR_LIMIT` |A content field exceeds the character or byte limit. +|`SCHEMA` |The YAML structure of the import file is invalid and could not be parsed. +|=== + +=== Example request — dry run + +// TODO: [WRITER] Replace with a confirmed working example from the Agent Coaching team. +[source,cURL] +---- +curl -X POST \ + 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/memory/import' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + -H 'Content-Type: application/json' \ + -d '{ + "import_tml": "# memory-export-v2\nversion: \"2.0\"\ndata_models:\n - ...", + "mode": "DRY_RUN" + }' +---- + +=== Example request — execute import + +[source,cURL] +---- +curl -X POST \ + 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/memory/import' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + -H 'Content-Type: application/json' \ + -d '{ + "import_tml": "# memory-export-v2\nversion: \"2.0\"\ndata_models:\n - ...", + "mode": "EXECUTE_IMPORT" + }' +---- + +=== Example response + +// TODO: [WRITER] Confirm response body structure with the Agent Coaching team. +[source,JSON] +---- +{ + "status": "OK", + "import_summaries": [ + { + "data_model_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", + "rules_imported": 12, + "recipes_imported": 34, + "rows_failed": 0 + } + ], + "failures": [] +} +---- + +=== Response codes + +[cols="1,3", options="header"] +|=== +|HTTP code |Description +|`200` |Operation completed. Check `status` in the response — a 200 may still indicate `VALIDATION_FAILED` or `ROLLED_BACK`. +|`400` |Bad request. Malformed request body or missing required parameter. +|`401` |Unauthorized. Authentication token is missing or invalid. +|`403` |Forbidden. Insufficient coaching access on one or more data models. +|`500` |Internal server error. Contact ThoughtSpot Support. +|=== + +== Memory migration workflow + +Use this workflow to migrate Spotter memory from a source environment to a target environment: + +. *Export memory from the source.* + + Call `POST /api/rest/2.0/ai/memory/export` with the GUIDs of the data models to migrate. + Save the exported file. + +. *Review and edit the file (optional).* + + The file is human-readable. You can update data model GUIDs for the target environment + and modify individual rules or recipes. Note that no semantic or column-level validation + is performed on import — ensure column names are valid in the target environment. + +. *Validate with a dry run.* + + Call `POST /api/rest/2.0/ai/memory/import` with `"mode": "DRY_RUN"`. Review + `import_summaries` and `failures` before proceeding. + +. *Execute the import.* + + Call `POST /api/rest/2.0/ai/memory/import` with `"mode": "EXECUTE_IMPORT"`. + +[WARNING] +==== +Appending or merging memory is *not* supported in this release. The import always replaces +the full memory state of the target data models. +// SOURCE: Design doc — "Merging memory on top of the existing target state is explicitly +// not supported in V1." +==== + +== Additional resources + +* xref:rest-api-v2-reference.adoc[REST API v2.0 reference] +* xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog] +* xref:spotter-train.adoc[Train Spotter] +// TODO: [WRITER] Add a link to the Spotter memory concept page once it exists. +// TODO: [WRITER] Add a link to the UI-based memory migration guide once published. diff --git a/modules/ROOT/pages/tml.adoc b/modules/ROOT/pages/tml.adoc index 9ffba0d70..cb72d1fee 100644 --- a/modules/ROOT/pages/tml.adoc +++ b/modules/ROOT/pages/tml.adoc @@ -8,6 +8,45 @@ 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. +// SOURCE: SCAL-307283, SCAL-317357 +// TODO: [WRITER] Confirm exact TML field names `owned_by` and `obj_id` in the Personalized View TML schema with the TML/deployment team before publishing. +// TODO: [WRITER] Confirm the smart merge behavior for `obj_id`: does a match update the existing view, skip import, or prompt the user? +// TODO: [WRITER] Confirm whether `obj_id` is present in TML export output for Collections by default in 26.8.0.cl, or must it be explicitly requested. +// TODO: [WRITER] Confirm the correct `metadata_type` value for Collections in the identity update API (`POST /api/rest/2.0/metadata/identity/update`). Verify with the platform team. +// TODO: [WRITER] Add a cross-reference to the product docs TML page for Personalized Views once the product docs page is updated. + +//// +[#collections-obj-id] +== Collections `obj_id` in TML + +// SOURCE: SCAL-317357 +Starting from 26.8.0.cl, the `obj_id` attribute is supported for the *Collections* object type in TML import and export. This enables stable cross-environment identification for Collections, consistent with support already available for Models, Liveboards, Answers, and other object types. + +=== Assign or update a Collections `obj_id` + +To assign or update the `obj_id` for an existing Collections object, use the Metadata Identity Update API: + +// TODO: [WRITER] Confirm endpoint path and `metadata_type` value for Collections with the platform team. +[source,bash] +---- +curl -X POST 'https://{ThoughtSpot-Host}/api/rest/2.0/metadata/identity/update' \ + -H 'Authorization: Bearer {token}' \ + -H 'Content-Type: application/json' \ + -d '{ + "metadata": [ + { + "identifier": "", + "metadata_type": "COLLECTION", + "obj_id": "my-stable-collection-id" + } + ] + }' +---- + +After the `obj_id` is assigned, TML exports for this Collection include the `obj_id` field, enabling stable identity across environments. +//// + + == Structure of a TML file To work with TML files for Models, views, SQL views, tables, Answers, Liveboards, and Monitor alerts in ThoughtSpot, you can download these objects as a flat file in `.TML` format, modify, and subsequently upload the TMLs either to the same or a different cluster. @@ -17,6 +56,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] + @@ -323,6 +363,65 @@ If Orgs are enabled on your instance, the API returns task status only for objec |**500**|Unexpected Error |==== +[#personalized-views-portability] +=== Personalized Views portability [earlyAccess eaBackground]#Early Access# + +Personalized Views support improved portability across ThoughtSpot environments. Two new TML fields and updated import merge logic make it easier to migrate Personalized Views between environments without creating duplicates. + +`author`::: +// TODO: [WRITER] Confirm field name and accepted value types (username string vs. user GUID). +A new `author` field is added to the Personalized View TML during export. This field is used to assign ownership during import. + +`obj_id`::: +// TODO: [WRITER] Confirm field name. Confirm whether obj_id is auto-generated on export or must be manually assigned before import. +A new `obj_id` field provides stable cross-environment object identity for Personalized Views. Use the same `obj_id` value across environments to ensure consistent identity during migrations. + + +When importing a Personalized View TML that contains an `obj_id`, and the `enable_personalized_view_upsert` is set to `true`, ThoughtSpot 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. + +// TODO: [WRITER] Confirm: does the merge-on-match behavior apply only when `create_new` is set to `false` in the import request, or does it apply regardless of `create_new`? +To enable this feature for your instance, contact your ThoughtSpot administrator. + +==== 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. + == 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..aac75a53c 100644 --- a/modules/ROOT/pages/tse-eco-mode.adoc +++ b/modules/ROOT/pages/tse-eco-mode.adoc @@ -18,9 +18,40 @@ Indicates that the cluster is stopped and no user activity is detected. The cluster is currently starting, or some other workflow is running on the cluster. == 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. -When the upgrade starts, the ThoughtSpot instance operates in the Ephemeral (Read-Only mode) and the cluster state changes to `UNDER_MAINTENANCE`. +// SOURCE: SCAL-320519 +// TODO: [WRITER] Verify the following deprecation statement with the cluster operations/TSE +// team before publishing: +// 1. Is the Ephemeral Read-Only mode fully deprecated, or is only the name changing? +// 2. What state does the cluster enter during upgrade from 26.8.0.cl — is `UNDER_MAINTENANCE` +// the only state, with no user access at all? +// 3. Does the `under_maintenance` field in the API response remain, or is it also deprecated? +// Update the NOTE block and surrounding text once engineering confirms the new behavior. + +With ThoughtSpot's Minimal Downtime Ephemeral Mode upgrade option, ThoughtSpot performs cluster upgrades in the background. During an upgrade, the cluster enters a transient state and the cluster state changes to `UNDER_MAINTENANCE`. + +[NOTE] +==== +[.version-badge.deprecated]#Deprecated# ThoughtSpot Cloud 26.8.0.cl + +The Ephemeral Read-Only mode — which previously allowed users limited read-only access (create and view data, with changes discarded after upgrade) during cluster upgrades — is deprecated as of ThoughtSpot Cloud 26.8.0.cl. + ++ +Clusters undergoing maintenance now enter the `UNDER_MAINTENANCE` state. Contact ThoughtSpot Support for details on upgrade scheduling and expected downtime. +// TODO: [WRITER] If limited access is still available under a different mechanism or name, +// update this NOTE to describe the new behavior instead of stating "no user access." +==== + +//// +NOTE TO WRITER: The following paragraph described the old Ephemeral (Read-Only) mode behavior. +Reason: The read-only mode during upgrades is deprecated in 26.8.0.cl (SCAL-320519). +Action required: Review before publishing. If any form of limited access during upgrade is +still supported, update the paragraph below to describe the new behavior. Delete this block +to confirm removal once the new behavior is documented. + +When the upgrade starts, the ThoughtSpot instance operates in the Ephemeral (Read-Only mode) +and the cluster state changes to `UNDER_MAINTENANCE`. This means that during the upgrade, the +system is in a transient state yet allows users to create and view data. However, any new objects +created during the upgrade will be lost. +//// ThoughtSpot users can determine if their instance is under maintenance by sending a `GET` request to one of the following API endpoints: @@ -64,11 +95,15 @@ https://{ThoughtSpot-Host}/api/rest/2.0/system/banner === API response -If the cluster in maintenance mode, the API returns the following response: +If the cluster is in maintenance mode, the API returns the following response: ---- {"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} ---- +// TODO: [WRITER] The banner_text above references "ephemeral mode" which is now deprecated. +// Confirm with the platform team whether the API response banner_text is also updated +// in 26.8.0.cl, and update this example if so. + If the cluster is not in maintenance mode, the API returns the following response: ---- {"banner_text":"This system is functioning normally. No maintenance is in progress.","under_maintenance":false} @@ -172,4 +207,4 @@ Indicates a possible error. Contact your administrator or ThoughtSpot Support if |**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 dc99edbb4..8a0f1e19f 100644 --- a/modules/ROOT/pages/whats-new.adoc +++ b/modules/ROOT/pages/whats-new.adoc @@ -23,6 +23,210 @@ This page lists new features, enhancements, and deprecated functionality introdu // *Affects:* Developers, Administrators, End Users // ============================================================ +// ============================================================ +// SOURCE: SCAL-295712, SCAL-309481, SCAL-273333, SCAL-312731, SCAL-292918, +// SCAL-310399, SCAL-312622, SCAL-309017, SCAL-307283, SCAL-317357, +// SCAL-306340, SCAL-313088, SCAL-293483, SCAL-244749, SCAL-323283 +// TODO: [WRITER] Confirm the exact calendar month label ("August 2026") with +// the release team before publishing. SCAL-295712 targets 26.8.0.cl but +// the calendar ship date is not confirmed at time of authoring (2026-07-10). +// ============================================================ + +== August 2026 + +**Release version**: ThoughtSpot Cloud 26.8.0.cl + +*Upgrade notes*: See individual feature entries below for backward-compatibility notes. The Navigation V1/V2 deprecation may require SDK configuration updates. + +*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 Analysts [earlyAccess eaBackground]#Early Access# +// SOURCE: SCAL-310399, SCAL-312622 +// SOURCE: src/embed/conversation.ts @version SDK: 1.51.0 | ThoughtSpot: 26.8.0.cl +// TODO: [WRITER] Confirm EA vs GA status with Agents Experience team (Karamveer Singh) before publishing. +// TODO: [WRITER] Confirm the full list of Action enum values for Analyst actions in types.ts once SDK 1.51.0 is tagged — verify Action.ShowAnalysts, Action.CreateAnalyst, Action.EditAnalyst, Action.MakeCopyAnalyst, Action.ShareAnalyst, Action.DeleteAnalyst exist in the released SDK. +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. + +In ThoughtSpot Embedded, the Analysts section is disabled by default. The Visual Embed SDK 1.51.0 introduces the following controls: + +Custom labels (in `SpotterSidebarViewConfig`)::: +* `spotterAnalystLabel` — Custom singular label for the Analyst entity. Default: `Analyst`. +* `spotterAnalystsLabel` — Custom label for the Analysts sidebar section. Default: `Analysts`. + +Starter prompts (in `SpotterChatViewConfig`)::: +* `enableStarterPrompts` — When set to `true`, shows onboarding starter prompts on initial load. Default: `false`. + +Action IDs for `hideActions` or `disableActions`::: +// TODO: [WRITER] Verify these Action enum values against the released SDK 1.51.0 types.ts before publishing. +* `Action.ShowAnalysts`, `Action.CreateAnalyst`, `Action.EditAnalyst`, `Action.MakeCopyAnalyst`, `Action.ShareAnalyst`, `Action.DeleteAnalyst` + +For more information, see xref:embed-spotter.adoc#spotter-analysts[Spotter Analysts in embedded applications]. + +--- + +[discrete] +==== SpotterViz Insight Tiles [earlyAccess eaBackground]#Early Access# +// SOURCE: SCAL-309017 +// SOURCE: src/embed/spotter-viz-utils.ts @version SDK: 1.51.0 | ThoughtSpot Cloud: 26.8.0.cl +// TODO: [WRITER] Confirm the exact embed config properties for Insight Tiles with the SpotterViz team. The loaderHeadline/loaderTips properties are confirmed from SDK source; confirm whether additional Insight Tile-specific config exists. +// TODO: [WRITER] Add a screenshot of SpotterViz Insight Tiles in the Liveboard Agent panel once available from the design team. +ThoughtSpot introduces *Insight Tiles* in the SpotterViz experience on embedded Liveboards. Insight Tiles appear in the Liveboard Agent panel as AI-generated data insight cards that users can interact with. + +The Visual Embed SDK 1.51.0 extends `SpotterVizConfig` with two new properties for the SpotterViz loading state: + +* `loaderHeadline` — Custom headline text displayed while SpotterViz is loading. +* `loaderTips` — Custom array of tips (`SpotterVizLoaderTip[]`) shown during the loading state. + +For more information, see xref:embed-spotterViz.adoc[SpotterViz in embedded Liveboards]. + +--- + +[discrete] +==== Spotter onboarding starter prompts [.version-badge.new]#New# +// SOURCE: SCAL-293483, SCAL-314448 +// SOURCE: src/embed/conversation.ts @version SDK: 1.51.0 | ThoughtSpot: 26.8.0.cl +// TODO: [WRITER] Verify that enableStarterPrompts is supported in SpotterEmbed (in addition to LiveboardEmbed and AppEmbed) by checking the SDK source for SpotterEmbedViewConfig. +Embedded Spotter now supports onboarding starter prompts to guide first-time users. When enabled, Spotter presents suggested questions based on the connected data model. Use `enableStarterPrompts: true` in `SpotterChatViewConfig` to enable this feature. + +For more information, see xref:embed-spotter.adoc#_enable_starter_prompts[Enable starter prompts in Spotter]. + +--- + +[discrete] +==== Navigation and homepage V1/V2 deprecated [.version-badge.deprecated]#Deprecated# +// SOURCE: SCAL-312731 +// TODO: [WRITER] Confirm exact release in which V1 and V2 will be fully REMOVED (not just deprecated) with the product team. Update the phrase "a future release" with the specific version once confirmed. +// TODO: [WRITER] Verify with SDK team whether existing embeds that omit discoveryExperience automatically fall back to V3, or require explicit SDK configuration update. +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. + +ThoughtSpot recommends updating your embed configuration to set `discoveryExperience` explicitly with `PrimaryNavbarVersion.Sliding` and `HomePage.ModularWithStylingChanges` to ensure compatibility with future releases. + +For migration guidance, see xref:full-app-customize.adoc#nav-v1-v2-deprecation[V1 and V2 deprecation]. + +--- + +[discrete] +==== TSE: Multiple features now generally available [.version-badge.new]#New# +// SOURCE: SCAL-295712 +// TODO: [WRITER] Confirm with product team the exact set of features going GA in 26.8.0.cl. Verify that Hide Irrelevant Filters, Compact Header, Cover Filter Page, and Aether UI are all included in 26.8.0.cl GA. +The following features, previously in Early Access, are now generally available for ThoughtSpot Embedded instances: + +* *Hide Irrelevant Filters* — Filters that are not relevant to the displayed visualization are automatically hidden. +* *Compact Header* — A condensed header layout for embedded Liveboards. +* *Cover Filter Page* — Overlay filter page experience for Liveboards. +* *Aether UI* — Updated visual design system. + +No SDK configuration changes are required. These features are enabled by default for all embedded instances on 26.8.0.cl. + +--- + +[discrete] +==== WYSIWYG Liveboard PDF export [.version-badge.new]#New# +// SOURCE: SCAL-309481 +// TODO: [WRITER] Verify whether `isContinuousLiveboardPDFEnabled` (introduced in SDK 1.48.0 as Beta) is the same capability going GA in 26.8.0.cl, or a separate WYSIWYG capability. Confirm with the Liveboard team. +// TODO: [WRITER] Verify backward compatibility: confirm that existing `DownloadLiveboardAsContinuousPDF` action behavior is unchanged for embeds using SDK 1.48.x+. +The WYSIWYG Liveboard PDF export experience is now generally available for ThoughtSpot Embedded instances. When enabled, the exported PDF matches the exact Liveboard layout as displayed on screen, rendering visualizations in a continuous layout rather than splitting them across A4 pages. + +--- + +[discrete] +==== Granular download privileges [.version-badge.new]#New# +// SOURCE: SCAL-273333 +// TODO: [WRITER] Confirm exact privilege names displayed in the UI ("Can Download Visuals" and "Can Download Detailed Data") and their corresponding REST API enum values with the access control team. +// TODO: [WRITER] Confirm whether existing "Can download" privilege assignments are automatically migrated to both new privileges, or require manual re-assignment. +ThoughtSpot introduces two new granular download privileges that replace the single general download privilege: + +* *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 [.version-badge.new]#New# +// SOURCE: SCAL-307283 +// TODO: [WRITER] Confirm exact TML field names `owned_by` and `obj_id` in the Personalized View TML schema with the TML/deployment team before publishing. +// TODO: [WRITER] Confirm the import merge behavior — does a duplicate check on `obj_id` update the existing view, or skip the import? +ThoughtSpot improves the portability of Personalized Views across environments: + +* A new `owned_by` field in the Personalized View TML allows specifying the owner during import. +* Personalized Views now support `obj_id` for stable cross-environment object identity. +* Import operations use smart merge logic to avoid duplicating Personalized Views with matching identity. + +For more information, see xref:tml.adoc[TML import and export]. + +--- + +[discrete] +==== Collections `obj_id` support in TML [.version-badge.new]#New# +// SOURCE: SCAL-317357 +// TODO: [WRITER] Verify the exact REST API endpoint path for updating Collections obj_id with the platform team. Candidate path: POST /api/rest/2.0/metadata/identity/update — confirm this is correct and supported for Collections. +The `obj_id` attribute is now supported for the *Collections* object type in TML import and export. This enables stable cross-environment identification for Collections, consistent with support already available for other object types such as Models, Liveboards, and Answers. + +The Metadata Identity Update API is extended to support updating `obj_id` for Collections. + +For more information, see xref:tml.adoc[TML import and export]. + +--- + +[discrete] +==== Discoverability checkbox removed [.version-badge.breaking]#Breaking# +// SOURCE: SCAL-292918 +// TODO: [WRITER] Verify whether the `discoverable` field in REST API share requests is also removed or deprecated, or whether the API still accepts it silently. +The *Make this Liveboard Discoverable* checkbox has been removed from the ThoughtSpot UI. Content is no longer made discoverable through a toggle. Sharing and access control are now managed exclusively through explicit sharing workflows. + +Embedding applications that relied on discoverability for content visibility should review their sharing logic and update user-facing guidance for content access. + +--- + +[discrete] +==== Schedule every-N-minutes option deprecated [.version-badge.deprecated]#Deprecated# +// SOURCE: SCAL-244749 +// TODO: [WRITER] Confirm which release the every-N-minutes frequency option will be fully removed. Confirm whether existing schedules are automatically migrated to the next supported frequency. +The *every N minutes* frequency option for Liveboard scheduled jobs is deprecated in 26.8.0.cl. New scheduled jobs cannot be created with this frequency. Existing jobs configured with this frequency continue to run until they are edited or the option is removed in a future release. + +Embedding applications that create scheduled jobs programmatically via the REST API should remove any usage of the `every_n_minutes` frequency in schedule creation requests. + +--- + +[discrete] +==== Business Terms autogeneration deprecated [.version-badge.deprecated]#Deprecated# +// SOURCE: SCAL-313088 +// TODO: [WRITER] Confirm whether existing auto-generated business terms are preserved or removed after this deprecation. Confirm which Spotter coaching REST API endpoints are affected. +The automatic generation of Business Terms for Spotter model coaching is deprecated. The Business Terms fields in the Spotter coaching interface are now available exclusively for adding custom context. Administrators who manage Spotter model coaching should review existing business term configurations. + +--- + +[discrete] +==== Spotter Model [.version-badge.new]#New# +// SOURCE: SCAL-306340 +// TODO: [WRITER] Confirm whether Spotter Model GA milestone is 26.8.0.cl or jun.26.mt. Verify with the AI Modeling team before publishing. +// TODO: [WRITER] Add xref to the Spotter Model page in developer-docs once the page filename is confirmed. +Spotter Model — which allows administrators to configure, train, and manage a dedicated AI model for Spotter — is now generally available. For more information, see the Spotter Model documentation. + +--- + +[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 + @@ -94,7 +298,7 @@ For more information, see xref:developer-playground.adoc#spottercode-panel[Using [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]. --- @@ -283,7 +487,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]. @@ -650,4 +854,4 @@ For information about the new features and enhancements introduced in Visual Emb ==== REST API For information about REST API v2 enhancements, see xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. -|=== \ No newline at end of file +|===