diff --git a/modules/ROOT/pages/.write-test b/modules/ROOT/pages/.write-test new file mode 100644 index 000000000..0e808f9c2 --- /dev/null +++ b/modules/ROOT/pages/.write-test @@ -0,0 +1 @@ +write access test - delete me \ No newline at end of file diff --git a/modules/ROOT/pages/api-changelog.adoc b/modules/ROOT/pages/api-changelog.adoc index 0619c8767..7b61550e8 100644 --- a/modules/ROOT/pages/api-changelog.adoc +++ b/modules/ROOT/pages/api-changelog.adoc @@ -8,6 +8,49 @@ This page documents the changes introduced in each release of the Visual Embed SDK. For information about the REST API v2.0 changes, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. +== Version 1.52.x, September 2026 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| + +[discrete] +===== Browser history management in full application embedding +To override the browser history behavior for embedding application users and prevent users from getting trapped in back-button loops inside the embedded iframe environment, you can now set `overrideHistoryState` in the Visual Embed SDK. + + +//// +[source,JavaScript] +---- +import { AppEmbed, init, AuthType } from '@thoughtspot/visual-embed-sdk'; + +init({ + thoughtSpotHost: 'https://.thoughtspot.cloud', + authType: AuthType.TrustedAuthToken, + getAuthToken: () => fetch('/ts-token').then(r => r.json()).then(d => d.token), +}); + +const embed = new AppEmbed('#embed-container', { + frameParams: { width: '100%', height: '100%' }, + overrideHistoryState: true, // <1> +}); + +embed.render(); +---- +<1> When set to `true`, ThoughtSpot replaces rather than pushes browser history entries during internal navigation. +//// + +|[tag greenBackground]#NEW FEATURE# a| + +[discrete] +===== Collections in left navigation panel +The `HomeLeftNavItem.Collections` enum value is now available in the Visual Embed SDK. Embed developers can include *Collections* as a selectable navigation option in the embedded left navigation panel for full application embeds. When enabled, end users of the embedded application can navigate to *Collections* from the left navigation panel. + +For more information, see xref:full-app-customize.adoc[Customize full application embedding]. + +|==== + + == Version 1.51.x, August 2026 [width="100%" cols="1,4"] @@ -1919,4 +1962,4 @@ Users with edit permissions can view and access the *Edit* action. The *Download When a user accesses the embedded application from a web browser that has third-party cookies disabled, the Visual Embed SDK emits the `NoCookieAccess` event to notify the developer. Cookies are disabled by default in Safari. Users can enable third-party cookies in Safari’s Preferences setting page or use another web browser. To know how to enable this setting by default on Safari for a ThoughtSpot embedded instance, contact ThoughtSpot Support. -|==== \ No newline at end of file +|==== diff --git a/modules/ROOT/pages/data-report-v2-api.adoc b/modules/ROOT/pages/data-report-v2-api.adoc index a73d16087..f1ed36d8e 100644 --- a/modules/ROOT/pages/data-report-v2-api.adoc +++ b/modules/ROOT/pages/data-report-v2-api.adoc @@ -687,4 +687,109 @@ To sort columns on a Liveboard or Answer, define runtime sort properties in `run For more information, see xref:runtime-sort.adoc#_rest_api_v2_0[Runtime sorting of columns]. - + [#answer-report] + === Answer Report API + + // SOURCE: SCAL-306069 + + The `POST /api/rest/2.0/report/answer` endpoint is generally available from 26.9.0.cl. Use this endpoint to export Answer data in CSV, XLSX, PDF, or PNG format. The endpoint supports saved Answers, pinned Answers (visualizations on a Liveboard), and Spotter-generated (ad hoc) Answers. + + ==== Prerequisites + + To download Answer data, the user must have at least *View* access to the Answer or Liveboard. If RBAC is enabled: + + * `DATADOWNLOADING` (Can download Data) — required for all export formats. + * `CAN_DOWNLOAD_DETAILED_DATA` (Can download detailed data) — required for CSV and XLSX. + * `CAN_DOWNLOAD_VISUALS` (Can download visuals) — required for PNG. + + ==== Request parameters + + [width="100%" cols="2,1,4"] + [options="header"] + |===== + | Parameter | Required | Description + | `metadata_identifier` | Conditional | GUID or name of the saved Answer. For pinned Answer exports, use the parent Liveboard GUID or name and pass `viz_guid` separately. + | `file_format` | Yes | Export format. Accepted values: `CSV`, `XLSX`, `PDF`, `PNG`. + | `viz_guid` | No | GUID of a pinned visualization on a Liveboard. When specified, `metadata_identifier` must identify the parent Liveboard. + | `personalised_view_identifier` | No | GUID or name of a Personalized View. When specified, the export uses data from that view. + | `runtime_filter` | No | Runtime filter overrides to apply to the export. + | `runtime_sort` | No | Runtime sort overrides to apply to the export. + | `runtime_param_override` | No | Runtime parameter overrides to apply to the export. + | `x_resolution` | No | Width of the PNG export in pixels. Range: 600–3840. Applies only when `file_format` is `PNG`. Default: 2254. + | `y_resolution` | No | Height of the PNG export in pixels. Range: 600–3840. Applies only when `file_format` is `PNG`. Default: 1588. + | `scaling_factor` | No | Scaling percentage for chart elements in PNG exports. Range: 80–400. Does not crop the image. Applies only when `file_format` is `PNG`. + |===== + + ==== Export a saved Answer + + [source,cURL] + ---- + curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/octet-stream' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "metadata_identifier": "my-saved-answer", + "file_format": "CSV" + }' \ + --output answer.csv + ---- + + ==== Export a pinned Answer + + [source,cURL] + ---- + curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/octet-stream' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "metadata_identifier": "", + "viz_guid": "", + "file_format": "PDF" + }' \ + --output pinned-answer.pdf + ---- + + ==== Export a Spotter Answer + + [source,cURL] + ---- + curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/octet-stream' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "metadata_identifier": "", + "file_format": "XLSX" + }' \ + --output spotter-answer.xlsx + ---- + + [NOTE] + ==== + Pass the answer ID from the Spotter API response as `metadata_identifier`. XLSX and PDF formats are supported for Spotter Answers from 26.9.0.cl. + ==== + + ==== Export a PNG with custom dimensions + + [source,cURL] + ---- + curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/octet-stream' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "metadata_identifier": "my-saved-answer", + "file_format": "PNG", + "x_resolution": 3840, + "y_resolution": 2160, + "scaling_factor": 150 + }' \ + --output answer-4k.png + ---- + \ No newline at end of file diff --git a/modules/ROOT/pages/rest-apiv2-changelog.adoc b/modules/ROOT/pages/rest-apiv2-changelog.adoc index 22e0cfcaf..b5325b191 100644 --- a/modules/ROOT/pages/rest-apiv2-changelog.adoc +++ b/modules/ROOT/pages/rest-apiv2-changelog.adoc @@ -8,6 +8,127 @@ This changelog lists the features and enhancements introduced in REST API v2.0. For information about new features and enhancements available for embedded analytics, see xref:whats-new.adoc[What's New]. +== Version 26.9.0.cl, September 2026 + + === Answer Export API enhancements — General Availability + + // SOURCE: SCAL-306069 + + The `POST /api/rest/2.0/report/answer` endpoint is generally available from 26.9.0.cl. The `isAnswerExportV2Enabled` flag is enabled by default on all ThoughtSpot Cloud instances. The following enhancements are included in this release: + + Pinned Answer export:: + Pass `viz_guid` to export a pinned Answer (a visualization on a Liveboard) directly. Liveboard-level filters and runtime overrides are applied automatically. The `metadata_identifier` must be the parent Liveboard GUID or name. + + Personalized View support:: + Pass `personalised_view_identifier` to export data from a specific Personalized View of a Liveboard. + + Spotter Answer export:: + XLSX and PDF export formats are now supported for Spotter-generated (ad hoc) Answers, in addition to CSV and PNG. + + Custom PNG dimensions:: + Use `x_resolution` and `y_resolution` parameters to specify custom pixel dimensions for PNG exports. Accepted range: 600–3840 px per axis. Default: 2254 × 1588. + + Display scaling:: + Use `scaling_factor` (range: 80–400) to adjust the relative size of chart elements in a PNG export without cropping the image. + + Dynamic file naming:: + Exported files are automatically named based on the Answer title with the correct file extension (`.png`, `.pdf`, `.csv`, `.xlsx`) appended. + + For more information, see xref:data-report-v2-api.adoc#answer-report[Answer Report API]. + + === Snowflake Semantic View integration APIs + + // SOURCE: SCAL-309867 + + ThoughtSpot 26.9.0.cl introduces REST API v2.0 endpoints for managing Snowflake Semantic View integrations programmatically. These APIs allow administrators and data managers to create, search, import, and delete semantic integration configurations without using the ThoughtSpot UI. + + [width="100%"] + [options="header"] + |===== + | Method | Endpoint | Description + | `POST` | `/api/rest/2.0/semantic-integrations/create` | Creates a new semantic integration by reading a Snowflake Semantic View and generating a ThoughtSpot data model. + | `POST` | `/api/rest/2.0/semantic-integrations/search` | Returns a list of semantic integrations matching the specified filter criteria. + | `POST` | `/api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/import` | Re-imports semantic updates from Snowflake and refreshes the associated ThoughtSpot data model. + | `POST` | `/api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/delete` | Deletes a semantic integration and its generated ThoughtSpot data model. + |===== + + Required privilege: `ADMINISTRATION` or `DATAMANAGEMENT`. If RBAC is enabled, the user also requires the `CAN_CREATE_OR_EDIT_CONNECTIONS` privilege and permission to manage data models. + + For more information, see xref:semantic-integrations-api.adoc[Snowflake Semantic View integration APIs]. + + === Spotter Memory — General Availability + + // SOURCE: SCAL-306173 + + The Spotter Memory feature is generally available from 26.9.0.cl. The memory APIs introduced in 26.8.0.cl (`POST /api/rest/2.0/ai/memory/import` and `POST /api/rest/2.0/ai/memory/export`) are enabled by default on all ThoughtSpot Cloud instances. Administrators can manage and audit Spotter training data programmatically without enabling a feature flag. + + For more information, see xref:spotter-ai-memory-api.adoc[Spotter memory APIs]. + + === Spotter Agent — Conversation sharing APIs + + // SOURCE: SCAL-306173 (aug.26.mt) + + ThoughtSpot 26.9.0.cl introduces REST API v2.0 endpoints for sharing saved Spotter agent conversations with other users or groups. Shared conversations are always `READ_ONLY`. + + [width="100%"] + [options="header"] + |===== + | Method | Endpoint | Description + | `POST` | `/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` | Shares a saved Spotter conversation with specified principals. Use `grant` and `revoke` arrays to manage access. + | `GET` | `/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content` | Returns the content of a shared Spotter conversation — messages, data sources, and answer details. + | `GET` | `/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info` | Returns sharing metadata — the list of principals the conversation is shared with and their access levels. The `is_shared_content_outdated` flag indicates if the shared snapshot is stale. + |===== + + For more information, see xref:spotter-agent-apis.adoc#_sharing_spotter_conversations[Sharing Spotter conversations]. + + === KPI Sparkline setting in metadata search response + + // SOURCE: SCAL-320899 + + The `POST /api/rest/2.0/metadata/search` API response now includes the `isSparklineEnabled` field in the `AnswerSpecHeader` object for KPI chart type answers. This boolean field indicates whether the sparkline trend line is enabled for the KPI visualization. + + * `true` — the sparkline trend line is enabled. + * `false` — the sparkline is disabled. + * Absent — the answer was saved before this release and has not been re-saved. Treat an absent field as unknown, not as `false`. + + === Outline Encoding — BYOC Muze + + // SOURCE: SCAL-317550 + + ThoughtSpot 26.9.0.cl promotes mark outline color to a first-class data-driven encoding channel in the Muze charting library (BYOC). Developers building custom charts with Muze can now bind a data field to `encoding.outline` to produce ordinal color palettes (for categorical fields) or continuous gradient ramps (for measures), with full legend rendering and legend-to-mark interaction. + + The static `outline` config (`{ fill, color, width, dash }`) remains fully backward compatible. Supported mark types: Point, Bar, Arc. + + === Personalized Views TML portability — General Availability + + // SOURCE: SCAL-307284 + + The Personalized Views TML portability feature introduced as Early Access in 26.8.0.cl is generally available from 26.9.0.cl. + + * The `author` field in Personalized View TML maps to the view owner's username or email, ensuring ownership is retained when a Liveboard is promoted across clusters or orgs. + * The `obj_id` field provides a stable cross-environment identifier for Personalized Views. + * Smart merge import: when importing a Liveboard TML that contains Personalized Views, ThoughtSpot preserves views that exist only in the target environment, appends new views from the imported TML, and updates views present in both. + + For more information, see xref:tml.adoc#personalized-views-portability[Personalized Views portability in TML]. + + === Connection configuration — Scheduled Liveboards process type + + // SOURCE: SCAL-312738 + + ThoughtSpot 26.9.0.cl adds `SCHEDULED_LIVEBOARDS` as a new process type for Embrace connection configurations. Administrators can assign the Scheduled Liveboards process to a connection configuration, enabling ThoughtSpot to use the associated credentials when running scheduled Liveboard delivery jobs. Configurable via: + + * `POST /api/rest/2.0/connection/configuration/create` + * `PUT /api/rest/2.0/connection/configuration/{configuration_identifier}/update` + + === AI Context — Spotter Optimization tab + + // SOURCE: SCAL-277656 + + The AI Context generation UI is revamped in 26.9.0.cl. A new *Spotter Optimization* tab is introduced in the data model editor for managing AI context, replacing the previous AI Context panel. The tab provides a more streamlined interface for reviewing and editing auto-generated descriptions for columns and joins. + + No changes to the AI context REST API endpoints in this release. + + == Version 26.8.0.cl, August 2026 === Spotter AI APIs diff --git a/modules/ROOT/pages/semantic-integrations-api.adoc b/modules/ROOT/pages/semantic-integrations-api.adoc new file mode 100644 index 000000000..0a9f80a9e --- /dev/null +++ b/modules/ROOT/pages/semantic-integrations-api.adoc @@ -0,0 +1,376 @@ += Snowflake Semantic View integration APIs +:toc: true +:toclevels: 3 + +:page-title: Snowflake Semantic View integration APIs +:page-pageid: semantic-integrations-api +:page-description: Use the ThoughtSpot REST API v2.0 endpoints to create, search, import, and delete Snowflake Semantic View integration configurations programmatically. + +ThoughtSpot provides the Semantic View integrations REST API v2.0 endpoints to create, search, import, and delete semantic integration configurations programmatically. + +== Overview +Snowflake Semantic Views provide a governed semantic layer for data in Snowflake, including named measures, dimensions, and business-logic formulas. When you create a semantic integration in ThoughtSpot, the platform reads the semantic view definition from Snowflake and generates a corresponding ThoughtSpot data model (Worksheet). The model inherits the column names, descriptions, and formula definitions from the Snowflake Semantic View. + +You can use the semantic integration APIs to automate the following tasks: + +* Create a semantic integration that links a Snowflake Semantic View to a ThoughtSpot data model. +* Search and list existing semantic integrations. +* Re-import a semantic integration to refresh the ThoughtSpot model after the source Snowflake Semantic View has changed. +* Delete a semantic integration and its generated ThoughtSpot model. + +[NOTE] +==== +The semantic integration APIs are available on ThoughtSpot Cloud instances from 26.9.0.cl. +Snowflake is the only supported CDW connector type (`RDBMS_SNOWFLAKE`). +==== + +== Prerequisites + +To use these APIs, the authenticated user must have one of the following privileges: + +* `ADMINISTRATION` (*Can administer ThoughtSpot*) +* `DATAMANAGEMENT` (*Can manage data*) + +If Role-Based Access Control (RBAC) is enabled on your instance, the user requires `CAN_CREATE_OR_EDIT_CONNECTIONS` (*Can create/edit Connections*) privilege. + +== API endpoints + +[width="100%"] +[options="header"] +|===== +| Method | Endpoint | Description +| `POST` | `/api/rest/2.0/semantic-integrations/create` | Creates a new semantic integration by reading a Snowflake Semantic View and generating a ThoughtSpot data model. +| `POST` | `/api/rest/2.0/semantic-integrations/search` | Returns a list of semantic integrations matching the specified filter criteria. +| `POST` | `/api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/import` | Re-imports semantic updates from the CDW source and refreshes the associated ThoughtSpot data model. +| `POST` | `/api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/delete` | Deletes a semantic integration and its generated ThoughtSpot data model. +|===== + +[#create-semantic-integration] +== Create a semantic integration +To create a new semantic integration by reading the specified Snowflake Semantic View and generating a corresponding ThoughtSpot data model, use the `/api/rest/2.0/semantic-integrations/create` API endpoint. On success, the response includes the integration GUID, the generated model GUID, and a per-formula import report. + + +=== Request parameters + +[width="100%"] +[options="header"] +|===== +| Parameter | Type | Required | Description +| `connection_identifier` | String | Yes | GUID or name of the Snowflake connection in ThoughtSpot. +| `name` | String | Yes | Display name for the semantic integration. Must be unique. +| `database_name` | String | Yes | Database name in the Snowflake CDW that contains the semantic view. +| `schema_name` | String | Yes | Schema name in the Snowflake CDW that contains the semantic view. +| `semantic_view_name` | String | Yes | Name of the Snowflake Semantic View to integrate. +| `type` | String | Yes | CDW connector type. Only accepted value: `RDBMS_SNOWFLAKE`. +| `description` | String | No | Optional description for the semantic integration. +| `tags` | Array | No | Tag GUIDs or names to associate with the integration. +|===== + +=== Response fields + +[width="100%"] +[options="header"] +|===== +| Field | Type | Description +| `id` | String | GUID of the newly created semantic integration. +| `name` | String | Display name of the semantic integration. +| `model_id` | String | GUID of the ThoughtSpot data model generated for this integration. +| `model_name` | String | Display name of the generated ThoughtSpot data model. +| `semantic_report` | Object | Per-formula import report. See <<_semantic_report_fields>>. +|===== + +[#semantic-report-fields] +=== Semantic report fields + +The `semantic_report` object contains a summary and a list of per-formula import results. + +`summary` fields: + +[width="100%"] +[options="header"] +|===== +| Field | Type | Description +| `total` | Integer | Total number of formulas in the Snowflake Semantic View. +| `imported` | Integer | Number of formulas successfully imported. +| `failed` | Integer | Number of formulas that failed to import. +| `skipped` | Integer | Number of formulas that were skipped. +|===== + +`formulas` array — each entry contains: + +[width="100%"] +[options="header"] +|===== +| Field | Type | Description +| `id` | String | Formula GUID in the generated ThoughtSpot model. +| `name` | String | Formula name. +| `description` | String | Formula description. +| `source_expression` | String | Original CDW expression. +| `translated_formula` | String | Equivalent ThoughtSpot formula expression. +| `import_status` | String | One of `IMPORTED`, `FAILED`, or `SKIPPED`. +| `change_status` | String | One of `NEW`, `UPDATED`, or `UNCHANGED`. Null on initial create (populated by import). +|===== + +=== Example request + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/semantic-integrations/create' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "connection_identifier": "", + "name": "Sales Semantic View", + "database_name": "SALES_DB", + "schema_name": "PUBLIC", + "semantic_view_name": "SALES_SEMANTIC_VIEW", + "type": "RDBMS_SNOWFLAKE", + "description": "Semantic integration for the Sales Snowflake Semantic View" +}' +---- + +=== Example response + +[source,JSON] +---- +{ + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Sales Semantic View", + "model_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", + "model_name": "Sales Semantic View", + "semantic_report": { + "summary": { + "total": 5, + "imported": 4, + "failed": 0, + "skipped": 1 + }, + "formulas": [ + { + "id": "formula-guid-001", + "name": "Total Revenue", + "description": "Sum of all revenue", + "source_expression": "SUM(revenue)", + "translated_formula": "sum(revenue)", + "import_status": "IMPORTED", + "change_status": null + } + ] + } +} +---- + +[#search-semantic-integrations] +== Search semantic integrations + +To fetch a paginated list of semantic integrations matching the specified criteria, use the `/api/rest/2.0/semantic-integrations/search` API endpoint. Returns all integrations if no filters are specified. + +=== Request parameters + +[width="100%"] +[options="header"] +|===== +| Parameter | Type | Required | Description +| `pattern` | String | No | Substring filter to narrow search results by integration name. +| `author_identifiers` | Array | No | Filter by the GUID or username of the user who created the integration. +| `connection_identifiers` | Array | No | Filter by the GUID or name of the Snowflake connection associated with the integration. +| `sort_options` | Object | No | Sort configuration. See <<_sort_options>>. +| `record_offset` | Integer | No | Number of records to skip for pagination. Minimum: 0. Default: 0. +| `record_size` | Integer | No | Maximum number of records to return. Use `0` to return all records. Default: 10. +|===== + +[#sort-options] +==== Sort options + +[width="100%"] +[options="header"] +|===== +| Field | Type | Description +| `field_name` | String | Sort field. One of: `NAME`, `AUTHOR`, `CREATED_TIME`, `MODIFIED_TIME`. +| `order` | String | Sort direction. `ASC` for ascending, `DESC` for descending. +|===== + +=== Response fields + +Returns an array of objects, each with the following fields: + +[width="100%"] +[options="header"] +|===== +| Field | Type | Description +| `id` | String | GUID of the semantic integration. +| `name` | String | Display name of the semantic integration. +| `description` | String | Description of the semantic integration. Null if not set. +| `model_id` | String | GUID of the associated ThoughtSpot data model. +| `model_name` | String | Display name of the associated ThoughtSpot data model. +| `import_type` | String | How the semantic definition was sourced. `CDW` for Snowflake Semantic View; `FILE` for file upload. +| `type` | String | CDW connector type. Currently always `RDBMS_SNOWFLAKE`. +| `connection_id` | String | GUID of the Snowflake connection. +| `connection_name` | String | Display name of the Snowflake connection. +| `author_id` | String | GUID of the user who created the integration. +| `author_name` | String | Username of the user who created the integration. +| `creation_time_in_millis` | Float | Creation time in Unix epoch milliseconds. +| `modification_time_in_millis` | Float | Last modification time in Unix epoch milliseconds. +| `tags` | Array | Tags associated with the integration, each with `id` and `name`. +|===== + +=== Example request + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/semantic-integrations/search' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "connection_identifiers": [""], + "sort_options": { + "field_name": "MODIFIED_TIME", + "order": "DESC" + }, + "record_size": 20, + "record_offset": 0 +}' +---- + +[#import-semantic-integration] +== Import a semantic integration +To re-import semantic updates from the Snowflake CDW source for an existing integration, and rebuild the corresponding ThoughtSpot data model, send a `POST` request to the `/api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/import` API endpoint. Send this API request, after the source Snowflake Semantic View has been updated (formulas added, removed, or modified) to bring the ThoughtSpot model back in line with the CDW definition. + +[NOTE] +==== +Importing updates is not supported for integrations created using the file upload option in the ThoughtSpot UI. To refresh a file-upload-based integration, use the ThoughtSpot UI. +==== + +The import operation: + +* Preserves the integration GUID, name, and `model_id`. Only the formula set is refreshed. +* Returns the same `semantic_report` response as create, with an additional `change_status` per formula indicating whether each formula is `NEW`, `UPDATED`, or `UNCHANGED` since the previous import. + + +=== Path parameters + +[width="100%"] +[options="header"] +|===== +| Parameter | Type | Required | Description +| `semantic_integration_identifier` | String | Yes | GUID or name of the semantic integration to re-import. +|===== + +=== Response fields + +Same as <>, with the addition of the `change_status` field in each formula entry: + +[width="100%"] +[options="header"] +|===== +| `change_status` value | Description +| `NEW` | Formula is new since the previous import. +| `UPDATED` | Formula definition changed since the previous import. +| `UNCHANGED` | Formula is unchanged since the previous import. +|===== + +=== Example request + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/semantic-integrations/Sales%20Semantic%20View/import' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + --data-raw '{}' +---- + +=== Example response + +[source,JSON] +---- +{ + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Sales Semantic View", + "model_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", + "model_name": "Sales Semantic View", + "semantic_report": { + "summary": { + "total": 6, + "imported": 5, + "failed": 0, + "skipped": 1 + }, + "formulas": [ + { + "id": "formula-guid-001", + "name": "Total Revenue", + "description": "Sum of all revenue", + "source_expression": "SUM(revenue)", + "translated_formula": "sum(revenue)", + "import_status": "IMPORTED", + "change_status": "UNCHANGED" + }, + { + "id": "formula-guid-002", + "name": "Net Profit", + "description": "Revenue minus costs", + "source_expression": "SUM(revenue) - SUM(costs)", + "translated_formula": "sum(revenue) - sum(costs)", + "import_status": "IMPORTED", + "change_status": "NEW" + } + ] + } +} +---- + +[#delete-semantic-integration] +== Delete a semantic integration +To permanently delete the specified semantic integration and its generated ThoughtSpot data model from the system, use the `/api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/delete` API endpoint. + +[WARNING] +==== +Deletion is permanent and cannot be undone. If you need to restore the integration, use the `create` endpoint to re-import the Snowflake Semantic View. +==== + +=== Path parameters + +[width="100%"] +[options="header"] +|===== +| Parameter | Type | Required | Description +| `semantic_integration_identifier` | String | Yes | GUID or name of the semantic integration to delete. +|===== + +=== Example request + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/semantic-integrations/Sales%20Semantic%20View/delete' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + --data-raw '{}' +---- + +A successful delete returns HTTP `200` with an empty response body. + +== Error responses + +[width="100%"] +[options="header"] +|===== +| Code | Description +| 400 | Bad Request — required parameter missing or invalid value (for example, unsupported `type`). +| 401 | Unauthorized — authentication token missing, expired, or invalid. +| 403 | Forbidden — the caller lacks the required privilege. +| 404 | Not Found — no semantic integration exists with the given identifier. +|===== + +== Related resources + +* xref:connections.adoc[Data connections] +* xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog] +* xref:rest-api-v2-reference.adoc[REST API v2.0 reference] diff --git a/modules/ROOT/pages/spotter-agent-apis.adoc b/modules/ROOT/pages/spotter-agent-apis.adoc index 5ea2587af..b9a909ee3 100644 --- a/modules/ROOT/pages/spotter-agent-apis.adoc +++ b/modules/ROOT/pages/spotter-agent-apis.adoc @@ -61,7 +61,20 @@ a| `POST /api/rest/2.0/ai/relevant-questions/` [beta betaBackground]^Beta^ + xref:spotter-agent-apis.adoc#_get_relevant_questions[Decomposes a user query] into relevant sub-questions. Guides users to explore data more deeply for a comprehensive analysis. + __Available on ThoughtSpot Cloud instances from 10.13.0.cl onwards__. -a| `POST /api/rest/2.0/ai/agent/converse/sse` [.version-badge.deprecated]#Deprecated# + + + a| `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` [.version-badge.new]#New# + + xref:spotter-agent-apis.adoc#_share_a_conversation[Shares a saved Spotter conversation] with one or more users or groups. Use `grant` and `revoke` arrays to manage access. Shared conversations are `READ_ONLY`. + + __Available on ThoughtSpot Cloud instances from 26.9.0.cl onwards.__ + + a| `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content` [.version-badge.new]#New# + + xref:spotter-agent-apis.adoc#_get_shared_content[Returns the shared content] of a Spotter conversation, including messages and associated answers. + + __Available on ThoughtSpot Cloud instances from 26.9.0.cl onwards.__ + + a| `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info` [.version-badge.new]#New# + + xref:spotter-agent-apis.adoc#_get_share_information[Returns sharing metadata] for a Spotter conversation — the list of principals it is shared with and whether the shared content is outdated. + + __Available on ThoughtSpot Cloud instances from 26.9.0.cl onwards.__ + + a| `POST /api/rest/2.0/ai/agent/converse/sse` [.version-badge.deprecated]#Deprecated# + Legacy API endpoint for streaming responses, including tokens and visualizations, for a specific conversation context. __Deprecated in 26.5.0.cl__. @@ -1290,3 +1303,145 @@ Name of the associated data source object. * Visit the +++REST API v2.0 Playground+++ to view the API endpoints and verify the request and response workflows. * For information about MCP tools, see xref:mcp-integration.adoc[MCP server integration]. + + [#_sharing_spotter_conversations] + == Sharing Spotter conversations + + // SOURCE: SCAL-306173 (aug.26.mt) + // SOURCE: prism/src/public-apis/nl-to-answer.graphql (master) + + ThoughtSpot provides REST API v2.0 endpoints to share saved Spotter agent conversations with other users or groups. Shared conversations are always `READ_ONLY` — recipients can view conversation messages and associated answers but cannot send new queries or modify the conversation. + + === Supported endpoints + + [width="100%" cols="1"] + |===== + a| `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` [.version-badge.new]#New# + + xref:spotter-agent-apis.adoc#_share_a_conversation[Shares a saved Spotter conversation] with one or more users or groups. + + __Available on ThoughtSpot Cloud instances from 26.9.0.cl onwards.__ + + a| `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content` [.version-badge.new]#New# + + xref:spotter-agent-apis.adoc#_get_shared_content[Returns the shared content] of a Spotter conversation, including messages and associated answers. + + __Available on ThoughtSpot Cloud instances from 26.9.0.cl onwards.__ + + a| `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info` [.version-badge.new]#New# + + xref:spotter-agent-apis.adoc#_get_share_information[Returns sharing metadata] for a Spotter conversation — the list of principals it is shared with. + + __Available on ThoughtSpot Cloud instances from 26.9.0.cl onwards.__ + |===== + + [#_share_a_conversation] + === Share a conversation + + Use `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` to share a saved Spotter conversation with one or more principals. + + ==== Path parameters + + [width="100%" cols="2,4"] + [options="header"] + |===== + | Parameter | Description + | `conversation_identifier` | The GUID of the saved Spotter conversation to share. + |===== + + ==== Request body parameters + + [width="100%" cols="2,1,4"] + [options="header"] + |===== + | Parameter | Required | Description + | `grant` | No | Array of principal identifiers to grant access. Each entry is a `user_identifier` (username or GUID) or `group_identifier` (group name or GUID). All shared access is `READ_ONLY`. + | `revoke` | No | Array of principal identifiers to revoke access from. + | `refresh_shared_content` | No | Boolean. When `true`, regenerates the shared content snapshot. Default: `false`. + | `notify_on_share` | No | Boolean. When `true`, sends an in-app notification to principals receiving access. Default: `true`. Available from 26.10.0.cl. + |===== + + ==== Example request + + [source,cURL] + ---- + curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "grant": [ + {"user_identifier": "user@example.com"}, + {"group_identifier": "analysts-group"} + ], + "revoke": [], + "refresh_shared_content": false + }' + ---- + + [#_get_shared_content] + === Get shared content + + Use `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content` to retrieve the content of a shared Spotter conversation. + + ==== Path parameters + + [width="100%" cols="2,4"] + [options="header"] + |===== + | Parameter | Description + | `conversation_identifier` | The GUID of the shared Spotter conversation. + |===== + + ==== Response fields + + [width="100%" cols="2,4"] + [options="header"] + |===== + | Field | Description + | `conversation_id` | GUID of the original conversation. + | `shared_conversation_id` | GUID of the shared conversation snapshot. + | `messages` | Array of conversation messages included in the shared snapshot. + | `data_sources` | Array of data source identifiers used in the conversation. + | `code_execution_files` | Array of files generated by code execution steps, if any. + |===== + + ==== Example request + + [source,cURL] + ---- + curl -X GET \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/json' + ---- + + [#_get_share_information] + === Get share information + + Use `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info` to retrieve sharing metadata for a Spotter conversation. + + ==== Path parameters + + [width="100%" cols="2,4"] + [options="header"] + |===== + | Parameter | Description + | `conversation_identifier` | The GUID of the Spotter conversation. + |===== + + ==== Response fields + + [width="100%" cols="2,4"] + [options="header"] + |===== + | Field | Description + | `is_shared_content_outdated` | Boolean. `true` if the shared content snapshot is stale. Use the share endpoint with `refresh_shared_content: true` to regenerate. + | `principals` | Array of principal objects the conversation is shared with. Each entry includes the principal identifier and their access level (always `READ_ONLY`). + |===== + + ==== Example request + + [source,cURL] + ---- + curl -X GET \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/json' + ---- + \ No newline at end of file diff --git a/modules/ROOT/pages/whats-new.adoc b/modules/ROOT/pages/whats-new.adoc index 56a89557d..255551f87 100644 --- a/modules/ROOT/pages/whats-new.adoc +++ b/modules/ROOT/pages/whats-new.adoc @@ -22,6 +22,109 @@ This page lists new features, enhancements, and deprecated functionality introdu // *Status:* Current / Supported / Deprecated // *Affects:* Developers, Administrators, End Users // ============================================================ +== September 2026 + +**Release version**: ThoughtSpot Cloud 26.9.0.cl + +*Upgrade notes*: No breaking changes in this release. + +*Recommended SDK versions*: Visual Embed SDK v1.52.0 and later + +[.cl-table, cols="2,4", frame=none, grid=none] +|=== +a| +[.cl-label] +*Version 26.9.0.cl* + +a| +[discrete] +==== Browser history management in full application embedding +When ThoughtSpot is embedded in a host application, internal navigation pushes new entries onto the browser history stack, causing the browser *Back* button to step through ThoughtSpot's internal pages before returning to the host application. To override the browser history behavior for embedding application users and prevent users from getting trapped in back-button loops inside the embedded iframe environment, set `overrideHistoryState` in the Visual Embed SDK. + +--- + +[discrete] +==== Collections in embedded left navigation panel [.version-badge.new]#New# + +The `HomeLeftNavItem.Collections` value is now available in the Visual Embed SDK 1.52.0. Embed developers can include *Collections* as a navigation option in the left navigation panel for full application embeds, enabling end users to navigate to *Collections* directly from the embedded experience. For more information, see xref:full-app-customize.adoc[Customize the embedded ThoughtSpot experience]. + +--- + +[discrete] +==== Answer Export API — General Availability [.version-badge.new]#New# + +The Answer Export API (`POST /api/rest/2.0/report/answer`) is now generally available. This release introduces the following enhancements: + +* *Pinned Answer export*: Export a pinned visualization from a Liveboard directly using the `viz_guid` parameter. +* *Personalized View support*: Export data from a specific Personalized View using `personalised_view_identifier`. +* *Spotter Answer export*: Export Spotter-generated answers in `XLSX` and `PDF` formats in addition to `CSV` and `PNG`. +* *Custom PNG dimensions*: Control PNG export dimensions using `x_resolution` and `y_resolution` parameters (600-3840 px). +* *Scaling control*: Adjust chart element size in PNG exports using `scaling_factor` (80-400). + +For more information, see xref:data-report-v2-api.adoc#answer-report[Answer Report API]. + +--- + +[discrete] +==== Snowflake Semantic View integration APIs [.version-badge.new]#New# + +ThoughtSpot introduces four new REST API v2.0 endpoints to manage Snowflake Semantic View integrations programmatically without using the ThoughtSpot UI: + +* `POST /api/rest/2.0/semantic-integrations/create` +* `POST /api/rest/2.0/semantic-integrations/search` +* `POST /api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/import` +* `POST /api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/delete` + +Requires `ADMINISTRATION` or `DATAMANAGEMENT` privilege. For more information, see xref:semantic-integrations-api.adoc[Snowflake Semantic View integration APIs]. + +--- + +[discrete] +==== Spotter Memory — General Availability [.version-badge.new]#New# + +The Spotter memory feature is now generally available. The memory APIs (`POST /api/rest/2.0/ai/memory/import` and `POST /api/rest/2.0/ai/memory/export`) are enabled by default on all ThoughtSpot Cloud instances. Administrators can manage and audit Spotter's training data programmatically. For more information, see xref:spotter-agent-apis.adoc[Spotter agent APIs]. + +--- + +[discrete] +==== Spotter conversation sharing APIs [.version-badge.new]#New# + +ThoughtSpot introduces three new REST API v2.0 endpoints to share Spotter agent conversations programmatically: + +* `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` -- Share a conversation with users or groups with `READ_ONLY` access. +* `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content` -- Retrieve the shared messages and answers in a conversation. +* `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info` -- Retrieve the list of principals a conversation is shared with and their access levels. + +For more information, see xref:spotter-agent-apis.adoc#_sharing_spotter_conversations[Sharing Spotter conversations]. + +--- + +[discrete] +==== KPI sparkline setting in metadata search response [.version-badge.new]#New# + +The `POST /api/rest/2.0/metadata/search` response now includes the `isSparklineEnabled` field in the `AnswerSpecHeader` object for KPI chart type answers. This boolean field indicates whether the sparkline trend line is enabled for a given KPI visualization. + +--- + +[discrete] +==== Personalized Views TML portability — General Availability [.version-badge.new]#New# + +The Personalized Views TML portability feature introduced in Early Access in 26.8.0.cl is now generally available. The `author` and `obj_id` fields are fully supported in exported and imported Personalized View TML. Smart merge import logic is applied by default. For more information, see xref:tml.adoc#personalized-views-portability[Personalized Views portability]. + +--- + +[discrete] +==== Visual Embed SDK +The Visual Embed SDK version 1.52.0 introduces `overrideHistoryState` for browser history management in `AppEmbed` and `HomeLeftNavItem.Collections` for embedded left navigation. For more information, see the xref:api-changelog.adoc[Visual Embed SDK changelog]. + +--- + +[discrete] +==== REST API v2 +For information about REST API v2 enhancements in this release, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. + +--- + +|=== + == August 2026 **Release version**: ThoughtSpot Cloud 26.8.0.cl +