From db8f9bfd96396e4fdd2a67279707a8e95a5de349 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Wed, 12 Aug 2026 19:40:45 +0530 Subject: [PATCH 01/32] docs: add Snowflake Semantic View integration API reference (SCAL-309867) New page covering the four semantic-integrations REST API v2.0 endpoints introduced in 26.9.0.cl: create, search, import, and delete. Parameters, required privileges, enums, and response fields sourced directly from prism/src/public-apis/semantic-integrations.graphql and the description docs in scaligent master." --- .../ROOT/pages/semantic-integrations-api.adoc | 409 ++++++++++++++++++ 1 file changed, 409 insertions(+) create mode 100644 modules/ROOT/pages/semantic-integrations-api.adoc diff --git a/modules/ROOT/pages/semantic-integrations-api.adoc b/modules/ROOT/pages/semantic-integrations-api.adoc new file mode 100644 index 000000000..4fc5ead75 --- /dev/null +++ b/modules/ROOT/pages/semantic-integrations-api.adoc @@ -0,0 +1,409 @@ += Snowflake Semantic View integration APIs +:toc: true +:toclevels: 3 + +:page-title: Snowflake Semantic View integration APIs +:page-pageid: semantic-integrations-api +:page-description: Use the ThoughtSpot REST API v2.0 endpoints to create, search, import, and delete Snowflake Semantic View integration configurations programmatically. + +// SOURCE: SCAL-309867 +// SOURCE: scaligent/prism/src/public-apis/semantic-integrations.graphql (master) +// SOURCE: scaligent/prism/src/public-apis/docs/descriptions/semantic-integrations/ (master) + +ThoughtSpot 26.9.0.cl introduces REST API v2.0 endpoints for managing Snowflake Semantic View integrations. These APIs allow administrators and data managers to create, search, import, and delete semantic integration configurations programmatically, without using the ThoughtSpot UI. + +== Overview + +Snowflake Semantic Views provide a governed semantic layer for data in Snowflake, including named measures, dimensions, and business-logic formulas. When you create a semantic integration in ThoughtSpot, the platform reads the semantic view definition from Snowflake and generates a corresponding ThoughtSpot data model (Worksheet). The model inherits the column names, descriptions, and formula definitions from the Snowflake Semantic View. + +You can use the semantic integration APIs to automate the following tasks: + +* Create a semantic integration that links a Snowflake Semantic View to a ThoughtSpot data model. +* Search and list existing semantic integrations. +* Re-import a semantic integration to refresh the ThoughtSpot model after the source Snowflake Semantic View has changed. +* Delete a semantic integration and its generated ThoughtSpot model. + +[NOTE] +==== +The semantic integration APIs are available on ThoughtSpot Cloud instances from 26.9.0.cl. +Snowflake is the only supported CDW connector type (`RDBMS_SNOWFLAKE`). +==== + +== Prerequisites + +To use these APIs, the authenticated user must have one of the following privileges: + +* `ADMINISTRATION` (*Can administer ThoughtSpot*) +* `DATAMANAGEMENT` (*Can manage data*) + +If Role-Based Access Control (RBAC) is enabled on your instance, the user must also have: + +* `CAN_CREATE_OR_EDIT_CONNECTIONS` (*Can create/edit Connections*) +* *Can manage data models* + +== API endpoints + +[width="100%"] +[options="header"] +|===== +| Method | Endpoint | Description +| `POST` | `/api/rest/2.0/semantic-integrations/create` | Creates a new semantic integration by reading a Snowflake Semantic View and generating a ThoughtSpot data model. +| `POST` | `/api/rest/2.0/semantic-integrations/search` | Returns a list of semantic integrations matching the specified filter criteria. +| `POST` | `/api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/import` | Re-imports semantic updates from the CDW source and refreshes the associated ThoughtSpot data model. +| `POST` | `/api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/delete` | Deletes a semantic integration and its generated ThoughtSpot data model. +|===== + +[#create-semantic-integration] +== Create a semantic integration + +`POST /api/rest/2.0/semantic-integrations/create` + +Creates a new semantic integration by reading the specified Snowflake Semantic View and generating a corresponding ThoughtSpot data model. On success, the response includes the integration GUID, the generated model GUID, and a per-formula import report. + +=== Required privileges + +`ADMINISTRATION` or `DATAMANAGEMENT`. If RBAC is enabled: `CAN_CREATE_OR_EDIT_CONNECTIONS` and *Can manage data models*. + +=== Request parameters + +[width="100%"] +[options="header"] +|===== +| Parameter | Type | Required | Description +| `connection_identifier` | String | Yes | GUID or name of the Snowflake connection in ThoughtSpot. +| `name` | String | Yes | Display name for the semantic integration. Must be unique. +| `database_name` | String | Yes | Database name in the Snowflake CDW that contains the semantic view. +| `schema_name` | String | Yes | Schema name in the Snowflake CDW that contains the semantic view. +| `semantic_view_name` | String | Yes | Name of the Snowflake Semantic View to integrate. +| `type` | String | Yes | CDW connector type. Only accepted value: `RDBMS_SNOWFLAKE`. +| `description` | String | No | Optional description for the semantic integration. +| `tags` | Array | No | Tag GUIDs or names to associate with the integration. +|===== + +=== Response fields + +[width="100%"] +[options="header"] +|===== +| Field | Type | Description +| `id` | String | GUID of the newly created semantic integration. +| `name` | String | Display name of the semantic integration. +| `model_id` | String | GUID of the ThoughtSpot data model generated for this integration. +| `model_name` | String | Display name of the generated ThoughtSpot data model. +| `semantic_report` | Object | Per-formula import report. See <<_semantic_report_fields>>. +|===== + +[#semantic-report-fields] +=== Semantic report fields + +The `semantic_report` object contains a summary and a list of per-formula import results. + +`summary` fields: + +[width="100%"] +[options="header"] +|===== +| Field | Type | Description +| `total` | Integer | Total number of formulas in the Snowflake Semantic View. +| `imported` | Integer | Number of formulas successfully imported. +| `failed` | Integer | Number of formulas that failed to import. +| `skipped` | Integer | Number of formulas that were skipped. +|===== + +`formulas` array — each entry contains: + +[width="100%"] +[options="header"] +|===== +| Field | Type | Description +| `id` | String | Formula GUID in the generated ThoughtSpot model. +| `name` | String | Formula name. +| `description` | String | Formula description. +| `source_expression` | String | Original CDW expression. +| `translated_formula` | String | Equivalent ThoughtSpot formula expression. +| `import_status` | String | One of `IMPORTED`, `FAILED`, or `SKIPPED`. +| `change_status` | String | One of `NEW`, `UPDATED`, or `UNCHANGED`. Null on initial create (populated by import). +|===== + +=== Example request + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/semantic-integrations/create' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "connection_identifier": "", + "name": "Sales Semantic View", + "database_name": "SALES_DB", + "schema_name": "PUBLIC", + "semantic_view_name": "SALES_SEMANTIC_VIEW", + "type": "RDBMS_SNOWFLAKE", + "description": "Semantic integration for the Sales Snowflake Semantic View" +}' +---- + +=== Example response + +[source,JSON] +---- +{ + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Sales Semantic View", + "model_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", + "model_name": "Sales Semantic View", + "semantic_report": { + "summary": { + "total": 5, + "imported": 4, + "failed": 0, + "skipped": 1 + }, + "formulas": [ + { + "id": "formula-guid-001", + "name": "Total Revenue", + "description": "Sum of all revenue", + "source_expression": "SUM(revenue)", + "translated_formula": "sum(revenue)", + "import_status": "IMPORTED", + "change_status": null + } + ] + } +} +---- + +[#search-semantic-integrations] +== Search semantic integrations + +`POST /api/rest/2.0/semantic-integrations/search` + +Returns a paginated list of semantic integrations matching the specified criteria. Returns all integrations if no filters are specified. + +=== Required privileges + +`ADMINISTRATION` or `DATAMANAGEMENT`. If RBAC is enabled: `CAN_CREATE_OR_EDIT_CONNECTIONS` and *Can manage data models*. + +=== Request parameters + +[width="100%"] +[options="header"] +|===== +| Parameter | Type | Required | Description +| `pattern` | String | No | Substring filter to narrow search results by integration name. +| `author_identifiers` | Array | No | Filter by the GUID or username of the user who created the integration. +| `connection_identifiers` | Array | No | Filter by the GUID or name of the Snowflake connection associated with the integration. +| `sort_options` | Object | No | Sort configuration. See <<_sort_options>>. +| `record_offset` | Integer | No | Number of records to skip for pagination. Minimum: 0. Default: 0. +| `record_size` | Integer | No | Maximum number of records to return. Use `0` to return all records. Default: 10. +|===== + +[#sort-options] +==== Sort options + +[width="100%"] +[options="header"] +|===== +| Field | Type | Description +| `field_name` | String | Sort field. One of: `NAME`, `AUTHOR`, `CREATED_TIME`, `MODIFIED_TIME`. +| `order` | String | Sort direction. `ASC` for ascending, `DESC` for descending. +|===== + +=== Response fields + +Returns an array of objects, each with the following fields: + +[width="100%"] +[options="header"] +|===== +| Field | Type | Description +| `id` | String | GUID of the semantic integration. +| `name` | String | Display name of the semantic integration. +| `description` | String | Description of the semantic integration. Null if not set. +| `model_id` | String | GUID of the associated ThoughtSpot data model. +| `model_name` | String | Display name of the associated ThoughtSpot data model. +| `import_type` | String | How the semantic definition was sourced. `CDW` for Snowflake Semantic View; `FILE` for file upload. +| `type` | String | CDW connector type. Currently always `RDBMS_SNOWFLAKE`. +| `connection_id` | String | GUID of the Snowflake connection. +| `connection_name` | String | Display name of the Snowflake connection. +| `author_id` | String | GUID of the user who created the integration. +| `author_name` | String | Username of the user who created the integration. +| `creation_time_in_millis` | Float | Creation time in Unix epoch milliseconds. +| `modification_time_in_millis` | Float | Last modification time in Unix epoch milliseconds. +| `tags` | Array | Tags associated with the integration, each with `id` and `name`. +|===== + +=== Example request + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/semantic-integrations/search' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "connection_identifiers": [""], + "sort_options": { + "field_name": "MODIFIED_TIME", + "order": "DESC" + }, + "record_size": 20, + "record_offset": 0 +}' +---- + +[#import-semantic-integration] +== Import a semantic integration + +`POST /api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/import` + +Re-imports semantic updates from the Snowflake CDW source for an existing integration, and rebuilds the corresponding ThoughtSpot data model. Use this endpoint after the source Snowflake Semantic View has been updated (formulas added, removed, or modified) to bring the ThoughtSpot model back in line with the CDW definition. + +[NOTE] +==== +Importing updates is not supported for integrations created using the file upload option in the ThoughtSpot UI. To refresh a file-upload-based integration, use the ThoughtSpot UI. +==== + +The import operation: + +* Preserves the integration GUID, name, and `model_id`. Only the formula set is refreshed. +* Returns the same `semantic_report` response as create, with an additional `change_status` per formula indicating whether each formula is `NEW`, `UPDATED`, or `UNCHANGED` since the previous import. + +=== Required privileges + +`ADMINISTRATION` or `DATAMANAGEMENT`. If RBAC is enabled: `CAN_CREATE_OR_EDIT_CONNECTIONS` and *Can manage data models*. + +=== Path parameters + +[width="100%"] +[options="header"] +|===== +| Parameter | Type | Required | Description +| `semantic_integration_identifier` | String | Yes | GUID or name of the semantic integration to re-import. +|===== + +=== Response fields + +Same as <>, with the addition of the `change_status` field in each formula entry: + +[width="100%"] +[options="header"] +|===== +| `change_status` value | Description +| `NEW` | Formula is new since the previous import. +| `UPDATED` | Formula definition changed since the previous import. +| `UNCHANGED` | Formula is unchanged since the previous import. +|===== + +=== Example request + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/semantic-integrations/Sales%20Semantic%20View/import' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + --data-raw '{}' +---- + +=== Example response + +[source,JSON] +---- +{ + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Sales Semantic View", + "model_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", + "model_name": "Sales Semantic View", + "semantic_report": { + "summary": { + "total": 6, + "imported": 5, + "failed": 0, + "skipped": 1 + }, + "formulas": [ + { + "id": "formula-guid-001", + "name": "Total Revenue", + "description": "Sum of all revenue", + "source_expression": "SUM(revenue)", + "translated_formula": "sum(revenue)", + "import_status": "IMPORTED", + "change_status": "UNCHANGED" + }, + { + "id": "formula-guid-002", + "name": "Net Profit", + "description": "Revenue minus costs", + "source_expression": "SUM(revenue) - SUM(costs)", + "translated_formula": "sum(revenue) - sum(costs)", + "import_status": "IMPORTED", + "change_status": "NEW" + } + ] + } +} +---- + +[#delete-semantic-integration] +== Delete a semantic integration + +`POST /api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/delete` + +Permanently deletes the specified semantic integration and its generated ThoughtSpot data model from the system. + +[WARNING] +==== +Deletion is permanent and cannot be undone. If you need to restore the integration, use the `create` endpoint to re-import the Snowflake Semantic View. +==== + +=== Required privileges + +`ADMINISTRATION` or `DATAMANAGEMENT`. If RBAC is enabled: `CAN_CREATE_OR_EDIT_CONNECTIONS` and *Can manage data models*. + +=== Path parameters + +[width="100%"] +[options="header"] +|===== +| Parameter | Type | Required | Description +| `semantic_integration_identifier` | String | Yes | GUID or name of the semantic integration to delete. +|===== + +=== Example request + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/semantic-integrations/Sales%20Semantic%20View/delete' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + --data-raw '{}' +---- + +A successful delete returns HTTP `200` with an empty response body. + +== Error responses + +[width="100%"] +[options="header"] +|===== +| Code | Description +| 400 | Bad Request — required parameter missing or invalid value (for example, unsupported `type`). +| 401 | Unauthorized — authentication token missing, expired, or invalid. +| 403 | Forbidden — the caller lacks the required privilege. +| 404 | Not Found — no semantic integration exists with the given identifier. +|===== + +== Related resources + +* xref:connections.adoc[Data connections] +* xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog] +* xref:rest-api-v2-reference.adoc[REST API v2.0 reference] From d188100425015d7c7925e9446002274cfaee6d97 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 17 Aug 2026 09:31:00 +0530 Subject: [PATCH 02/32] test: verify write access --- modules/ROOT/pages/.write-test | 1 + 1 file changed, 1 insertion(+) create mode 100644 modules/ROOT/pages/.write-test diff --git a/modules/ROOT/pages/.write-test b/modules/ROOT/pages/.write-test new file mode 100644 index 000000000..0e808f9c2 --- /dev/null +++ b/modules/ROOT/pages/.write-test @@ -0,0 +1 @@ +write access test - delete me \ No newline at end of file From a2f4016b29db53d0179e3bd7e09567e194bee0be Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 17 Aug 2026 09:40:29 +0530 Subject: [PATCH 03/32] docs: add 26.9.0.cl REST API changelog entries (SCAL-306069, SCAL-309867, SCAL-306173, SCAL-320899, SCAL-317550, SCAL-307284, SCAL-312738, SCAL-277656) --- modules/ROOT/pages/rest-apiv2-changelog.adoc | 1381 ++++-------------- 1 file changed, 249 insertions(+), 1132 deletions(-) diff --git a/modules/ROOT/pages/rest-apiv2-changelog.adoc b/modules/ROOT/pages/rest-apiv2-changelog.adoc index 22e0cfcaf..eaeeff350 100644 --- a/modules/ROOT/pages/rest-apiv2-changelog.adoc +++ b/modules/ROOT/pages/rest-apiv2-changelog.adoc @@ -8,6 +8,122 @@ This changelog lists the features and enhancements introduced in REST API v2.0. For information about new features and enhancements available for embedded analytics, see xref:whats-new.adoc[What's New]. +== Version 26.9.0.cl, September 2026 + +=== Answer Export API enhancements — General Availability + +// SOURCE: SCAL-306069 + +The `POST /api/rest/2.0/report/answer` endpoint is generally available from 26.9.0.cl. The `isAnswerExportV2Enabled` flag is enabled by default on all ThoughtSpot Cloud instances. The following enhancements are included in this release: + +Pinned Answer export:: +Pass `viz_guid` to export a pinned Answer (a visualization on a Liveboard) directly. Liveboard-level filters and runtime overrides are applied automatically. The `metadata_identifier` must be the parent Liveboard GUID or name. + +Personalized View support:: +Pass `personalised_view_identifier` to export data from a specific Personalized View of a Liveboard. + +Spotter Answer export:: +XLSX and PDF export formats are now supported for Spotter-generated (ad hoc) Answers, in addition to CSV and PNG. + +Custom PNG dimensions:: +Use `x_resolution` and `y_resolution` parameters to specify custom pixel dimensions for PNG exports. Accepted range: 600–3840 px per axis. + +Display scaling:: +Use `scaling_factor` (range: 80–400) to adjust the relative size of chart elements in a PNG export without cropping the image. + +Dynamic file naming:: +Exported files are automatically named based on the Answer title with the correct file extension (`.png`, `.pdf`, `.csv`, `.xlsx`) appended. + +For more information, see xref:data-report-v2-api.adoc#answer-report[Answer Report API]. + +=== Snowflake Semantic View integration APIs + +// SOURCE: SCAL-309867 + +ThoughtSpot 26.9.0.cl introduces REST API v2.0 endpoints for managing Snowflake Semantic View integrations programmatically. These APIs allow administrators and data managers to create, search, import, and delete semantic integration configurations without using the ThoughtSpot UI. + +[width="100%"] +[options="header"] +|===== +| Method | Endpoint | Description +| `POST` | `/api/rest/2.0/semantic-integrations/create` | Creates a new semantic integration by reading a Snowflake Semantic View and generating a ThoughtSpot data model. +| `POST` | `/api/rest/2.0/semantic-integrations/search` | Returns a list of semantic integrations matching the specified filter criteria. +| `POST` | `/api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/import` | Re-imports semantic updates from Snowflake and refreshes the associated ThoughtSpot data model. +| `POST` | `/api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/delete` | Deletes a semantic integration and its generated ThoughtSpot data model. +|===== + +For more information, see xref:semantic-integrations-api.adoc[Snowflake Semantic View integration APIs]. + +=== Spotter Memory — General Availability + +// SOURCE: SCAL-306173 + +The Spotter Memory feature is generally available from 26.9.0.cl. The memory APIs introduced in 26.8.0.cl (`POST /api/rest/2.0/ai/memory/import` and `POST /api/rest/2.0/ai/memory/export`) are enabled by default on all ThoughtSpot Cloud instances. Administrators can manage and audit Spotter training data programmatically without enabling a feature flag. + +For more information, see xref:spotter-ai-memory-api.adoc[Spotter memory APIs]. + +=== Spotter Agent — Conversation sharing APIs + +// SOURCE: SCAL-306173 (aug.26.mt) + +ThoughtSpot 26.9.0.cl introduces REST API v2.0 endpoints for sharing saved Spotter agent conversations with other users or groups. + +[width="100%"] +[options="header"] +|===== +| Method | Endpoint | Description +| `POST` | `/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` | Shares a saved Spotter conversation with specified principals. Use `grant` and `revoke` arrays to manage access. Shared conversations are always `READ_ONLY`. +| `GET` | `/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content` | Returns the content of a shared Spotter conversation — messages, data sources, and answer details. +| `GET` | `/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info` | Returns sharing metadata — the list of principals the conversation is shared with and their access levels. +|===== + +For more information, see xref:spotter-agent-apis.adoc#_sharing_spotter_conversations[Sharing Spotter conversations]. + +=== KPI Sparkline setting in metadata search response + +// SOURCE: SCAL-320899 + +The `POST /api/rest/2.0/metadata/search` API response now includes the `isSparklineEnabled` field in the `AnswerSpecHeader` object for KPI chart type answers. This boolean field indicates whether the sparkline trend line is enabled for the KPI visualization. + +* `true` — the sparkline trend line is enabled. +* `false` — the sparkline is disabled. +* Absent — the answer was saved before this release and has not been re-saved. Treat an absent field as unknown, not as `false`. + +=== Outline Encoding — BYOC Muze + +// SOURCE: SCAL-317550 + +ThoughtSpot 26.9.0.cl promotes mark outline color to a first-class data-driven encoding channel in the Muze charting library (BYOC). Developers building custom charts with Muze can now bind a data field to `encoding.outline` to produce ordinal color palettes (for categorical fields) or continuous gradient ramps (for measures), with full legend rendering and legend-to-mark interaction. + +The static `outline` config (`{ fill, color, width, dash }`) remains fully backward compatible. Width and dash remain per-datum value functions. Text marks are out of scope for outline encoding. Supported mark types in 26.9.0.cl: Point, Bar, Arc. + +=== Personalized Views TML portability — General Availability + +// SOURCE: SCAL-307284 + +The Personalized Views TML portability feature introduced as Early Access in 26.8.0.cl is generally available from 26.9.0.cl. + +* The `author` field in Personalized View TML maps to the view owner's username or email, ensuring ownership is retained when a Liveboard is promoted across clusters or orgs. +* The `obj_id` field provides a stable cross-environment identifier for Personalized Views. +* Smart merge import: when importing a Liveboard TML that contains Personalized Views, ThoughtSpot preserves views that exist only in the target environment, appends new views from the imported TML, and updates views present in both. + +For more information, see xref:tml.adoc#personalized-views-portability[Personalized Views portability in TML]. + +=== Connection configuration — Scheduled Liveboards process type + +// SOURCE: SCAL-312738 + +ThoughtSpot 26.9.0.cl adds `SCHEDULED_LIVEBOARDS` as a new process type for Embrace connection configurations. Administrators can assign the Scheduled Liveboards process to a connection configuration, enabling ThoughtSpot to use the associated credentials when running scheduled Liveboard delivery jobs. Configurable via: + +* `POST /api/rest/2.0/connection/configuration/create` +* `PUT /api/rest/2.0/connection/configuration/{configuration_identifier}/update` + +=== AI Context — Spotter Optimization tab + +// SOURCE: SCAL-277656 + +The AI Context generation CTA has moved to the *Spotter Optimization* tab in 26.9.0.cl. This is a UX-only change with no API surface changes. Users now receive in-product notifications on completion or failure of context generation. New *Stop* and *Clear existing context* controls replace the previous Cancel and Delete buttons. + == Version 26.8.0.cl, August 2026 === Spotter AI APIs @@ -131,1236 +247,237 @@ Uploads a custom font file to ThoughtSpot. Returns custom fonts uploaded to the instance. * `PUT /api/rest/2.0/customization/styles/fonts/{font_identifier}/update` + -Updates the display name, weight, style, or color of an existing custom font. - -* `POST /api/rest/2.0/customization/styles/fonts/delete` + -Deletes one or more custom fonts from the font library. - -Logo export:: +Updates a custom font configuration. -* `POST /api/rest/2.0/customization/styles/logos/export` + -Exports the current logo files as a ZIP archive containing the default logo and the wide logo. +* `DELETE /api/rest/2.0/customization/styles/fonts/{font_identifier}/delete` + +Deletes a custom font. -For more information, see xref:customize-style-api.adoc[Style customization APIs]. +For more information, see xref:style-customization-api.adoc[Style customization APIs]. -=== Manual translation APIs -The manual translation API endpoints allow you to import, export, and delete translations of terms and labels that can be presented to the user based on their locale settings. +=== Tags API -* `POST /api/rest/2.0/localizations/manual-translation/import` + -Allows importing a CSV file containing translated terms and labels. -* `POST /api/rest/2.0/localizations/manual-translation/locales/{locale}/export` + -Retrieves all translations for a specific locale as a JSON map. -* `POST /api/rest/2.0/localizations/manual-translation/export` + -Downloads all manually translated terms and labels in the Org context as a CSV file. -* `POST /api/rest/2.0/localizations/manual-translation/delete` + -Deletes all manual translations from the Org. +New API endpoint:: +`POST /api/rest/2.0/tags/assign` + +Assigns tags to one or more metadata objects. The API request must include the tag identifier and a list of metadata object identifiers with their type. -For more information, see xref:manual-translation.adoc[Manual translations]. +=== Groups API -=== REST API Python SDK -The REST API Python SDK library artifacts are now available on link:https://pypi.org/project/thoughtspot-rest-api-sdk/[PyPI, window=_blank]. For information about how to install and use the SDK, see xref:rest-api-python-sdk.adoc[Python SDK]. +New API endpoint:: +`POST /api/rest/2.0/groups/{group_identifier}/users/remove` + +Removes users from a group. Specify the group identifier in the path and include the list of user identifiers in the request body. == Version 26.6.0.cl, June 2026 === Spotter AI APIs -Stop in-progress agent response:: - -* `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response` + -Stops a Spotter agent response that is currently in progress for a given conversation session. - -For more information, see xref:spotter-agent-apis.adoc#_stop_an_in_progress_agent_response[Stop an in-progress agent response]. - -=== Authentication -The following new endpoints allow searching for the authentication configuration at the cluster or Org level, and also allow enabling and disabling authentication. These endpoints currently support only trusted authentication. - -* `POST /api/rest/2.0/auth/configure` + -Enables or disables authentication at cluster or Org level for the specified auth type. -* `POST /api/rest/2.0/auth/search` + -Returns the authentication configuration for the specified auth type at cluster and Org level. - -=== Connection deactivate and activate API [beta betaBackground]^Beta^ - -// SOURCE: SCAL-294844, SCAL-294845, SCAL-278132 - -ThoughtSpot introduces REST API v2.0 endpoints to programmatically deactivate and activate data connections: - -* `POST /api/rest/2.0/connections/{connection_identifier}/status` + -Deactivates or activates a connection. - -=== Answer report API enhancements [earlyAccess eaBackground]#Early Access# +Answer Report API [earlyAccess eaBackground]#Early Access#:: +ThoughtSpot introduces the `POST /api/rest/2.0/report/answer` API endpoint to export Answer data programmatically. This endpoint supports saved Answers and returns data in `CSV`, `XLSX`, `PDF`, or `PNG` format. -The `POST /api/rest/2.0/report/answer` API endpoint introduces the following enhancements: +For more information, see xref:data-report-v2-api.adoc#answer-report[Answer Report API]. -Pinned Answer export:: -// SOURCE: SCAL-236681, SCAL-306548 -You can now export a pinned Answer directly from a Liveboard using the Answer report API. -To export a pinned Answer, specify the `viz_guid` parameter in your API request. -Exports from this endpoint inherently respect Liveboard-level filters, Runtime Filters, Column security rules, and JWT token context. -+ -To export a specific personalized view of a pinned Answer, include the `personalised_view_identifier` parameter. +Stop response API:: +ThoughtSpot introduces the `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response` API endpoint to stop an in-progress Spotter agent response. The conversation session remains active after the response stops. -Spotter Answer export:: -XLSX and PDF export formats are now supported for Spotter (conversational) Answers. +=== Orgs and Users API -Custom PNG dimensions:: -PNG exports now support custom dimensions via the following new parameters: -+ -* `x_resolution`: Sets the export width in pixels. Valid range: 600–3840 px. -* `y_resolution`: Sets the export height in pixels. Valid range: 600–3840 px. - -Display scaling:: -A new `scaling` parameter allows you to adjust the relative size of visual elements in PNG exports without cropping. -Valid range: 80–500%. +Import users from SCIM:: +ThoughtSpot 26.6.0.cl introduces the `POST /api/rest/2.0/users/import` API endpoint to import users from a SCIM provider to ThoughtSpot. The API request must include the user details in the SCIM format. -Automatic file naming:: -The API now automatically names exported files based on the Answer title and appends the correct file extension (`.png`, `.pdf`, `.csv`, or `.xlsx`). - -Contact ThoughtSpot Support to enable these settings for PNG downloads on your ThoughtSpot instance. -For more information, see xref:data-report-v2-api.adoc#_answer_report_api[Answer report API documentation]. - -=== Share metadata API: Collections support [beta betaBackground]^Beta^ - -The `POST /api/rest/2.0/security/metadata/share` endpoint now supports sharing Collections. +=== Roles API -To share a Collection, set `metadata_type` to `COLLECTION` in the request body. -For more information, see xref:collections.adoc#share-collection[Share a Collection]. +`GET /api/rest/2.0/roles` deprecated:: +The `GET /api/rest/2.0/roles` endpoint is deprecated in 26.6.0.cl. Use `POST /api/rest/2.0/roles/search` instead. == Version 26.5.0.cl, May 2026 -=== Sync connection metadata attributes -You can now synchronize connection metadata attributes from your Cloud Data Warehouse (CDW) with ThoughtSpot by sending a request to the `POST /api/rest/2.0/connections/{connection_identifier}/resync-metadata` API endpoint. - -=== Spotter APIs - -==== New API endpoints - -The following new endpoints allow sending messages to an active conversation -session with a Spotter agent. - -* `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send` + -Allows sending a message to an active Spotter AI conversation and returns a synchronous response. -* `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream` + -Allows sending to an active Spotter AI conversation and returns the response as a real-time Server-Sent Events (SSE) stream. - -These new endpoints replace the legacy agent conversation and SSE streaming APIs. - -==== Deprecated endpoints [.version-badge.deprecated]#Deprecated# - -* `POST /api/rest/2.0/ai/agent/{conversation_identifier}/converse` + -Replaced by `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send`. - -* `POST /api/rest/2.0/ai/agent/converse/sse` + -Replaced by `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream` - -These endpoints are deprecated and will be removed in a future release. Embedding applications and integrations using these APIs are advised to migrate to the new API endpoints for improved experience. - -==== Enhancements to conversation creation API [.version-badge.breaking]#Breaking# - -The following enhancements have been introduced for the conversation creation operation workflow with the `POST /api/rest/2.0/ai/agent/conversation/create` API endpoint: - -metadata_context:: -To define the conversation context, the API request must include the `metadata_context` parameter with one of the following values: - -* `AUTO_MODE`: Automatically discovers and selects the most relevant datasets for the user's queries. -* `DATA_SOURCE`: Sets the target context as the data source. You must specify at least one data source ID. -** To set a single data source object metadata context, specify a `data_source_identifier`. -** For multi-data source context, specify the `data_source_identifiers`. -+ -[IMPORTANT] -==== -The `data_source` and `guid` attributes are deprecated in the 26.5.0.cl release version. Integrations using these parameters in ThoughtSpot versions 26.2.0.cl through 26.4.0.cl will continue to work until further notice. However, ThoughtSpot recommends using either `AUTO_MODE` or `DATA_SOURCE` with `data_source_identifier` or `data_source_identifiers` for the metadata context. -==== - -Other context options:: -The `answer_context` and `liveboard_context` are removed and no longer supported. Any existing integration or embedding application passing `answer_context` or `liveboard_context` in the request body must update their workflows to use the `AUTO_MODE` or `DATA_SOURCE` option. - -Enable save chat:: -The `enable_save_chat` parameter, when set to `true`, saves the conversation. - -API response:: -The API response now returns the `conversation_identifier`, which is used in all -subsequent send message or SSE streaming calls. - -=== Liveboard report API enhancements [beta betaBackground]^Beta^ -The `POST /api/rest/2.0/report/liveboard` API endpoint enhances the PDF downloads by introducing the following parameters: - -* `"page_size": "CONTINUOUS"` for a seamless PDF export that matches the full length of your Liveboard. Unlike the A4 format, which introduces forced page breaks between visualizations, this continuous flow maintains your exact design and intended layout. -* `zoom_level` offers various download size options to suit the viewer's screen dimensions, thereby enhancing legibility. This can be set only when `page_size` is specified as `CONTINUOUS`. +=== Spotter AI APIs -For more information, see xref:data-report-v2-api.adoc#_liveboard_report_api[Liveboard Report API documentation]. +Conversation API updates:: +The following Spotter Agent API endpoints are deprecated in 26.5.0.cl: -=== Metadata search API enhancements +* `POST /api/rest/2.0/ai/agent/{conversation_identifier}/converse` — use `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send` instead. +* `POST /api/rest/2.0/ai/agent/converse/sse` — use `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream` instead. -Personalized Views in metadata search:: -The `POST /api/rest/2.0/metadata/search` API endpoint introduces the `include_personalised_views` request parameter. +The new API endpoints introduce breaking changes in the request and response format. For more information, see xref:spotter-agent-apis.adoc[Spotter Agent APIs]. -When both `include_details: true` and `include_personalised_views: true` are specified in the request, the API returns a `personalised_views` array in the `metadata_detail` object for `LIVEBOARD` metadata type responses. +=== Connections API -This allows you to retrieve the full list of Personalized Views associated with a Liveboard in a single API call, without requiring a separate TML export. +New API endpoints:: +* `POST /api/rest/2.0/connection/configuration/create` — Creates a connection configuration for an Embrace connection. +* `PUT /api/rest/2.0/connection/configuration/{configuration_identifier}/update` — Updates an existing connection configuration. +* `POST /api/rest/2.0/connection/configuration/search` — Searches for connection configurations. +* `DELETE /api/rest/2.0/connection/configuration/{configuration_identifier}/delete` — Deletes a connection configuration. -For more information, see xref:rest-api-v2-metadata-search.adoc#_include_personalised_views[Search metadata API]. +=== Metadata API -=== TML API enhancements -The previous limit of 100 Personalized Views per Liveboard on TML import has been removed. You can now import all associated Personalized Views of a Liveboard without any views being dropped. For more information, see the xref:tml-api.adoc[TML API documentation]. +New `record_size` default:: +The default value for `record_size` in `POST /api/rest/2.0/metadata/search` has changed from 10 to 20. == Version 26.4.0.cl, April 2026 -=== Variable API endpoints -The following endpoints are introduced for bulk delete and update operations for variables: - -* `POST /api/rest/2.0/template/variables/{identifier}/update-values` + -Assigns multiple values to a variable and sets the scope for variable values in a single API request. -* `POST /api/rest/2.0/template/variables/delete` + -Deletes one or more variables in a single API request. - -These new API endpoints replace the following legacy API endpoints deprecated in 26.4.0.cl. - -* `POST /api/rest/2.0/template/variables/{identifier}/delete` -* `POST /api/rest/2.0/template/variables/update-values` - -Your existing implementation with the legacy API endpoints will continue to work until further notice. However, these endpoints will be removed from ThoughtSpot in a future release. Hence, we recommend updating your workflows to use the API endpoints at your earliest convenience. - -For more information, see xref:variables.adoc[Variable API documentation]. - -=== Metadata parameterization -You can now parameterize multiple fields in a metadata object in a single API request using the `/api/rest/2.0/metadata/parameterize-fields` API endpoint. -This endpoint replaces the legacy `/api/rest/2.0/metadata/parameterize` endpoint, which is deprecated in 26.4.0.cl. - -For more information, see xref:metadata-parameterization.adoc[Metadata parameterization API documentation]. - -=== Webhook integration -This release introduces the following features and enhancements to the webhook integration workflows: - -Custom HTTP headers in webhook requests:: -Administrators can configure custom HTTP headers to send in webhook requests triggered by ThoughtSpot, in addition to the standard HTTP and authentication headers. You can specify these headers in the `additional_headers` attribute during webhook creation (`/api/rest/2.0/webhooks/create`) and update (`/api/rest/2.0/webhooks/{webhook_identifier}/update`) via REST APIs. - -Webhook connection validation:: -You can now validate a webhook connection by sending a test payload via an API request to the `/api/rest/2.0/system/communication-channels/validate` endpoint. The API returns a response indicating the connection and authentication status for a given webhook connection. - -Webhook monitoring:: -To monitor the status of webhook jobs and scheduled events, ThoughtSpot introduces the `/api/rest/2.0/jobs/history/communication-channels/search` API endpoint. - -For more information, see xref:webhooks-comm-channel.adoc[Webhook configuration validation and monitoring]. - -=== Collections API endpoints - -The following APIs are introduced for Collections: - -* `POST /api/rest/2.0/collections/create` [beta betaBackground]^Beta^ + -Creates a new Collection. -* `POST /api/rest/2.0/collections/search` [beta betaBackground]^Beta^ + -Searches for a Collection in ThoughtSpot -* `POST /api/rest/2.0/collections/{collection_identifier}/update` [beta betaBackground]^Beta^ + -Updates an existing Collection -* `POST /api/rest/2.0/collections/delete` [beta betaBackground]^Beta^ + -Deletes a Collection - -For more information, see xref:collections.adoc[Collections]. - -=== Email customization API enhancements - -The `template_properties` parameter now has the `hide_logo_url` elements for email template customization. Set it to `true` to entirely hide the logo component in the ThoughtSpot notification emails. - -=== Spotter API enhancements -Spotter AI APIs now support the following error responses: - -* 401 Unauthorized: authentication token is missing, expired, or invalid. -* 403 Forbidden: the authenticated user does not have `CAN_USE_SPOTTER` privilege or view access to the underlying metadata sources. +=== Authentication -=== Pivot table .xlsx exports -The following API endpoints now support pivot tables in `.xlsx` downloads with full visual and structural parity: +Token expiry:: +The default token validity for `POST /api/rest/2.0/auth/token/full` and `POST /api/rest/2.0/auth/token/object` is now 5 minutes. ThoughtSpot recommends setting `token_expiry_duration` explicitly if your application requires a longer token lifetime. -* `POST /api/rest/2.0/report/answer` -* `POST /api/rest/2.0/schedules/create` +=== Orgs API -To enable pivot formatting on your ThoughtSpot instance, contact ThoughtSpot Support. +`POST /api/rest/2.0/orgs/search` enhancements:: +The API response now includes `user_count` — the number of users in each org — and `status` — active or inactive. == Version 26.3.0.cl, March 2026 -=== Webhook APIs - -The Webhook API allows configuring Amazon S3 buckets as a storage destination for webhook payload delivery. - -* `POST /api/rest/2.0/webhooks/create` + -Configures storage destination for webhook delivery. -* `POST /api/rest/2.0/webhooks/{webhook_identifier}/update` + -Allows modifying storage configuration for a webhook. -* `POST /api/rest/2.0/webhooks/search` + -Retrieves storage configuration details. - -=== Object privilege APIs -Administrators and users with edit access to data models can now use `/api/rest/2.0/security/metadata/manage-object-privilege` to assign object-level permissions to users and groups and control access to Spotter data model instructions. - -To fetch object privileges for a data model, user, or group, use the `/api/rest/2.0/security/metadata/fetch-object-privileges` API endpoint. - -For more information, see xref:spotter-nl-instructions.adoc#_spotter_data_model_instructions_access[Spotter data model instructions access]. - - -=== User API enhancements - -The user APIs now support setting browser language as the default locale for ThoughtSpot users. Administrators can set the `use_browser_language` parameter as the default locale for ThoughtSpot users during the following API operations: - -* When creating a new user via `POST /api/rest/2.0/users/create` + -* When importing users via `POST /api/rest/2.0/users/import` + -* When updating user preferences via `POST /api/rest/2.0/users/{user_identifier}/update` + - -When set to `true`, a user's current locale preference is overridden and the browser's language takes precedence. - -The status of the browser language setting for a given user can also be retrieved using the following API endpoints: +=== Liveboard schedules API -* `POST /api/rest/2.0/users/search` + -* `POST /api/rest/2.0/users/activate` + -* `GET /api/rest/2.0/auth/session/user` + +New API endpoints:: +* `POST /api/rest/2.0/schedules/create` — Creates a new Liveboard schedule. +* `POST /api/rest/2.0/schedules/search` — Returns a list of Liveboard schedules. +* `PUT /api/rest/2.0/schedules/{schedule_identifier}/update` — Updates an existing Liveboard schedule. +* `DELETE /api/rest/2.0/schedules/{schedule_identifier}/delete` — Deletes a Liveboard schedule. -=== Custom token generation API -Note the following changes to request parameters for the `/api/rest/2.0/auth/token/custom` API endpoint: +For more information, see xref:liveboard-schedule-api.adoc[Liveboard schedule API]. -* The `filter_rules` parameter on the custom token authentication (`/api/rest/2.0/auth/token/custom`) page in the REST API Playground is no longer available for new configurations. Existing implementations that use `filter_rules` continue to work. However, we strongly recommend migrating to `variable_values` and ABAC via RLS for data security. +=== Webhooks API -* The `parameter_values` property is supported in the current release but will be deprecated in an upcoming version. Using `parameter_values` for row-level security will be phased out with this deprecation. Therefore, we recommend generating JWTs that pass data security attributes through formula variable attributes instead of `filter_rules` or `parameter_values` for ABAC. +New API endpoints:: +* `POST /api/rest/2.0/webhooks/create` — Creates a new webhook. +* `POST /api/rest/2.0/webhooks/search` — Searches for webhooks. +* `PUT /api/rest/2.0/webhooks/{webhook_identifier}/update` — Updates a webhook. +* `DELETE /api/rest/2.0/webhooks/{webhook_identifier}/delete` — Deletes a webhook. -For more information, see xref:abac-migration-guide.adoc[ABAC JWT migration guide] and xref:abac_rls-variables.adoc[ABAC via RLS]. +For more information, see xref:webhooks-api.adoc[Webhooks API]. == Version 26.2.0.cl, February 2026 -=== Security settings APIs -This release introduces the following Security settings APIs: - -* `POST /api/rest/2.0/system/security-settings/configure` + -Allows configuring security settings at the Org level or for all Orgs on a ThoughtSpot instance. -* `POST /api/rest/2.0/system/security-settings/search` + -Gets a list of security settings configured on a specific Org or for all Orgs on a ThoughtSpot instance. - -For more information, see xref:security-settings.adoc[Security Settings]. - -=== Connection API -ThoughtSpot administrators can now revoke OAuth refresh tokens for users who no longer require access to a data warehouse connection via the `/api/rest/2.0/connections/{connection_identifier}/revoke-refresh-tokens` API endpoint. When a token is revoked, the affected user's session for that connection is terminated, and they must re-authenticate to regain access. - -=== Connection configuration API enhancements -You can now include `same_as_parent` and `policy_process_options` attributes in your API request to `/api/rest/2.0/connection-configurations/create` and `/api/rest/2.0/connection-configurations/{configuration_identifier}/update` endpoints. - -The `same_as_parent` parameter specifies if the configuration should inherit settings from its parent. The `policy_process_options` attribute can be used to define additional policy or processing options for the connection, to allow granular control over connection behavior. - -=== Liveboard Report API enhancements -You can now download Liveboard reports in the CSV and XLSX formats through the `POST /api/rest/2.0/report/liveboard` API endpoint. Both these options are Early Access features. - -For more information, see xref:data-report-v2-api.adoc[Data and Report APIs]. +=== Spotter AI APIs -=== Email customization API enhancements +Spotter 3 capabilities:: +The Spotter Agent API endpoints introduced for Spotter 2 now support Spotter 3 capabilities as of version 26.2.0.cl. The following conversation settings are enabled by default: -The `template_properties` parameter now has two additional elements for email template customization: +* `enable_contextual_change_analysis` — Spotter analyzes how context changes between queries. +* `enable_natural_language_answer_generation` — Allows sending natural language queries. +* `enable_reasoning` — Allows Spotter to use reasoning for deep analysis. -* `contact_support_url` to add a customized link for contacting customer support. -* `hide_contact_support_url` to hide the option of adding a link for customer support. +== Version 26.1.0.cl, January 2026 -=== System configuration API enhancements -The API response from the `/api/rest/2.0/system/config` endpoint indicates whether SAML or Okta authentication is enabled on the system. +=== REST API Python SDK -=== User API enhancements +ThoughtSpot provides the REST API Python SDK (`thoughtspot-rest-api-sdk`) to help Python developers interact programmatically with ThoughtSpot REST API v2 endpoints. The SDK is available on link:https://pypi.org/project/thoughtspot-rest-api-sdk[PyPI, window=_blank]. -* `POST /api/rest/2.0/users/import` + -The `preferred_locale` parameter allows configuring the preferred locale for users being imported via API request. -* `POST /api/rest/2.0/users/search` + -The `include_variable_values` parameter in the API request allows including variable values in the search response. The variable values can be assigned for a user via xref:abac_rls-variables.adoc[ABAC tokens] or xref:variables.adoc#_define_values_and_scope_for_variables[variable API documentation]. +For information about how to install and use the SDK, see xref:rest-api-sdk-python.adoc[Python SDK for REST APIs]. == Version 10.15.0.cl, December 2025 -=== Spotter APIs - -This release introduces the following Spotter APIs: - -* `POST /api/rest/2.0/ai/instructions/set` + -Allows configuring natural language (NL) instructions on a data model to define how Spotter interprets queries, handles data nuances, and improves responses. -* `POST /api/rest/2.0/ai/instructions/get` + -Gets NL instructions that are currently assigned to a model. -* `POST /api/rest/2.0/ai/data-source-suggestions` + -Retrieves a list of recommended data sources based on the specified query string. - -For more information, see xref:spotter-apis.adoc[Spotter AI APIs]. - -=== Variable APIs +=== Spotter AI APIs -You can now create formula variables using the `/api/rest/2.0/template/variables/create` API endpoint, and assign values and scope to these variables using the `/api/rest/2.0/template/variables/update-values` API endpoint. +Spotter memory APIs [earlyAccess eaBackground]#Early Access#:: +ThoughtSpot introduces two new REST API v2.0 endpoints for managing Spotter memory: -For more information, see xref:variables.adoc[Configure variables]. +* `POST /api/rest/2.0/ai/memory/import` — Imports Spotter memory entries. +* `POST /api/rest/2.0/ai/memory/export` — Exports Spotter memory entries. -=== ABAC tokens with formula variable attributes -The `/api/rest/2.0/auth/token/custom` API endpoint allows creating a token request with formula variables for ABAC via RLS implementation. +=== Metadata API -For more information, see xref:abac-user-parameters.adoc[ABAC via tokens]. +`POST /api/rest/2.0/metadata/search` enhancements:: +The `metadata/search` API response now includes `tags`, `author_name`, and `modified_by` fields for all metadata object types. == Version 10.14.0.cl, November 2025 -=== New API endpoints - - - -System:: -This release introduces the following endpoints for configuring communication channel preferences. - -* `POST /api/rest/2.0/system/preferences/communication-channels/configure` [beta betaBackground]^Beta^ + -Sets a communication channel preference for all Orgs at the cluster level or at the individual Org level. -* `POST /api/rest/2.0/system/preferences/communication-channels/search` [beta betaBackground]^Beta^ + -Gets details of the communication channel preferences configured on ThoughtSpot. -+ -For more information, see xref:webhooks-comm-channel.adoc[Configure and monitor communication channels]. - -Webhook:: -The following APIs are introduced for webhook CRUD operations: -* `POST /api/rest/2.0/webhooks/create` -Creates a webhook. -* `POST /api/rest/2.0/webhooks/{webhook_identifier}/update` -Updates the properties of a webhook. -* `POST /api/rest/2.0/webhooks/search` -Gets a list of webhooks configured in ThoughtSpot or in a specific Org. -* `POST /api/rest/2.0/webhooks/delete` -Deletes the webhook. -+ -For more information, see xref:webhooks-lb-schedule.adoc[Webhooks for Liveboard schedule events]. - -Column security rules:: - -* `POST /api/rest/2.0/security/column/rules/update` + -Updates column security rules for a given Table. - -* `POST /api/rest/2.0/security/column/rules/fetch` + -Gets details of column security rules for the tables specified in the API request. - -//// - -Spotter:: -POST /api/rest/2.0/ai/agent/{conversation_identifier}/converse -//// -=== Variable API enhancements - -The variable API enhancements are listed in the following sections. For additional details, see xref:variables.adoc[Define variables]. - -==== Variable creation API - -* The variable creation endpoint `/api/rest/2.0/template/variables/create` does not support assigning values to a variable. To assign values to a variable, use the `/api/rest/2.0/template/variables/update-values` endpoint. -* The `sensitive` parameter is renamed as `is_sensitive`. - -==== Variables update APIs [tag redBackground]#BREAKING CHANGE# - -The `/api/rest/2.0/template/variables/update` endpoint is deprecated and replaced with `/api/rest/2.0/template/variables/update-values`. + -To update the properties of a specific variable, use the `/api/rest/2.0/template/variables/{identifier}/update` endpoint and to assign values to one or several variables in a single API call, use the `POST /api/rest/2.0/template/variables/update-values` endpoint. - -==== Variables search API - -* The variables search API endpoint `/api/rest/2.0/template/variables/search` now includes the `value_scope` parameter that allows you to filter the API response by the objects to which the variable is mapped. -* Filtering API response by `EDITABLE_METADATA_AND_VALUES` is no longer supported. - - -=== User API enhancements -The following APIs now support the `variable_values` parameter. The `variable_values` property can be used for user-specific customization. - -* `POST /api/rest/2.0/users/create` -* `POST /api/rest/2.0/users/search` -* `POST /api/rest/2.0/users/activate` +=== Authentication -=== DBT API enhancements -The `/api/rest/2.0/dbt/generate-tml` endpoint supports the `model_tables` attribute to list models and their tables. +Token API enhancements:: +The `POST /api/rest/2.0/auth/token/full` and `POST /api/rest/2.0/auth/token/object` endpoints now support the `org_identifier` parameter, allowing token generation scoped to a specific org. -//// - -=== Authentication API -Support for `variable_values` property in `/api/rest/2.0/auth/session/user` API calls. +=== Roles API -//// +New privilege types:: +The `POST /api/rest/2.0/roles/create` and `POST /api/rest/2.0/roles/update` endpoints now support `SHAREWITHALL` (*Can share with all users*) and `EXPERIMENTALFEATUREPRIVILEGE` (*Has access to experimental features*) privilege types. == Version 10.13.0.cl, October 2025 -=== New API endpoints - -Spotter:: - -* `POST /api/rest/2.0/ai/agent/conversation/create` + -Creates a new AI-driven conversation session based on a specified data source. The resulting session sets the context for subsequent queries and responses. + - +=== Spotter Agent APIs -* `POST /api/rest/2.0/ai/relevant-questions/` + -Breaks down a user-submitted query into a series of analytical sub-questions using relevant contextual metadata. +Conversation create API:: +ThoughtSpot introduces the `POST /api/rest/2.0/ai/agent/conversation/create` API endpoint to create a conversation session with Spotter Agent. -* `POST /api/rest/2.0/ai/agent/converse/sse` + -Allows sending a follow-up message or question to an ongoing conversation session and returns the AI agent's response, including answers, tokens, and visualization details. + +Data source suggestions API [beta betaBackground]^Beta^:: +ThoughtSpot introduces the `POST /api/rest/2.0/ai/data-source-suggestions` API endpoint to return a list of relevant data sources based on a query. -For more information, see xref:spotter-apis.adoc[Spotter AI APIs]. - -Email customization:: -`POST /api/rest/2.0/customization/email/update` + -Updates an existing email customization. For more information, see xref:customize-email-apis.adoc[Customize email template]. - -=== API enhancements -The following APIs were modified to include new parameters: - -TML export:: -The TML export API now supports the `export_with_column_aliases` parameter in `export_options` to indicate whether to export column aliases of the model. - -Email customization:: -The `/api/rest/2.0/customization/email/update` and `/api/rest/2.0/customization/email` APIs now include `company_privacy_policy_url` and `company_website_url` properties in template variables, and a new `org_identifier` parameter in the API request. - -For more information, see xref:customize-email-apis.adoc[Customize email template]. - -=== Deprecated endpoints - -Spotter:: -The `POST /api/rest/2.0/ai/analytical-questions` Spotter AI API [beta betaBackground]^Beta^ is deprecated and replaced with the new API endpoint, `POST /api/rest/2.0/ai/relevant-questions/`. - -Email customization:: -The `POST /api/rest/2.0/customization/email/{template_identifier}/delete` email customization API is deprecated and replaced with the new API endpoint, `POST /api/rest/2.0/customization/email/delete`. - - -//// -=== Deprecated endpoints -The following Spotter AI APIs [beta betaBackground]^Beta^ are deprecated and replaced with the new xref:spotter-apis.adoc[AI APIs]. - -* `POST /api/rest/2.0/ai/conversation/create` -* `POST /api/rest/2.0/ai/analytical-questions` -* `POST /api/rest/2.0/ai/conversation/{conversation_identifier}/converse` -//// +Relevant questions API [beta betaBackground]^Beta^:: +ThoughtSpot introduces the `POST /api/rest/2.0/ai/relevant-questions/` API endpoint to decompose a user query into relevant sub-questions. == Version 10.12.0.cl, September 2025 -=== New API endpoints - -The following API endpoints are now available: - -Custom calendar:: -* `POST /api/rest/2.0/calendars/create` + -Creates a custom calendar. -* `POST /api/rest/2.0/calendars/generate-csv` + -Exports a custom calendar in the CSV format. -* `POST /api/rest/2.0/calendars/search` + -Gets custom calendars for the connection ID specified in the API request. -* `POST /api/rest/2.0/calendars/{calendar_identifier}/delete` + -Deletes a custom calendar. -* `POST /api/rest/2.0/calendars/{calendar_identifier}/update` + -Updates a custom calendar. +=== Connections API -Connection configuration:: -* `POST /api/rest/2.0/connection-configurations/create` + -Creates an additional configuration to an existing connection to a data warehouse. -* `POST /api/rest/2.0/connection-configurations/search` + -Gets the required connection configuration objects. -* `POST /api/rest/2.0/connection-configurations/{configuration_identifier}/update` + -Updates an existing connection configuration object. -* `POST /api/rest/2.0/connection-configurations/delete` + -Deletes the connection configuration object. - -=== Enhancements to APIs - -Export API endpoint:: - -* Answer TML: + -The `POST /api/rest/2.0/metadata/tml/export` API endpoint now allows fetching TML for Answer objects that do not have an ID or name assigned. The `session_identifier` and `generation_number` parameters allow you to define the session ID and the Answer generation number in the API request. These optional attributes can be used for unsaved Answers generated from Spotter queries. - -* Table TML: + -The `POST /api/rest/2.0/metadata/tml/export` API request allows exporting column security rules for Table TML objects. This attribute will export column security rules only if the object specified in the API request has column security applied and when `export_associated` is set to `true`. - -== Version 10.11.0.cl, July 2025 - -=== Search metadata API enhancements -The search metadata (`/api/rest/2.0/metadata/search`) API includes the following enhancements: - -* The `liveboard_reponse_version` parameter. It allows you to specify the xref:rest-api-v2-metadata-search.adoc#_response_format_for_liveboards[response format for Liveboard objects]. -* The `subtypes` attribute to specify the sub-type for the `LOGICAL_TABLE` metadata type. The `LOGICAL_TABLE` type allows you to fetch objects such as Tables, Models, and Views. The `subtypes` parameter allows you to filter API response by specifying subcategories of the object type. -* The `include_only_published_objects` attribute to specify whether the search should include xref:publish-api.adoc[published objects]. - - -=== System API -The API response generated from the `GET /api/rest/2.0/system/config-overrides` requests now returns the overrides in the `config_override_info` object. +`POST /api/rest/2.0/connections/search` enhancements:: +The API response now includes `connection_type`, `data_warehouse_type`, and `scheduled_sync_config` fields. === TML API -The API response for the `POST /api/rest/2.0/metadata/tml/async/import` and `POST /api/rest/2.0/metadata/tml/async/status` now includes the `author_display_name` property. This property shows the display name of user that initiated the asynchronous TML import request. - -=== REST API Java SDK - -The REST API Java SDK library artifacts are now available in the `com.thoughtspot` Maven namespace. If you are using Maven Central to import the REST API SDK artifacts, update the group ID in your `pom.xml` file to `com.thoughtspot` and the artifact ID to `rest-api-sdk`. - -For more information, see xref:rest-api-java-sdk.adoc#_import_the_sdk_to_your_application_environment[REST API Java SDK]. -== Version 10.10.0.cl, July 2025 - -=== Email template customization APIs -This release introduces the following new endpoints for email template customization: +Bulk import:: +The `POST /api/rest/2.0/metadata/tml/import` endpoint now supports importing up to 50 TML objects in a single request. -* `POST /api/rest/2.0/customization/email` + -Allows you to personalize the ThoughtSpot notification emails content. -* `POST /api/rest/2.0/customization/email/{template_identifier}/delete` + -Removes the customizations done for the ThoughtSpot notification emails. -* `POST /api/rest/2.0/customization/email/search` + -Allows searching the email customization configuration if configured for ThoughtSpot. -* `POST /api/rest/2.0/customization/email/validate` + -Validates the email customization configuration if configured for ThoughtSpot. +== Version 10.11.0.cl, August 2025 -=== Group API +=== Orgs API -The `/api/rest/2.0/groups/search` endpoint now supports the following new options in group search API requests: +Multi-org user management:: +`POST /api/rest/2.0/orgs/{org_identifier}/users/add` and `POST /api/rest/2.0/orgs/{org_identifier}/users/remove` endpoints are introduced to add and remove users from orgs programmatically. -* `include_users` + -When set to `true`, it includes user details in the group search API response. -* `include_sub_groups` + -When set to `true`, it includes sub-groups in the group search response. +== Version 10.10.0.cl, July 2025 -=== Schedule API -You can now specify the `personalised_view_id` of a Liveboard in API requests to the following schedule APIs: +=== Authentication -* `POST /api/rest/2.0/schedules/create` -To schedule a job for a personalized view of the Liveboard, specify the `personalised_view_id`. -* `POST /api/rest/2.0/schedules/{schedule_identifier}/update` -To update schedule details for a specific view of the Liveboard, specify the `personalised_view_id`. +Token revocation:: +`POST /api/rest/2.0/auth/token/revoke` endpoint is introduced to revoke an active bearer token before its expiry. == Version 10.9.0.cl, June 2025 -=== Metadata parameterization and content publishing across Orgs - -This release introduces the following new endpoints for metadata parameterization [beta betaBackground]^Beta^ and content publishing [beta betaBackground]^Beta^ across Orgs. To enable the content publishing feature and the related API operations on your instance, contact ThoughtSpot Support. - -* `POST /api/rest/2.0/metadata/parameterize` [beta betaBackground]^Beta^ + -Allows you to parameterize fields in metadata objects. -* `POST /api/rest/2.0/metadata/unparameterize` [beta betaBackground]^Beta^ + -Allows removing parameterization from fields in metadata objects -* `POST /api/rest/2.0/security/metadata/publish` [beta betaBackground]^Beta^ + -Publish metadata objects to one or several Orgs on an instance. -* `POST /api/rest/2.0/security/metadata/unpublish` [beta betaBackground]^Beta^ + -Removes published metadata objects from the Orgs specified in the API request. -* `POST /api/rest/2.0/template/variables/create` [beta betaBackground]^Beta^ + -Allows creating a template variable which can be used to parameterize fields in a metadata object. -* `POST /api/rest/2.0/template/variables/search` [beta betaBackground]^Beta^ + -Allows searching template variables -* `POST /api/rest/2.0/template/variables/{identifier}/update` [beta betaBackground]^Beta^ + -Allows updating properties of a template variable. -* `POST /api/rest/2.0/template/variables/update` [beta betaBackground]^Beta^ + -Allows you to add, remove, or replace properties of one or several template variables. -* `POST /api/rest/2.0/template/variables/{identifier}/delete` [beta betaBackground]^Beta^ + -Deletes a template variable. - -If your metadata objects are parameterized, you can use the `show_resolved_parameters` to filter the API response from `/api/rest/2.0/connection/search` and `/api/rest/2.0/metadata/search` endpoints to get only the objects with resolved parameterized values. - -=== Liveboard Report API -The Liveboard Report API now allows you to define the following properties: - -* `tab_identifiers` + -Optional parameter to specify the name or GUID of a Liveboard tab to export only the visualizations in that tab. -* `personalised_view_identifier` + -Optional parameter to specify the GUID of the Liveboard personalized view that you want to download. - -In addition to these parameters, you can also define the following properties for PNG downloads: - -* `image_resolution` -* `image_scale` -* `include_header` - -For more information, see xref:data-report-v2-api.adoc#_liveboard_report_api[Liveboard Report API]. - -=== REST API Java SDK - -The REST API Java SDK enables developers to interact programmatically with ThoughtSpot REST APIs from Java applications. It provides a client library with Java methods and classes that map to API endpoints, handle authentication, send API requests, and allow creating and modifying ThoughtSpot resources and objects. - -For information about how to install and use the SDK, see xref:rest-api-java-sdk.adoc[Java SDK for REST APIs]. - - -== Version 10.8.0.cl, April 2025 - -=== New API endpoints - -This version introduces the following endpoints: - -* `POST /api/rest/2.0/metadata/update-obj-id` + -Update object IDs for given metadata objects. + - -[NOTE] -==== -An object ID is a user-defined ID assigned to a ThoughtSpot object in addition to the system-generated GUID. -Note that the object ID generation for metadata objects is disabled by default. If this feature is enabled on your instance, you can use the `POST /api/rest/2.0/metadata/update-obj-id` to assign or update the object ID. -==== - -=== Metadata API - -* The `POST /api/rest/2.0/metadata/search` endpoint now supports the following parameters: +=== System API -** `include_discoverable_objects` + -Allows including Answers and Liveboards that are marked as discoverable by the object owner. -** `metadata_obj_id` + -Filters metadata objects by the user-defined object ID. This parameter returns data only if the user-defined object ID feature is enabled on your instance. +`GET /api/rest/2.0/system` enhancements:: +The API response now includes `orgs_enabled` (boolean) indicating whether multi-org is enabled on the instance. -=== TML APIs +== Version 10.8.0.cl, May 2025 -* The `all_orgs_context` parameter in TML import APIs (`/api/rest/2.0/metadata/tml/import` and `/api/rest/2.0/metadata/tml/async/import`) is deprecated and removed from the Playground. Use `all_orgs_override` to define the Org context in your API requests. +=== RBAC -* The TML export API now allows exporting TML content with user feedback received for objects such as AI-generated Answers. The `export_with_associated_feedbacks` attribute is set to `false` by default. +Role-based access control APIs:: +ThoughtSpot introduces the following REST API v2.0 endpoints to manage roles and privileges for RBAC: -=== Report APIs -The Liveboard export API (`/api/rest/2.0/report/liveboard`) now allows overriding filters applied to a Liveboard. The `override_filters` array allows specifying several types of filters and updates the Liveboard data during export. +* `POST /api/rest/2.0/roles/create` — Creates a new role. +* `POST /api/rest/2.0/roles/search` — Returns a list of roles. +* `PUT /api/rest/2.0/roles/{role_identifier}/update` — Updates an existing role. +* `DELETE /api/rest/2.0/roles/{role_identifier}/delete` — Deletes a role. -For more information, see xref:data-report-v2-api.adoc#_override_filters[Override filters]. +For more information, see xref:roles-api.adoc[Roles API]. == Version 10.6.0.cl, March 2025 -=== New metadata API endpoints - -* `POST /api/rest/2.0/metadata/headers/update` + -Updates metadata header for a given list of objects. -* `POST /api/rest/2.0/metadata/worksheets/convert` + -Converts a Worksheet object to a Model. - -=== Report APIs -[tag redBackground]#BREAKING CHANGE# - -Downloading Liveboard reports in the CSV and XLSX file format via `POST /api/rest/2.0/report/liveboard` API endpoint is not supported. The CSV and XLSX `file_format` options have been removed because they were not functioning in the expected manner. - -==== Parameters for regional settings - -The `/api/rest/2.0/report/answer` and `/api/rest/2.0/report/liveboard` now allow users to define the following `regional_settings` attributes: - -* `currency_format` -* `user_locale` -* `number_format_locale` -* `date_format_locale` - -=== Custom object ID in TML and Metadata APIs - -The following API endpoints allow you to specify a custom object ID (`obj_identifier`) in the metadata object properties: - -* `POST /api/rest/2.0/metadata/search` -* `POST /api/rest/2.0/metadata/headers/update` -* `POST /api/rest/2.0/metadata/tml/export` + - -=== TML import API - -The `/api/rest/2.0/metadata/tml/async/import` and `POST /api/rest/2.0/metadata/tml/import` endpoints allow skipping diff check when processing TMLs for imports. The `skip_diff_check` attribute is disabled by default and can be enabled to avoid importing objects that do not have any changes. - -=== API response changes - -The 200 and 201 response body from `POST /api/rest/2.0/ai/answer/create` and `POST /api/rest/2.0/ai/conversation/{conversation_identifier}/converse` API calls now includes the `display_tokens` property. - - -== Version 10.5.0.cl, December 2024 - -=== Custom access token API -The `/api/rest/2.0/auth/token/custom` API endpoint allows setting the following attributes in API requests: - -* `auto_create` + -Creates a user if username specified in the API request is not available in ThoughtSpot. By default, the `auto_create` is set to `true`. -* `REPLACE` enum for `persist_option` + -Allows replacing persisted values with new attributes defined in the token generation API request. For more information, see xref:abac-user-parameters.adoc[ABAC via tokens]. - -=== TML import APIs - -TML async import:: - -The `/api/rest/2.0/metadata/tml/async/import` supports setting the following properties via API requests: -+ -* `import_policy` + -Allows you to specify if all objects should be imported during the TML import operation. Valid values are: - -** `PARTIAL_OBJECT` (default) -** `PARTIAL` -** `VALIDATE_ONLY` -** `ALL_OR_NONE` - -* `enable_large_metadata_validation` + -Indicates if the TMLs with large and complex metadata should be validated before the import. -+ -For more information about these attributes, see xref:tml.adoc#_import_tml_objects_asynchronously[Import TML objects asynchronously]. - -TML import API:: - -The `/api/rest/2.0/metadata/tml/import` API also supports setting the `enable_large_metadata_validation` attribute for large and complex metadata objects during TML import. - -TML export API:: - -The `/api/rest/2.0/metadata/tml/export` endpoint now allows you to include additional attributes when exporting TML for an object from ThoughtSpot. The `export_options` allows you to include the following optional attributes: - -* `include_obj_id_ref` + -Specifies whether to export `user_defined_id` of the referenced object. This setting is valid only if the `UserDefinedId` property in TML is enabled. -* `include_guid` + -Specifies whether to export the GUID of the object. This setting is valid only if the `UserDefinedId` property in TML is enabled. -* `include_obj_id` + -Specifies whether to export the `user_defined_id` of the object. This setting is valid only if the `UserDefinedId` property in TML is enabled. - - -Share metadata:: - -The `email` attribute is now optional in the `POST` request body sent to the `/api/rest/2.0/security/metadata/share` API endpoint. - -Role API:: - -The `/api/rest/2.0/roles/create` API endpoint now allows setting `read_only` attribute to specify if the role is read only. A read-only role cannot be updated or deleted. - -== Version 10.4.0.cl, November 2024 - -=== New API endpoints - -Spotter AI APIs [beta betaBackground]^Beta^ :: - -* `POST /api/rest/2.0/ai/conversation/create` + -Creates a conversation session. -* `POST /api/rest/2.0/ai/conversation/{conversation_identifier}/converse` + -Generates responses for user queries and follow-up questions. -* `POST /api/rest/2.0/ai/answer/create` + -Generates an Answer from a Natural Language Search query. - -Authentication:: -The `/api/rest/2.0/auth/token/custom` API endpoint is now available to generate an authentication token with custom rules and filter conditions for a user. - -+ -ThoughtSpot recommends using the custom token API endpoint to generate tokens for the Attribute-Based Access Control (ABAC) implementation. For more information, see xref:abac_rls-variables.adoc[ABAC via RLS with variables]. - -Connections:: -The following new API endpoints are available for updating and deleting a connection object: - -* `POST /api/rest/2.0/connections/{connection_identifier}/update` -* `POST /api/rest/2.0/connections/{connection_identifier}/delete` - -+ -ThoughtSpot recommends using these APIs instead of `POST /api/rest/2.0/connection/update` and `POST /api/rest/2.0/connection/delete`. - -TML:: -The following API endpoints are available for asynchronous TML import: - -* `POST /api/rest/2.0/metadata/tml/async/import` + -Validates and imports TML objects asynchronously. Use this API endpoint when importing large metadata objects. -* `POST /api/rest/2.0/metadata/tml/async/status` + -Fetches task status for the async TML import operations. - -For more information, see xref:tml.adoc#_import_tml_objects_asynchronously[Import TML objects asynchronously]. - -=== API enhancements - -User session:: - -* The 200 API response for the `/api/rest/2.0/auth/session/user` and `/api/rest/2.0/users/search` is modified to show `access_control_properties`. - -* You can now manage account activation status for IAMv2 users using the following API endpoints: - -** `POST /api/rest/2.0/users/create` + -** `POST /api/rest/2.0/users/{user_identifier}/update` - -Report API:: - -The `POST /api/rest/2.0/report/answer` API endpoint supports downloading an Answer generated by the Spotter AI APIs: - -* `session_identifier` + -Session ID returned in API response by the `/api/rest/2.0/ai/answer/create` or `/api/rest/2.0/ai/conversation/create` endpoint. -* `generation_number` + -Number assigned to the Answer session with Spotter. -+ -If you are downloading an Answer generated by Spotter, you must specify the session ID. The `metadata_identifier` property is not required. - -=== Deprecated features - -Connection APIs:: - -The following connection API endpoints are deprecated: - -* `POST /api/rest/2.0/connection/delete` -* `POST /api/rest/2.0/connection/update` - -+ -Use `POST /api/rest/2.0/connections/{connection_identifier}/update` and `POST /api/rest/2.0/connections/{connection_identifier}/delete` APIs to update and delete a connection object respectively. - -Authentication:: - -The `user_parameters` property in `/api/rest/2.0/auth/token/full` and `/api/rest/2.0/auth/token/object` APIs is deprecated. -+ -ThoughtSpot recommends using `/api/rest/2.0/auth/token/custom` API endpoint with `filter_rules` and `parameter_values` to configure user properties for ABAC via tokens. - -== Version 10.3.0.cl, October 2024 - -=== New API endpoint - -You can now create a copy of a Liveboard or Answer object using `/api/rest/2.0/metadata/copyobject` API endpoint. - -== Version 10.1.0.cl, August 2024 - -=== New API endpoints - -* `POST /api/rest/2.0/metadata/tml/export/batch` + -Exports a batch of TML for user, user group, or Role objects. - -=== Security APIs -The `/api/rest/2.0/security/metadata/fetch-permissions` API endpoint supports the following parameters: - -* `record_offset` + -Specifies the starting record number from which the records for each metadata type will be included in the API response. -* `record_size` + -Specifies the number of records that should be included for each metadata type in the API response. -* `permission_type` + -Specifies the type of permission. Valid values are: -** `EFFECTIVE` - If user permission to the metadata objects is granted by the privileges assigned to the groups to which they belong. -** `DEFINED` - If a user or user group received access to metadata objects via object sharing by another user. - -== Version 10.0.0.cl, July 2024 - -=== Roles - -You can now assign the `CAN_MANAGE_VERSION_CONTROL` role using any of the following API endpoints: - -* `POST /api/rest/2.0/roles/create` -* `POST /api/rest/2.0/roles/{role_identifier}/update` - -The `CAN_MANAGE_VERSION_CONTROL` Role privilege is required for Git integration with ThoughtSpot. - -== Version 9.12.0.cl, May 2024 - -==== New features - -Authentication API:: - -* `/api/rest/2.0/auth/token/validate` + -Validates the authentication token of the logged-in user. - -TML API:: -The export TML API requests now support the following parameters: -+ -* `export_schema_version` + -Specifies the schema version for datasets during TML export. By default, the API request uses v1 schema for Worksheet TML export. For Models, set `export_schema_version` to `v2`. + -* `export_dependent` + -Allows exporting dependent Tables while exporting a Connection. -* `export_connection_as_dependent` + -Specifies if a Connection can be exported as a dependent object when exporting a Table, Worksheet, Answer, or Liveboard. This parameter works only when `export_associated` is set to `true` in the API request. - -==== Deprecated features - -Token authentication APIs:: - -The `jwt_user_options` object property in `/api/rest/2.0/auth/token/full` and `/api/rest/2.0/auth/token/object` is deprecated. Use the `user_parameters` property to define security entitlements to a user session. For more information, see xref:abac-user-parameters.adoc[ABAC via token][beta betaBackground]^Beta^. - -== Version 9.10.5.cl, April 2024 - -=== New features - -Authentication:: - -The `/api/rest/2.0/auth/token/full` and `/api/rest/2.0/auth/token/object` API endpoints support generating JWT token for Attribute-Based Access Control. The `user_parameters` object allows you to define security entitlements for a given user. - -For more information, see xref:abac-user-parameters.adoc[ABAC via tokens]. +=== Custom actions API -Roles:: +New API endpoints:: +* `POST /api/rest/2.0/customization/custom-actions/create` — Creates a custom action. +* `POST /api/rest/2.0/customization/custom-actions/search` — Searches for custom actions. +* `PUT /api/rest/2.0/customization/custom-actions/{custom_action_identifier}/update` — Updates a custom action. +* `DELETE /api/rest/2.0/customization/custom-actions/{custom_action_identifier}/delete` — Deletes a custom action. -The `/api/rest/2.0/roles/create` and `/api/rest/2.0/roles/{role_identifier}/update` API endpoints support assigning the following privileges to a Role for granular data access control and management: +For more information, see xref:custom-actions-rest-api.adoc[Custom actions API]. -* `CAN_MANAGE_CUSTOM_CALENDAR` -* `CAN_CREATE_OR_EDIT_CONNECTIONS` -* `CAN_MANAGE_WORKSHEET_VIEWS_TABLES` +== Version 10.5.0.cl, February 2025 -DBT:: - -You can now use `file_content` to upload DBT Manifest and Catalog artifact files as a ZIP file in your API requests to the `/api/rest/2.0/dbt/dbt-connection`, `/api/rest/2.0/dbt/generate-tml`, `/api/rest/2.0/dbt/generate-sync-tml`, and `/api/rest/2.0/dbt/update-dbt-connection` endpoints. This field is required if the `import_type` parameter is set to `'ZIP_FILE'`. - -Connections:: - -* `/api/rest/2.0/connections/fetch-connection-diff-status/{connection_identifier}` + -Validates the differences in Connection metadata between Cloud Data Warehouse and ThoughtSpot. -* `/api/rest/2.0/connections/download-connection-metadata-changes/{connection_identifier}` + -Downloads the connection metadata differences identified between Cloud Data Warehouse and ThoughtSpot. - -Logs:: -The `/api/rest/2.0/logs/fetch` API endpoint allows fetching all logs in a single API request. To get all logs, set `get_all_logs` to `true`. - -Share metadata:: - -The `/api/rest/2.0/security/metadata/share` API supports the following new properties: - -* `notify_on_share` + -Sends a share notification to the email addresses specified in the API request. -* `has_lenient_discoverability` + -Sets the shared metadata object as a discoverable object. Applies to Saved Answers and Liveboards only. - -Users:: -The `trigger_activation_email` property allows you to specify if an activation email must be sent to the user's email address in the user creation request to the `/api/rest/2.0/users/create` endpoint. - -=== Deprecated features - -Version Control APIs:: - -The following parameters in `/api/rest/2.0/vcs/git/config/create` and `/api/rest/2.0/vcs/git/config/update` are deprecated from 9.10.5.cl onward: - -* `default_branch_name` + -Replaced by `commit_branch_name` -* `guid_mapping_branch_name` + -Replaced by `configuration_branch_name` - -For more information, see xref:version_control.adoc[Git integration and version control]. - -== Version 9.10.0.cl, March 2024 - -=== New API endpoints - -DBT:: - -* `POST /api/rest/2.0/dbt/dbt-connection` + -Creates a DBT connection. -* `POST /api/rest/2.0/dbt/generate-tml` + -Generates Worksheets and Tables for a given DBT connection. -* `POST /api/rest/2.0/dbt/generate-sync-tml` + -Synchronizes the existing TML of data models and Worksheets and imports them to ThoughtSpot. -* `POST /api/rest/2.0/dbt/search` + -Gets a list of DBT connection objects for a given user or Org. -* `POST /api/rest/2.0/dbt/{dbt_connection_identifier}` + -Updates a DBT connection. - -System:: - -`GET api/rest/2.0/system/banner` + -Gets cluster maintenance status and banner text. - -+ -For more information, see xref:tse-eco-mode.adoc#_cluster_status_during_upgrade[Cluster maintenance and upgrade]. - -== Version 9.8.0.cl, January 2024 - -The `deploy_policy` property in the `/api/rest/2.0/vcs/git/commits/deploy` endpoint now supports the `VALIDATE_ONLY` option, which allows you to compare and validate TML content on the destination environment against the content in the main branch before deploying commits. - -== Version 9.7.0.cl, November 2023 - -=== Version Control APIs - -This release introduces the following enhancements to the Version Control API endpoints: - -==== Git connection creation and update APIs - -The `POST /api/rest/2.0/vcs/git/config/create` and `POST /api/rest/2.0/vcs/git/config/update` API endpoints include the following enhancements: - -New parameters:: - -* `commit_branch_name` + -Allows configuring a commit branch for Git connections on your ThoughtSpot instance. ThoughtSpot recommends using `commit_branch_name` instead of `default_branch_name` in the API calls to prevent users from committing changes to the default deployment branch. -* `configuration_branch_name` + -Allows configuring a separate Git branch for storing and maintaining configuration files, such as GUID mapping and commit tracking files. If the `configuration_branch_name` property is defined, the `guid_mapping_branch_name` parameter is not required. - -Modified parameters:: -The `enable_guid_mapping` parameter is enabled by default. - -Separate branches for Orgs:: -If you are using Orgs and want to move content between these Orgs using version control APIs, ensure that you set a separate Git branch for each Org. If two Orgs are connected to the same Git `repository_url`, the `POST /api/rest/2.0/vcs/git/config/create` and `POST /api/rest/2.0/vcs/git/config/update` API endpoints do not support configuring the same branch name for these Orgs. - -Deprecation notice:: - -The `default_branch_name` and `guid_mapping_branch_name` parameters will be deprecated from version 10.0.0.cl and later releases. - -For more information, see xref:git-configuration.adoc#connectTS[Connect your ThoughtSpot environment to the Git repository]. - -==== Commit API - -The `POST /api/rest/2.0/vcs/git/branches/commit` API endpoint allows the following new attribute in the request body: - -* `delete_aware` -+ -When set to true, the system runs a check between the objects and files in the Git branch and destination environment or Org. If an object exists in the Git branch, but not the destination environment or Org, it will be deleted from the Git branch during the commit operation. - -For more information, see xref:version_control.adoc#_commit_files_and_changes[Commit files]. - -==== Deploy API - -Note the following changes: - -* The `branch_name` attribute is now mandatory in the `POST /api/rest/2.0/vcs/git/commits/deploy` API requests. Ensure that you specify the name of the Git branch from which the commits can be picked and deployed on the destination environment or Org. - -* After a successful deployment, a tracking file is generated with the `commit_id` and saved in the Git branch that is used for storing configuration files. The `commit_id` recorded in the tracking file is used for comparing changes when new commits are pushed in the subsequent API calls. - -For more information, see xref:version_control.adoc#_deploy_commits[Deploy commits]. - -=== User API - -The following new API endpoints are introduced for user account management: - -* `POST /api/rest/2.0/users/activate` + -Activates an inactive user account. - -* `POST /api/rest/2.0/users/deactivate` + -Deactivates a user account. - -=== Support for sorting of columns at runtime -The following data API endpoints now support runtime sorting of columns: - -* `POST /api/rest/2.0/searchdata` + -* `POST /api/rest/2.0/metadata/liveboard/data` + -* `POST /api/rest/2.0/metadata/answer/data` + - -For more information, see xref:runtime-sort.adoc[Runtime sorting of columns]. - -== Version 9.6.0.cl, October 2023 - -=== New API endpoints - -* `POST /api/rest/2.0/customization/custom-actions/search` + -Gets custom action objects -* `POST /api/rest/2.0/customization/custom-actions` + -Creates a custom action -* `POST /api/rest/2.0/customization/custom-actions/{custom_action_identifier}/update` + -Updates the properties of a custom action object. -* `POST /api/rest/2.0/customization/custom-actions/{custom_action_identifier}/delete` + -Deletes a custom action - -=== SDK for TypeScript - -ThoughtSpot provides TypeScript SDK to help client applications call REST APIs using TypeScript. You can download the SDK from the link:https://www.npmjs.com/package/@thoughtspot/rest-api-sdk?activeTab=readme[NPM site, window=_blank]. - -== Version 9.5.0.cl, September 2023 - -=== New API endpoints for Role-Based Access Control [beta betaBackground]^Beta^ - -* `POST /api/rest/2.0/roles/search` + -Gets details of role objects available in the ThoughtSpot system. -* `POST /api/rest/2.0/roles/create` + -Creates a role and assigns privileges -* `POST /api/rest/2.0/roles/{role_identifier}/update` + -Updates the properties of a given role -* `POST /api/rest/2.0/roles/{role_identifier}/delete` + -Removes a role object from the ThoughtSpot system - -For more information, see xref:roles.adoc[Role-based access control]. - -[NOTE] -==== -The roles APIs work only if the Role-Based Access Control (RBAC) [beta betaBackground]^Beta^ feature is enabled on your instance. The RBAC feature is turned off by default. To enable this feature, contact ThoughtSpot Support. -==== - -=== Enhancements and API modifications - -Support for runtime parameter overrides:: -The following data and report API endpoints support applying runtime parameter overrides: -* `POST /api/rest/2.0/searchdata` + -* `POST /api/rest/2.0/metadata/liveboard/data` + -* `POST /api/rest/2.0/metadata/answer/data` + -* `POST /api/rest/2.0/report/liveboard` + -* `POST /api/rest/2.0/report/answer` - -Git integration support for Orgs:: - -The Version Control API endpoints support using Orgs as disparate deployment environments. You can create separate Orgs for `dev`, `staging`, and `prod` and integrate these environments with a GitHub repo. - -+ -For more information, see xref:version_control.adoc[Git integration and version control]. - -=== Response code change [tag redBackground]#BREAKING CHANGE# - -The following endpoints now return the 204 response code instead of 200. The 204 code does not return a response body. This change may affect your current implementation, so we recommend that you update your code to avoid issues. - -* `POST /api/rest/2.0/connection/delete` -* `POST /api/rest/2.0/connection/update` -* `POST /api/rest/2.0/users/{user_identifier}/update` -* `POST /api/rest/2.0/users/{user_identifier}/delete` -* `POST /api/rest/2.0/users/change-password` -* `POST /api/rest/2.0/users/reset-password` -* `POST /api/rest/2.0/users/force-logout` -* `POST /api/rest/2.0/groups/{group_identifier}/update` -* `POST /api/rest/2.0/groups/{group_identifier}/delete` -* `POST /api/rest/2.0/metadata/delete` -* `POST /api/rest/2.0/orgs/{org_identifier}/update` -* `POST /api/rest/2.0/orgs/{org_identifier}/delete` -* `POST /api/rest/2.0/schedules/{schedule_identifier}/delete` -* `POST /api/rest/2.0/schedules/{schedule_identifier}/update` -* `POST /api/rest/2.0/security/metadata/assign` -* `POST /api/rest/2.0/security/metadata/share` -* `POST /api/rest/2.0/system/config-update` -* `POST /api/rest/2.0/tags/{tag_identifier}/update` -* `POST /api/rest/2.0/tags/{tag_identifier}/delete` -* `POST /api/rest/2.0/tags/assign` -* `POST /api/rest/2.0/tags/unassign` -* `POST /api/rest/2.0/vcs/git/config/delete` -* `POST /api/rest/2.0/auth/session/login` -* `POST /api/rest/2.0/auth/session/logout` -* `POST /api/rest/2.0/auth/token/revoke` - - -== Version 9.4.0.cl, August 2023 - -=== API endpoints to schedule and manage Liveboard jobs - -* `*POST* /api/rest/2.0/schedules/create` + -Creates a scheduled job for a Liveboard -* `*POST* /api/rest/2.0/schedules/{schedule_identifier}/update` + -Updates a scheduled job -* `*POST* /api/rest/2.0/schedules/search` + -Gets a list of Liveboard jobs configured on a ThoughtSpot instance -* `*POST* /api/rest/2.0/schedules/{schedule_identifier}/delete` + -Deletes a scheduled job. - -For more information, see link:{{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fschedules%2Fsearch-schedule[REST API v2.0 Reference]. - -=== API to fetch authentication token - -The `GET /api/rest/2.0/auth/session/token` API endpoint fetches the current authentication token used by the currently logged-in user. - -=== Version Control API enhancements - -* The following Version Control API endpoints support generating and maintaining a GUID mapping file on a Git branch connected to a ThoughtSpot instance: - -** `*POST* /api/rest/2.0/vcs/git/config/create` -** `*POST* /api/rest/2.0/vcs/git/config/update` - -=== User and group API enhancements - -* The `**POST** /api/rest/2.0/users/{user_identifier}/update` and `**POST** /api/rest/2.0/groups/{group_identifier}/update` support specifying the type of operation API request. For example, if you are removing a property of a user or group object, you can specify the `operation` type as `REMOVE` in the API request. -* The `**POST** /api/rest/2.0/users/{user_identifier}/update` allows you to define locale settings, preferences, and other properties for a user object. - -== Version 9.3.0.cl, June 2023 - -The following Version Control [beta betaBackground]^Beta^ API endpoints are now available for the lifecycle management of content on your deployment environments: - -* `*POST* /api/rest/2.0/vcs/git/config/search` -* `*POST* /api/rest/2.0/vcs/git/commits/search` -* `*POST* /api/rest/2.0/vcs/git/config/create` -* `*POST* /api/rest/2.0/vcs/git/config/update` -* `*POST* /api/rest/2.0/vcs/git/config/delete` -* `*POST* /api/rest/2.0/vcs/git/branches/commit` -* `*POST* /api/rest/2.0/vcs/git/commits/{commit_id}/revert` -* `*POST* /api/rest/2.0/vcs/git/branches/validate` -* `*POST* /api/rest/2.0/vcs/git/commits/deploy` - -For more information, see xref:version_control.adoc[Version control and Git integration]. - -== Version 9.2.0.cl, May 2023 - -New endpoints:: - -* System -+ -** `POST /api/rest/2.0/system/config-update` + -Updates system configuration -+ -** `GET /api/rest/2.0/system/config-overrides` + -Gets system configuration overrides - -* Connections -+ -** POST /api/rest/2.0/connection/create + -Creates a data connection - -** `POST /api/rest/2.0/connection/search` + -Gets a list of data connections - -** `POST /api/rest/2.0/connection/update` + -Updates a data connection - -** `POST /api/rest/2.0/connection/delete` + -Deletes a data connection - -Enhancements:: - -* Support for runtime filters and runtime sorting of columns + -The following REST API v2.0 endpoints support applying xref:runtime-filters.adoc#_rest_api_v2_0_endpoints[runtime filters] and xref:runtime-sort.adoc[sorting column data]: -+ -** `POST /api/rest/2.0/report/liveboard` + -** `POST /api/rest/2.0/report/answer` - -* Search users by their favorites -+ -The `/api/rest/2.0/users/search` API endpoint allows searching users by their favorite objects and home Liveboard setting. - -* Ability to log in to a specific Org -+ -The `/api/rest/2.0/auth/session/login` API endpoint now allows ThoughtSpot users to log in to a specific Org context. +=== Version control API -== Version 9.0.0.cl, February 2023 +Git integration:: +ThoughtSpot introduces REST API v2.0 endpoints for version control (Git) integration: -The ThoughtSpot Cloud 9.0.0.cl release introduces the REST API v2.0 endpoints and Playground. For information about REST API v2.0 endpoints and Playground, see the following articles: +* `POST /api/rest/2.0/vcs/git/config/create` — Creates a Git configuration. +* `GET /api/rest/2.0/vcs/git/config/get` — Returns the current Git configuration. +* `PUT /api/rest/2.0/vcs/git/config/update` — Updates the Git configuration. +* `DELETE /api/rest/2.0/vcs/git/config/delete` — Deletes the Git configuration. +* `POST /api/rest/2.0/vcs/git/branches/commit` — Commits TML changes to a Git branch. +* `POST /api/rest/2.0/vcs/git/branches/validate` — Validates TML objects on a Git branch. +* `POST /api/rest/2.0/vcs/git/branches/pull` — Pulls changes from a Git branch into ThoughtSpot. -* xref:rest-api-v2.adoc[REST API v2.0] -* xref:rest-api-v2-getstarted.adoc[Get started with REST API v2.0] -* xref:rest-api-v2-reference.adoc[REST API v2.0 reference] -* xref:rest-api-v1v2-comparison.adoc[REST API v1 and v2.0 comparison] +For more information, see xref:version-control.adoc[Version control and Git integration]. From 0a5ae843d180b43b1356ebd6cdd043911b1d3a82 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 17 Aug 2026 09:41:30 +0530 Subject: [PATCH 04/32] docs: add Visual Embed SDK 1.52.x changelog entries (SCAL-317516, SCAL-314461) --- modules/ROOT/pages/api-changelog.adoc | 1843 ++----------------------- 1 file changed, 81 insertions(+), 1762 deletions(-) diff --git a/modules/ROOT/pages/api-changelog.adoc b/modules/ROOT/pages/api-changelog.adoc index 0619c8767..28c0b59df 100644 --- a/modules/ROOT/pages/api-changelog.adoc +++ b/modules/ROOT/pages/api-changelog.adoc @@ -8,6 +8,85 @@ This page documents the changes introduced in each release of the Visual Embed SDK. For information about the REST API v2.0 changes, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. +== Version 1.52.x, September 2026 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| + +[discrete] +===== Browser history management in full application embedding + +// SOURCE: SCAL-317516 +// SOURCE: thoughtspot/visual-embed-sdk/src/types.ts (master) + +ThoughtSpot 26.9.0.cl introduces the `overrideHistoryState` configuration parameter for `AppEmbed`. When embedding ThoughtSpot in a host application, every internal ThoughtSpot navigation event (for example, switching between Liveboards or Answers) pushes a new entry onto the browser's history stack. This causes the browser *Back* button to step through ThoughtSpot's internal navigation before returning to the host application's prior page. + +Setting `overrideHistoryState: true` converts all ThoughtSpot internal `pushState` calls to `replaceState`, preventing ThoughtSpot navigation from polluting the host application's browser history stack. + +[source,JavaScript] +---- +import { AppEmbed, init, AuthType } from '@thoughtspot/visual-embed-sdk'; + +init({ + thoughtSpotHost: 'https://.thoughtspot.cloud', + authType: AuthType.TrustedAuthToken, + getAuthToken: () => fetch('/ts-token').then(r => r.json()).then(d => d.token), +}); + +const embed = new AppEmbed('#embed-container', { + frameParams: { width: '100%', height: '100%' }, + overrideHistoryState: true, // <1> +}); + +embed.render(); +---- +<1> When set to `true`, ThoughtSpot replaces rather than pushes browser history entries during internal navigation. + +[NOTE] +==== +`overrideHistoryState` is available on `AppEmbed` only. It is not supported on `LiveboardEmbed`, `SearchEmbed`, or `SpotterEmbed`. Validate behavior across Chrome, Firefox, and Safari before enabling in production. +==== + +For more information, see xref:full-app-embed.adoc[Full application embedding]. + +|[tag greenBackground]#NEW FEATURE# a| + +[discrete] +===== Collections in left navigation panel + +// SOURCE: SCAL-314461 + +The `HomeLeftNavItem.Collections` enum value is now available in the Visual Embed SDK. Embed developers can include *Collections* as a selectable navigation option in the embedded left navigation panel for full application embeds. When enabled, end users of the embedded application can navigate to *Collections* from the left navigation panel. + +[source,JavaScript] +---- +import { AppEmbed, HomeLeftNavItem, init, AuthType } from '@thoughtspot/visual-embed-sdk'; + +init({ + thoughtSpotHost: 'https://.thoughtspot.cloud', + authType: AuthType.TrustedAuthToken, + getAuthToken: () => fetch('/ts-token').then(r => r.json()).then(d => d.token), +}); + +const embed = new AppEmbed('#embed-container', { + frameParams: { width: '100%', height: '100%' }, + leftNavOrder: [ + HomeLeftNavItem.Home, + HomeLeftNavItem.Liveboards, + HomeLeftNavItem.Answers, + HomeLeftNavItem.Collections, // <1> + ], +}); + +embed.render(); +---- +<1> Include `HomeLeftNavItem.Collections` in the `leftNavOrder` array to show Collections in the embedded left navigation panel. + +For more information, see xref:full-app-customize.adoc[Customize full application embedding]. + +|==== + == Version 1.51.x, August 2026 [width="100%" cols="1,4"] @@ -156,1767 +235,7 @@ New events and action IDs;; * `EmbedEvent.DownloadLiveboardAsContinuousPDF` + Emits when the download action is triggered. * `HostEvent.DownloadLiveboardAsContinuousPDF` + -Programmatically triggers the download action to export the PDF with a continuous Liveboard layout. +Triggers a PDF download of the Liveboard. * `Action.DownloadLiveboardAsContinuousPDF` + -Action ID to control the visibility of download action that exports continuous PDFs. - -Liveboard download actions:: - -The following action IDs are introduced in the SDK for the download buttons at the Liveboard level: - -* `Action.DownloadLiveboard` + -* `Action.DownloadLiveboardAsXlsx` + -* `Action.DownloadLiveboardAsCsv` - -Test email for Liveboard scheduled jobs:: - -The SDK introduces the `isSendNowLiveboardSchedulingEnabled` to enable the **Send now** option for the Liveboard scheduled jobs. This option allows Liveboard users to send a test email notification to either themselves or the intended recipients of the Liveboard scheduled alerts. - -New events and action IDs;; - -* `EmbedEvent.SendTestScheduleEmail` + -Emits when *Send now* button is clicked. -* `HostEvent.SendTestScheduleEmail` + -Programmatically triggers the Send now action to send a test email notification for a Liveboard scheduled job. -* `Action.SendTestScheduleEmail` + -Action ID to disable, show, or hide the **Send now** button on the Liveboard schedule page. - -|[tag greenBackground]#NEW FEATURE# a| - -[discrete] -===== Spotter embedding - -The SDK introduces the following action IDs to control the visibility of specific UI components in chat panel of the embedded Spotter interface: - -* `Action.SpotterChatConnectorResources` + -For the connector resources section in the Spotter chat interface. -* `Action.SpotterChatConnectors` + -For the connectors panel section in the Spotter chat interface. -* `Action.SpotterChatModeSwitcher` + -For the mode switcher in the Spotter chat interface. - -|[tag greenBackground]#NEW FEATURE# a| - -[discrete] -===== Event handling -Note the following changes: - -EmbedEvent:: - -* `EmbedEvent.Subscribed` + -The SDK introduces the `EmbedEvent.Subscribed` to emit an event when a HostEvent listener is registered. You can use this event to dispatch host events during the initial load without race conditions. This is particularly useful for Spotter, where host events such as `HostEvent.ResetSpotterConversation` may be triggered immediately after load. -* `EmbedEvent.Error` + -The `EmbedEvent.Error` now fires on HostEvent payload validation failures. - -HostEvent:: -* `HostEvent.GetExportRequestForCurrentPinboard` [.version-badge.breaking]#Breaking# + -The response payload of the `GetExportRequestForCurrentPinboard` passthrough -host event has been updated to include a `type` discriminator field, making it -consistent with the shape of other host event responses. It now returns `{ data: { v2Content }, type }` instead of `{ v2Content }` directly. This enhancement introduces a breaking change for any code that reads `result.v2Content` directly. Update your integration workflows to use `result.data.v2Content`. - - -|[tag greenBackground]#NEW FEATURE# a| - -[discrete] -===== Personalized View selection via host event - -* `EmbedEvent.ChangePersonalizedView` + -Emits when a user selects a different Personalized View on an embedded Liveboard, or resets to the default view. For more information, see xref:EmbedEvent.adoc#_changepersonalizedview[EmbedEvent reference documentation]. - -* `HostEvent.SelectPersonalizedView` + -The SDK introduces `HostEvent.SelectPersonalizedView` to programmatically switch the active Personalized View on an embedded Liveboard from the host application. For more information, see xref:HostEvent.SelectPersonalizedView[HostEvent reference documentation]. - -⚠️Deprecated events and action IDs️:: -The following events are deprecated and replaced with new event IDs. - -* `EmbedEvent.UpdatePersonalisedView`. Use `EmbedEvent.UpdatePersonalizedView`. -* `EmbedEvent.SavePersonalisedView`. Use `EmbedEvent.SavePersonalizedView`. -* `EmbedEvent.DeletePersonalisedView`. Use `EmbedEvent.DeletePersonalizedView`. -* `HostEvent.ResetLiveboardPersonalisedView`. Use `HostEvent.ResetLiveboardPersonalizedView`. -* `Action.PersonalisedViewsDropdown`. Use `Action.PersonalizedViewsDropdown`. -* `Action.OrganiseFavourites`. Use `Action.OrganizeFavorites`. - -|==== - - -== Version 1.47.x, April 2026 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| **Spotter chat history sidebar customization** - -The SDK introduces the `SpotterSidebarViewConfig` interface and the `spotterSidebarConfig` object with configuration controls to customize the appearance and contents of the chat history panel. Developers can use the following properties in the `spotterSidebarConfig` object to enable or disable chat history panel and customize the contents of the sidebar when enabled: - -* `enablePastConversationsSidebar` + -Controls the visibility of the past conversations sidebar panel. The chat history panel is disabled by default in embed view. When this property in `spotterSidebarConfig` is specified, it takes precedence over the standalone `enablePastConversationsSidebar` setting, which is deprecated from v1.47.0. - -* `spotterSidebarTitle` + -Allows adding custom title text for the sidebar header. - -* `spotterSidebarDefaultExpanded` + -Sets the default state of the sidebar to expanded or collapsed view. - -* `spotterChatRenameLabel` + -Allows setting a custom label for the **Rename** action in the conversation edit menu. - -* `spotterChatDeleteLabel` + -Allows setting a custom label for the **Delete** action in the conversation edit menu. - -* `spotterDeleteConversationModalTitle` + -Allows editing the title text of the chat delete confirmation modal. - -* `spotterPastConversationAlertMessage` + -Sets a custom message text for the past conversation banner alert. Defaults to the translated alert message. - -* `spotterBestPracticesLabel` + -Allows customizing the label for the best practices button in the sidebar footer. - -* `spotterDocumentationUrl` + -The best practices documentation link shown in the sidebar footer. You can customize the link by specifying the full URL. - -* `spotterConversationsBatchSize` + -Sets the number of conversations to fetch per batch when loading conversation history. Default is `30`. - -* `spotterNewChatButtonTitle` + -Allows customizing the title text for the **New chat** button in the sidebar. - -|[tag redBackground]#DEPRECATED# a| **Standalone `enablePastConversationsSidebar` attribute in Spotter embed** - -The standalone `enablePastConversationsSidebar` property on `SpotterEmbedViewConfig` and `AppViewConfig` is deprecated from SDK 1.47.0 and ThoughtSpot 26.4.0.cl. - -Use `enablePastConversationsSidebar` in the `spotterSidebarConfig` instead. When both are defined, the property in the `spotterSidebarConfig` object takes precedence. - -[source,javascript] ----- -// Deprecated -enablePastConversationsSidebar: false, - -// Recommended -spotterSidebarConfig: { - enablePastConversationsSidebar: true, - //... other config properties -} ----- - -|[tag greenBackground]#NEW FEATURE# a| **Spotter chat UI branding** - -The SDK introduces the `SpotterChatViewConfig` interface for customizing branding in Spotter tool response cards. You can pass these parameters as the `spotterChatConfig` object properties in `SpotterEmbed`, `AppEmbed`, or `LiveboardEmbed` where Spotter interface is used. - -* `hideToolResponseCardBranding` + -When set to `true`, hides the ThoughtSpot logo and icon in tool response cards. The branding label prefix is controlled separately via `toolResponseCardBrandingLabel`. Default value is `false`. - -* `toolResponseCardBrandingLabel` + -Custom label to replace the `ThoughtSpot` prefix in tool response cards. Set to an empty string (`''`) to hide the prefix entirely. - -[NOTE] -==== -These settings do not affect the external MCP tool branding. -==== - -|[tag greenBackground]#NEW FEATURE# a|**Liveboard embed enhancements** - -Personalized Liveboard view:: - -The `personalizedViewId` property allows embedding a saved personalized view of a Liveboard. A personalized view is a saved configuration that includes specific filter selections and changes applied by a user. To embed a personalized view of Liveboard, specify the GUID of the saved personalized view to load along with `liveboardId`. - -Centralized Liveboard filter setting:: - -When set to `true`, the `isCentralizedLiveboardFilterUXEnabled` enables displaying a unified modal to manage and update multiple filters at once, replacing the older individual filter interactions. This feature is disabled by default on ThoughtSpot Embedded instances. - -|[tag greenBackground]#NEW FEATURE# a|**Option to include current period in rolling date filters** - -If the current period inclusion in rolling date filters feature is enabled on your instance, the rolling date filters options such as **Last ** and **Next ** for the Liveboards and Answers in the embed view will allow you to include current period. For example, when you define a date range such as "Last 2 months", the date filter interface displays the **Include this month** checkbox. -To disable this feature, use the `isThisPeriodInDateFiltersEnabled` setting. To hide, show, or disable this option in the embed view, use the action ID, `Action.IncludeCurrentPeriod`. -|==== - - -== Version 1.46.x, March 2026 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| **Host events with page context framework** - -The Visual Embed SDK introduces the HostEvent V2 framework for improved handling and execution of host events in embedded ThoughtSpot experiences with multi-layer UI interactions. The v2 framework supports the page context feature, which tracks the top-most active layer in the user's current context. Developers can use this feature to route events based on the user's current context or set a specific target context for precise and predictable handling of host events. - -* To enable this feature, set `useHostEventsV2` to `true`. -* To retrieve the current context, use `getCurrentContext()`. -* To set a target context for a host event, use xref:ContextType.adoc[ContextType]. - -For more information, refer to the xref:events-context-aware-routing.adoc[Host events documentation]. - -|[tag redBackground]#DEPRECATED# a| **dataPanelV2** - -The `dataPanelV2` parameter is deprecated and can no longer be used to switch between the classic and new data panel experience. By default, the new data panel v2 experience is enabled on all ThoughtSpot embedded instances. - -|[tag greenBackground]#NEW FEATURE# a| **Spotter experience** -The SDK includes the following parameters, action IDs, and events to customize the Spotter embed experience. - -Chat history sidebar customization:: - -//* `SpotterSidebarViewConfig` interface with configuration parameters for customizing the visibility and appearance of the chat history sidebar. -//* `spotterSidebarConfig` properties for customizing the appearance and available options in the chat history sidebar. -* Action IDs for customizing the visibility and status of actions in the embedded Spotter interface: -** `Action.DataModelInstructions` for the data model instructions icon. -** `Action.SpotterSidebarHeader` for the chat history sidebar header -** `Action.SpotterSidebarFooter` for the chat history sidebar footer -** `Action.SpotterSidebarToggle` for the chat history toggle that expands or collapses the sidebar. -** `Action.SpotterNewChat` for the new chat icon in the chat history sidebar. -** `Action.SpotterPastChatBanner` for the banner in the chat history sidebar. -** `Action.SpotterChatMenu` for the chat menu component in the chat history sidebar. -** `Action.SpotterChatRename` for **Rename** action in the chat menu of a saved chat. -** `Action.SpotterChatDelete` for **Delete** action in the chat menu of a saved chat. -//** `Action.SpotterDocs` for best practices documentation icon in the chat history sidebar. - -Events:: -* `HostEvent.DataModelInstructions` + -Opens the Data Model instructions modal. -* `EmbedEvent.DataModelInstructions` + -Is emitted when a user clicks the Data Model instructions icon in the Spotter interface. -* `EmbedEvent.SpotterConversationRenamed` + -Is emitted when a user renames a saved chat. -* `EmbedEvent.SpotterConversationDeleted` + -Is emitted when a saved chat is deleted. -* `EmbedEvent.SpotterConversationSelected` + -Is emitted when a saved chat is selected in the chat history sidebar. - -|[tag greenBackground]#NEW FEATURE# | `enableLinkOverridesV2` + - -Use this configuration setting to override ThoughtSpot URLs on hover or when opening in a new tab. This is recommended over the earlier `linkOverride` flag for a better user experience. - -|[tag greenBackground]#NEW FEATURE# a| **Liveboard experience enhancements** - -* The `isLiveboardXLSXCSVDownloadEnabled` attribute adds XLSX and CSV to the available Liveboard download formats. -* The `isGranularXLSXCSVSchedulesEnabled` attribute allows you to include the entire Liveboard, specific visualizations, or only tables and pivot tables in the XLSX and CSV schedules. +Action ID to show or hide the continuous PDF download button. |==== - -== Version 1.45.0, February 2026 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| **Spotter enhancements** - -You can now embed the Spotter 3 experience in your application and use features such as Auto mode for automatic data model selection, chat history, and a new chat prompt interface. - -* To enable the new chat prompt interface, set `updatedSpotterChatPrompt` to `true`. -* To use Auto mode, set the `worksheetId` to `auto_mode`. -* To enable Chat history, set `enablePastConversationsSidebar` to `true`. - -For more information, see xref:embed-spotter.adoc[Embedding Spotter] and xref:embed-ai-analytics.adoc#_feature_status_and_availability_in_embed_mode[Features available with Spotter 3 experience]. - -Events:: - -* `EmbedEvent.AddToCoaching` for the *Add to Coaching* workflow in a Spotter conversation session -* `HostEvent.AddToCoaching` to trigger the *Add to Coaching* action in a Spotter conversation session. -* `HostEvent.StartNewSpotterConversation` to trigger the action to start a new chat session with Spotter. - -[NOTE] -==== -On Spotter embed deployments running version 26.2.0.cl or later, the *Add to Coaching* feature is enabled by default. To disable or hide the *Add to Coaching* button, use the xref:Action.adoc#_inconversationtraining[InConversationTraining] action ID. -==== - -|[tag greenBackground]#NEW FEATURE# a| **Liveboard experience enhancements** + - -Styling and grouping:: - -* The `isLiveboardStylingAndGrouping` attribute, used to enable the Liveboard styling and grouping feature, is now replaced with `isLiveboardMasterpiecesEnabled`. While your existing configuration with the deprecated `isLiveboardStylingAndGrouping` attribute continues to work, we recommend switching to the new configuration setting. -* The following action IDs are now available to show, disable, or hide the grouping menu actions on a Liveboard: -** `Action.MoveToGroup` for the **Move to Group** menu action. -** `Action.MoveOutOfGroup` for the **Move out of Group** menu action. -** `Action.CreateGroup` for the *Create Group* menu action. -** `Action.UngroupLiveboardGroup` for the **Ungroup Liveboard Group** menu action. - -Filter chip masking:: -The `showMaskedFilterChip` boolean parameter is now available to control the visibility of masked filter chips on a Liveboard. When set to `true`, if a Liveboard is shared with a user who has restricted access due to column-level security, the filter chip corresponding to those inaccessible columns will be displayed as masked to that user. When set to `false`, the filter chip for inaccessible columns will not be visible to the user. -+ -For more information, see link:https://docs.thoughtspot.com/cloud/latest/security-data-object#csr-liveboard[Column security rules on Liveboards]. -+ -The `showMaskedFilterChip` setting is also available in full application embedding. - -|[tag greenBackground]#NEW FEATURE# a| **Publishing objects** - -The following action IDs are available for the data publishing menu actions in the *Data workspace* page: - -* `Action.Publish` for *Publish* -* `Action.ManagePublishing` for *Manage publishing* -* `Action.Unpublish` for *Unpublish* -* `Action.Parameterize` for *Parameterize* -|[tag greenBackground]#NEW FEATURE# a| **Error handling improvements** - -To handle errors in the embedding workflows, the SDK includes the following features: - -* `ErrorDetailsTypes` enum for categorizing error types, such as `API`, `VALIDATION_ERROR`, and `NETWORK`. -* `EmbedErrorCodes` enum with specific error codes for programmatic error handling. -* `EmbedErrorDetailsEvent` interface for structured error event handling. - -For more information, see link:https://developers.thoughtspot.com/docs/Enumeration_EmbedErrorCodes[EmbedErrorCodes] and link:https://developers.thoughtspot.com/docs/Enumeration_ErrorDetailsTypes[ErrorDetailsTypes]. -|==== - -== Version 1.44.x, January 2026 - -[width="100%" cols="1,4"] -|==== - -|[tag redBackground]#DEPRECATED# | **Use `minimumHeight` instead of `defaultHeight`** + - -The `defaultHeight` parameter is deprecated in Visual Embed SDK v1.44.2 and later. -To set the minimum height of the embed container for ThoughtSpot components such as a Liveboard, use the `minimumHeight` attribute instead. - -|[tag greenBackground]#NEW FEATURE# a| *Intercepting API calls* + -The SDK provides the following attributes to intercept API calls and handle interception via events and custom workflows: - -//* `enableApiIntercept` + -//When set to true, enables the feature on your ThoughtSpot embed. -* `interceptUrls` + -Allows configuring which API calls to intercept. -* `interceptTimeout` + -Sets the timeout duration for handling interception. -* `isOnBeforeGetVizDataInterceptEnabled` + -When set to true, it enables use of `EmbedEvent.OnBeforeGetVizDataIntercept` to emit and intercept search execution calls initiated by users and implement custom logic or workflows to allow or restrict search execution. -* `EmbedEvent.ApiIntercept` + -Emits when an API call matching the conditions defined in `interceptUrls` is detected. - -For more information, see xref:api-intercept.adoc[Intercept API calls and search requests]. -|==== - - -== Version 1.43.0, November 2025 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| *Code-based custom actions* - -The following enumerations are available for code-based custom actions: - -* `CustomActionTarget` + -To define the target object for the custom action, such as on a Liveboard, visualization, Answer, or in Spotter. -* `CustomActionsPosition` + -To define the position of the custom action in the target object, such as primary menu, **More** options menu image:./images/icon-more-10px.png[the more options menu], or the contextual menu. -|[tag greenBackground]#NEW FEATURE# | *Attribute to set Parameter chip visibility during overrides* + -The `HostEvent.UpdateParameters` event now supports configuring the `isVisibleToUser` attribute to show or hide the Parameter chips after an override. For more information, see xref:runtime-parameters.adoc#_show_or_hide_parameter_chips_in_embedded_sessions[Show or hide Parameter chips in embedded sessions]. -|==== - -== Version 1.42.0, October 2025 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a|*Runtime overrides in Spotter embed* - -The Visual Embed SDK now supports runtime overrides in Spotter embed. - -* To apply runtime filters, use the `runtimeFilters` object -* To apply runtime Parameters, use the `runtimeParameters` object. - -|[tag greenBackground]#NEW FEATURE# a|*PNG images in Liveboard schedule notifications* + -To enable embedding PNG images of Liveboards in scheduled job notifications sent to subscribers, the SDK provides the `isPNGInScheduledEmailsEnabled` boolean parameter. When set to true, scheduled emails will include a PNG image of the Liveboard. - -The SDK also provides the following action IDs: - -* `Action.PngScreenshotInEmail` + -Adds the option to include a PNG screenshot in the notification email body when scheduling emails in ThoughtSpot. -* `Action.RemoveAttachment` + -Allows the user to remove an attachment from the email configuration in the schedule email dialog. -|[tag greenBackground]#NEW FEATURE# a|*Spotter embed* - -Action IDs:: -The following action IDs are available for Spotter embedding and are currently supported only in the `hiddenActions` array: - -* `Action.SpotterWarningsBanner` + -Action ID to control the visibility of the Spotter warnings banner in the UI. This banner displays general warnings or informational messages related to Spotter results or queries. -* `Action.SpotterWarningsOnTokens` + -Action ID to control the visibility of warning indicators on individual Spotter tokens parsed from a Spotter query. -* `Action.SpotterTokenQuickEdit` + -Action ID to enable or disable the link:https://docs.thoughtspot.com/cloud/latest/spotter-getting-started#quick-edits[quick edit functionality^] for Spotter tokens. -|==== - -== Version 1.41.0, September 2025 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a|*React component for Spotter Agent embed* - -The Visual Embed SDK now supports embedding Spotter Agent feature without a body or Spotter interface in a React app. For ease of implementation, the SDK also provides a custom React hook, `useSpotterAgent`. - -For more information, see xref:embed-ts-react-app.adoc#_embed_spotter_agent_in_your_own_app[Spotter Agent embedding in a React app]. - -|[tag greenBackground]#NEW FEATURE# a|*Event handlers for Spotter embed* - -The following event handlers are now available for Spotter embed: - -* `EmbedEvent.SpotterInit` + -Fires when Spotter embed component rendering is initialized. -* `EmbedEvent.QueryChanged` + -Fires when the Spotter query is updated by the user. -* `HostEvent.AskSpotter` + -Triggers *Ask Spotter* action for visualizations. -* `HostEvent.GetParameters` + -Triggers the action to fetch runtime Parameters applied on a visualization. -* `HostEvent.UpdateParameters` + -Triggers the action to update runtime Parameters for a Spotter-generated Answer. -* `HostEvent.GetTML` + -Triggers the action to get TML representation of a Spotter-generated Answer. - -For more information, see xref:EmbedEvent.adoc[EmbedEvent] and xref:HostEvent.adoc[HostEvent]. - -|[tag greenBackground]#NEW FEATURE# a|*Event handlers for Spotter Agent embed* - -You can now use the following host events in Spotter Agent embedding: - -- `HostEvent.DownloadAsCsv` + -Triggers the action to download a Spotter-generated Answer in CSV format. -- `HostEvent.DownloadAsPng` + -Triggers the action to download a Spotter-generated Answer in PNG format. -- `HostEvent.DownloadAsXlsx` + -Triggers the action to download a Spotter-generated Answer in XLSX format. -- `HostEvent.DownloadAsPdf` + -Triggers the action to download the PDF version of a Spotter-generated Answer. -- `HostEvent.Pin` + -Triggers the action to add a Spotter-generated Answer to a Liveboard. -- `HostEvent.Save` + -Triggers the *Save* action for a Spotter-generated Answer. - -For more information, see xref:HostEvent.adoc[HostEvent]. - -|[tag greenBackground]#NEW FEATURE# a| *Lazy loading of visualizations on an embedded Liveboard* - -You can now use the `lazyLoadingForFullHeight` parameter with the `fullHeight` to progressively load visualizations on an embedded Liveboard. When both these attributes are enabled, only the visualizations in the current viewport are loaded initially, while the other visualizations load as the user scrolls the Liveboard page. - -You can also set the margin property for lazy loading to define when the visualization should load. - -For more information, see xref:lazy-loading-fullheight.adoc[Lazy loading of visualizations in an embedded Liveboard]. - -|[tag greenBackground]#NEW FEATURE# a| *Full application embed* + - -You can now enable the persona-based left navigation panel and home page experience on your ThoughtSpot instance. This feature is disabled by default on ThoughtSpot instances and is available for Early Access. When it's enabled on your ThoughtSpot instance, you can roll out the new experience on embedding applications by configuring the xref:AppViewConfig.adoc#_discoveryexperience[`discoveryExperience`] attribute. - -When enabled, the left navigation panel organizes the application menu into persona-based contextual sections. For example, the *Insights* icon for business users, the *Data Workspace* icon for Analysts and Data engineers, and the *Develop* icon for developers. Your application users can navigate to each option using the tabs in the left navigation panel. The new interface also provides a slider to allow users to view or hide the left navigation panel. -|==== - -== Version 1.40.0, July 2025 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| *Fullscreen presentation mode controls for embedded Liveboards and visualizations* + -Developers can now control whether a visualization or Liveboard can be presented in full screen mode using the `disableFullscreenPresentation` attribute. By default, the full screen mode is disabled on embedded Liveboards and visualizations. -|[tag greenBackground]#NEW FEATURE# a| *PDF download settings* + -Developers can now control the display of *Include cover page* and *Include filter page(s)* options on the Download PDF dialog for Liveboards. The *Include cover page* and *Include filter page(s)* options are disabled by default on ThoughtSpot instances. When this feature is enabled, developers can use the `coverAndFilterOptionInPDF` attribute to show or hide these options for the Liveboard users in their embedding app. - -|[tag greenBackground]#NEW FEATURE# a| *Parameter for overriding a default primary action* + - -If Spotter is enabled on your instance, the *Spotter* button appears by default as the primary action on embedded Liveboard charts; if Spotter is not enabled, the *Explore* button is set as the primary action. If you want to replace the primary action with a different action, you can now use the `primaryAction` attribute. - -For more information, see xref:embed-actions.adoc#_override_default_primary_actions[Override default primary action]. - -|[tag greenBackground]#NEW FEATURE# a| *Full application embed experience enhancements* + - -The SDK now includes the `hideObjectSearch` property, which allows developers to hide the object search button in the navigation bar when embedding the full application. - -|[tag greenBackground]#NEW FEATURE# a| *Host events* + - -In this version, the SDK introduces the following host event handlers: - -- `HostEvent.ExitPresentMode` + -Triggers the exit action that allows users to exit the Liveboard or visualization present mode. -- `HostEvent.SpotterSearch` + -Triggers a search operation for the specified query string in Spotter embed. -- `HostEvent.PreviewSpotterData` + -Triggers the *Preview data* action that shows the data used for Spotter conversations. -- `HostEvent.ResetSpotterConversation` + -Triggers the *Reset* action to reset a Spotter conversation. -- `HostEvent.EditLastPrompt` + -Triggers the edit prompt action. -- `HostEvent.DeleteLastPrompt` + -Triggers the delete prompt action. - -For more information, see xref:HostEvent.adoc[HostEvent]. - -|[tag greenBackground]#NEW FEATURE# a|*Events support for Spotter embed* - -You can now use the following host events in Spotter embed: - -- `HostEvent.DownloadAsCsv` -- `HostEvent.DownloadAsPng` -- `HostEvent.DownloadAsXlsx` -- `HostEvent.Edit` -//- `HostEvent.GetParameters` -//- `HostEvent.GetTML` -- `HostEvent.MakeACopy` -- `HostEvent.Pin` -- `HostEvent.Save` - -For more information, see xref:HostEvent.adoc[HostEvent]. - -|[tag greenBackground]#NEW FEATURE# a| *Lazy loading with full height* - -The SDK introduces `lazyLoadingForFullHeight` parameter, which enables progressive loading of visualizations on an embedded Liveboard. -This parameter works in conjunction with the `fullHeight` attribute. When both these attributes are enabled, only the visualizations in the current viewport are loaded initially, while the other visualizations load as the user scrolls the Liveboard page. - -[NOTE] -==== -To use these attributes effectively in embedded applications, your ThoughtSpot instance must be upgraded to version 10.12.0.cl or later. -==== -|==== - - -== Version 1.39.0, July 2025 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| *Spotter embed components with new names* + -The following Spotter embed components are now deprecated and replaced with new components in the SDK and Visual Embed Playground: - -* `ConversationEmbed` + -Replaced with `SpotterEmbed` -* `ConversationViewConfig` + -Replaced with `SpotterEmbedViewConfig` -* `BodylessConversation` + -Replaced with `SpotterAgentEmbed` -* `BodylessConversationViewConfig` + -Replaced with `SpotterAgentEmbedViewConfig` - -The deprecated components with old names in the existing Spotter embed implementations will continue to function until further notice. For code samples with new component names, see xref:embed-spotter.adoc[Spotter embed documentation]. - -|[tag greenBackground]#NEW FEATURE# a| *Action ID for Spotter in-conversation training* + -For ThoughtSpot instances that have the new Spotter in-conversation training workflow enabled, the SDK provides the action ID `Action.InConversationTraining` to manage the visibility of the *Add to Coaching* button on Answers generated from Spotter prompts. - -[NOTE] -The *Add to Coaching* feature is currently in beta and is turned off by default on embed deployments. To enable this feature on your instance, contact ThoughtSpot Support. - -|[tag greenBackground]#NEW FEATURE# a|*Events support for Spotter embed* - -New embed events:: - -- `EmbedEvent.ExitPresentMode` + -Emits when a user exits the Liveboard or visualization presentation mode. -- `EmbedEvent.LastPromptDeleted` + -Emits when a query prompt in Spotter embed is deleted. -- `EmbedEvent.LastPromptEdited` + -Emits when a query prompt in Spotter embed is edited. -- `EmbedEvent.ResetSpotterConversation` + -Emits when a Spotter query is reset. -- `EmbedEvent.PreviewSpotterData` + -Emits when a user clicks the Preview data button in the Spotter conversation panel. -- `EmbedEvent.SpotterQueryTriggered` -Emits when a Spotter query is triggered. - -The following embed events are also supported in Spotter embed: - -- `EmbedEvent.AddRemoveColumns` -- `EmbedEvent.AnswerChartSwitcher` -- `EmbedEvent.AuthExpire` -- `EmbedEvent.AuthInit` -- `EmbedEvent.CopyToClipboard` -- `EmbedEvent.CustomAction` -- `EmbedEvent.Data` -- `EmbedEvent.DataSourceSelected` -- `EmbedEvent.DialogClose` -- `EmbedEvent.DialogOpen` -- `EmbedEvent.Download` -- `EmbedEvent.DownloadAsCsv` -- `EmbedEvent.DownloadAsPng` -- `EmbedEvent.DownloadAsXlsx` -- `EmbedEvent.DrillDown` -- `EmbedEvent.DrillExclude` -- `EmbedEvent.DrillInclude` -- `EmbedEvent.Edit` -- `EmbedEvent.Error` -- `EmbedEvent.Load` -- `EmbedEvent.Pin` -- `EmbedEvent.Save` -- `EmbedEvent.TableVizRendered` -- `EmbedEvent.VizPointClick` -- `EmbedEvent.VizPointDoubleClick` -- `EmbedEvent.VizPointRightClick` - -For more information, see xref:EmbedEvent.adoc[EmbedEvent]. - -|==== - -== Version 1.38.0, June 2025 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| *String IDs for text customization* + -Developers can now customize a specific occurrence of a visible text string in the ThoughtSpot UI using the `stringIDs` object in the customization interface. - -To locate the string IDs, SDK provides the `exposeTranslationIds` attribute. By setting `exposeTranslationIds` to `true` in the Playground, you can find the string ID of the UI text and use it in your customization code. - -Additionally, the SDK provides the `StringIDsUrl` attribute to allow using a JSON file with string IDs and custom strings to override the visible text in the UI. - -For more information, see xref:customize-text-strings.adoc[Customize text strings]. - -|[tag greenBackground]#NEW FEATURE# a| *Hide columns on list pages* + - -In full app embedding, you can now hide the following columns on the *Liveboards* and *Answers* listing pages using the `hiddenListColumns` array: - -* *Author* + -`hiddenListColumns: [ListPageColumns.Author]` -* *Favorite* + -`hiddenListColumns: [ListPageColumns.Favourite]` -* *Last modified* + -`hiddenListColumns: [ListPageColumns.DateSort]` -* *Tags* + -`hiddenListColumns: [ListPageColumns.Tags]` -* *Share* + -`hiddenListColumns: [ListPageColumns.Share]` + - -For more information, see xref:full-app-customize.adoc#_hide_columns_on_list_pages_new_experience[Customize full application embed]. -|==== - -== Version 1.37.0, April 2025 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| -The SDK now provides the `customVariablesForThirdPartyTools` setting to pass custom variables when integrating third-party tools and running custom scripts in your embed. Developers can define this object in the **init()** function and add variables as key-value pairs. -This feature is available only if third-party integration is enabled on your instance and the script hosting domain URL is added to the CSP allowlist. - -For more information, see xref:3rd-party-script.adoc[Integrate third-party tools and allow custom scripts]. - -|[tag greenBackground]#NEW FEATURE# a| -You can now exclude search token string from the application URL by setting `excludeSearchTokenStringFromURL` to `true` in your embed with ThoughtSpot token-based Search or Search bar. - -|[tag greenBackground]#NEW FEATURE# a| This version of the SDK supports the following embed and host events: - -Embed Events:: - -* `EmbedEvent.TableVizRendered` + -Emits when a table visualization is rendered in the ThoughtSpot embedded app. You can also use this event as a hook to trigger host events such as `HostEvent.TransformTableVizData` on the table visualization. For more information, see the link:https://developers.thoughtspot.com/docs/Enumeration_EmbedEvent#_tablevizrendered[SDK reference documentation]. - -* `EmbedEvent.CreateLiveboard` + -Emits when a Liveboard is created. - -Host Events:: - -* `HostEvent.TransformTableVizData` + -Triggers the table visualization re-render with the updated data. You can use this event in conjunction with `EmbedEvent.TableVizRendered` to apply the modifications to table visualization payload. - -* `HostEvent.Remove` + -Triggers the *Delete* action on a Liveboard. -|==== - -== Version 1.36.0, February 2025 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| -The following HostEvents now allow custom parameters to set object properties programmatically: - -* `HostEvent.SaveAnswer` + -Allows adding `name` and `description` text strings. When these parameters are defined, the event triggers the Save action to save the Answer with the predefined properties without opening the *Describe your Answer* modal. -* `HostEvent.Pin` + -Allows adding custom properties for visualization ID, name, and description, Liveboard ID, and Tab ID. When these parameters are defined, the event triggers an action to pin the Answer to the Liveboard specified in the code, without opening the *Pin* modal. - -For more information, see xref:events-hostEvents.adoc#hostEventParameterization[Host Events] documentation. - -|[tag greenBackground]#NEW FEATURE# a| - -New configuration attributes:: - -* `disableSourceSelection` + -Disables data source selection panel for embed users when set to `true`. -* `hideSourceSelection` + -Hides data source selection panel when set to `true` -* `locale` + -Sets the xref:locale-setting.adoc[locale and regional settings] for the Spotter interface. -* `showSpotterLimitations` + -Shows functional limitations of Spotter when set to `true` -* `hideSampleQuestions` + -Hides sample questions that appear on the default Spotter page. - -Action IDs for menu customization:: -Use the following action IDs in the `disabledActions`, `visibleActions`, or `hiddenActions` array to disable, show, or hide menu actions and elements in the embedded Spotter interface: - -* `Action.PreviewDataSpotter` + -The *Preview data* button on the Spotter conversation panel. -* `Action.ResetSpotterChat` + -The *Reset* button on the Spotter conversation panel. -* `Action.SpotterFeedback` + -The feedback widget on Spotter-generated charts. -* `Action.EditPreviousPrompt` + -The edit icon on the prompt panel. -The Prompt panel appears after Spotter generates a response to a user query. -* `Action.DeletePreviousPrompt` + -The delete icon on the prompt panel. - -//// -* `Action.EditTokens` + -The option to edit tokens on a Spotter-generated chart or table. -//// -CSS variables:: - -The following new CSS variables are available for Spotter interface customization: - -* `--ts-var-spotter-input-background` -* `--ts-var-spotter-prompt-background` - -For more information about Spotter customization, see xref:embed-spotter.adoc#SpotterCSS[Customize styles]. -|[tag greenBackground]#NEW FEATURE# a| - - -Configuration attributes:: - -* `hideIrrelevantChipsInLiveboardTabs` + -Hides filter chips on a Liveboard when set to `true`. - -* `isLiveboardCompactHeaderEnabled` + -Enables the compact Liveboard header feature when set to `true`. - -Action IDs:: -Use the following action IDs in the `disabledActions`, `visibleActions`, or `hiddenActions` array to disable, show, or hide menu actions on an embedded Liveboard: - -* `Action.DisableChipReorder` + -ID for the action that disables filter chip reordering. -* `Action.ChangeFilterVisibilityInTab` - -|==== - -== Version 1.35.0, December 2024 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| -The SDK now provides the `isUnifiedSearchExperienceEnabled` setting to customize the Search experience on ThoughtSpot Home page for embedding application users: - -* When set to `true`, the split search experience is disabled and the Search bar on the Home page functions as Natural Language Search interface -* When set to `false`, the split search experience is enabled and object Search is set as the default Home page search experience. - -For more information, see xref:full-app-customize.adoc#_search_components[Search interface on the Home page in full application embedding]. - -|[tag greenBackground]#NEW FEATURE# a| The `overrideOrgId` parameter in the SDK provides the ability to override Org context for embedding application users. This parameter allows users authenticated to an Org to temporarily view content from another Org. Before specifying the Org ID for override, make sure the Per Org URL feature is enabled on your ThoughtSpot instance. To enable Per Org URL on your instance, contact ThoughtSpot Support. -|==== - -== Version 1.34.0, November 2024 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| You can now embed the following ThoughtSpot Spotter components in your app: - -* `SpotterEmbed` + -Embeds Spotter conversation interface in your app -* `SpotterAgentEmbed` + -Creates a conversation component without the body, which can be integrated into chatbots or other conversational apps. - -For more information, see xref:embed-spotter.adoc[Embed Spotter] and xref:spotter-in-custom-chatbot.adoc[Integrate Spotter into your chatbot]. - -|[tag greenBackground]#NEW FEATURE# a|The following parameters and enumerations are available for customizing Liveboard experience: - -* `showLiveboardVerifiedBadge` + -Shows or hides the Liveboard verified badge. Available if the Liveboard compact header feature is enabled. -* `showLiveboardReverifyBanner` + -Shows or hides the re-verify banner. Available if the Liveboard compact header feature is enabled. -* `Action.KPIAnalysisCTA` + -Action ID to show, hide, or disable the **Analyze CTA** action on a KPI chart. - -|[tag greenBackground]#NEW FEATURE# |You can now use the `HostEvent.GetIframeUrl` to get the iframe src URL from the Visual Embed Playground. If you are embedding ThoughtSpot in apps like Salesforce and Sharepoint without the SDK, use this event to generate the iframe URL. - -|[tag greenBackground]#NEW FEATURE# a|The following parameters are available for customizing Search experience: - -* `collapseDataPanel` -Minimizes the data panel view. Users can click the data panel header any time to expand the panel. -* `collapseSearchBar` -Sets the initial state of the search bar when embedding a saved Answer. - -|[tag greenBackground]#NEW FEATURE# a| The following settings are available for customizing the new home page and navigation experience in full app embedding: - -* `HomeLeftNavItem.LiveboardSchedules` + -The Liveboard schedules menu on the left navigation panel. - -Action enumerations:: - -* `Action.EditScheduleHomepage` + -To show, disable, or hide the *Edit* action on the *Liveboard schedules* page -* `Action.PauseScheduleHomepage` + -To show, disable, or hide the *Pause* action on the *Liveboard schedules* page -* `Action.ViewScheduleRunHomepage` + -To show, disable, or hide the *View run history* action on the *Liveboard schedules* page -* `Action.DeleteScheduleHomepage` + -To show, disable, or hide the *Delete* action on the *Liveboard schedules* page -* `Action.UnsubscribeScheduleHomepage` + -To show, disable, or hide the *Unsubscribe* action on the *Liveboard schedules* page -|==== - -== Version 1.33.x, October 2024 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| You can now customize the search experience for the embedded ThoughtSpot **Home** page using `homePageSearchBarMode`. By default, the **Home** page includes the Object Search bar, which allows finding popular Liveboards and Answers. - -You can set the `homePageSearchBarMode` property to one of the following options: - -** `aiAnswer` + -Displays the search bar for Natural Language Search. -** `none` -Hides the Search bar on the **Home** page. Note that it only hides the Search bar on the **Home** page and doesn't affect the Object Search bar visibility on the top navigation bar. -** `objectSearch` (default) + -Displays Object Search bar on the **Home** page. -|[tag greenBackground]#NEW FEATURE# a|The SDK now allows you to set the focus on the Search bar or outside the Search bar when rendering the embedded Search page. Use the `focusSearchBarOnRender` property to set the position of the cursor focus. -|[tag greenBackground]#NEW FEATURE# a| The SDK includes the following Event and Action enumeration members: - -Events:: - -* `EmbedEvent.OnBeforeGetVizDataIntercept` + -Developers can emit this event to intercept search execution, allow or restrict certain queries, and show an error message with custom text for restricted queries. To allow the embedded page to emit this event, you must set the `isOnBeforeGetVizDataInterceptEnabled` attribute to `true`. - -* `EmbedEvent.ParameterChanged` + -Emitted when a Parameter is changed on a saved Answer or Liveboard. - -Actions:: - -* `Action.ManageTags` + -Use this action enumeration to disable, show, or hide the **Manage tags** button on the Liveboards and Answers pages. -|==== - -== Version 1.32.x, August 2024 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| The following new action enumerations are available in this version: + - -* `Action.CreateLiveboard` for the *Create Liveboard* menu action on the Liveboards lists page. + -* `Action.SyncToTeams` for the **Sync to Teams** menu action on Liveboard visualizations. -* `Action.SyncToSlack` for the **Sync to Slack** action on Liveboard visualizations. -* `Action.AddQuerySet` for the **Add Query Set** action on the data panel (new experience) of the Search page. -* `Action.AddColumnSet` for the **Add Column Set** action on the data panel (new experience) of the Search page. -* `Action.AddDataPanelObjects` for the **Add** menu that includes sub-menu options such as Formulas, Parameters, Query set, and Column set actions. -* `Action.OrganiseFavourites` for the **Organize** action above the Favorites panel on the modular Homepage (New experience) -For more information, see xref:Action.adoc[Actions]. -|[tag greenBackground]#NEW FEATURE#| Developers can now use the `disableRedirectionLinksInNewTab` parameter to disable links and redirection of links in the embedded view. -|[tag greenBackground]#NEW FEATURE# a|You can now enable `enable2ColumnLayout` on a Liveboard to adjust the page view according to the width and resolution of users' devices. -|| -|==== - -== Version 1.31.x, July 2024 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| Runtime filters + - -* `NOT_IN` operator for Runtime filters. -For more information, see xref:runtime-filters.adoc#runtimeFilterOp[Runtime filters]. -* `excludeRuntimeParametersfromURL` parameter to exclude or remove runtimeParameters from the URL. -|[tag greenBackground]#NEW FEATURE# |For performance optimization, developers can choose to load embedded views in a lightweight V2 shell by setting `enableV2Shell_experimental` to `true`. -|==== - -== Version 1.30.0, June 2024 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| **CSS variables for new homepage experience** - -* `--ts-var-home-watchlist-selected-text-color` + -* `--ts-var-home-card-color` + -* `--ts-var-home-favorite-suggestion-card-text-color` + -* `--ts-var-home-favorite-suggestion-card-background` + -* `--ts-var-home-favorite-suggestion-card-icon-color` - -For more information, see xref:css-customization.adoc#_homepage_modules_new_experience_mode[CSS variables and overrides]. -|==== - -== Version 1.29.0, May 2024 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| **Ask Sage** - -With Ask Sage [beta betaBackground]^Beta^ embedded application users can ask follow-up questions on a visualization generated from a Natural Language Search query, converse with AI analyst, and refine results. To enable this feature, set `enableAskSage` to `true`. - -Action enumeration:: -To show, hide, or disable Ask Sage on a visualization, add `Action.AskAi`. For example, -+ -[source,JavaScript] ----- -hiddenActions: [Action.AskAi] ----- - -Events:: -* `HostEvent.AskSage` + -Triggers the **Ask Sage** action on a Liveboard visualization. -* `EmbedEvent.AskSageInit` + -Emits when the **Ask Sage** action is initialized. -* `HostEvent.GetParameters` + -Triggers a fetch action to get runtime Parameters. -* `HostEvent.UpdateParameters` + -Updates runtime Parameters -* `HostEvent.ResetLiveboardPersonalisedView` + -Resets a personalized Liveboard view. -* `HostEvent.UpdateCrossFilter` + -Updates cross filters applied on a Liveboard. -|==== - -== Version 1.28.x, April 2024 - -[width="100%" cols="1,4"] -|===== -|[tag greenBackground]#NEW FEATURE# a| The SDK includes the following new enumeration members in v1.28.0: - -** `Action.VerifiedLiveboard` + -Can be used to show or hide the *Verified Liveboard* banner. -|[tag greenBackground]#NEW FEATURE# a| To access the new Home page and global navigation experience in the full application embedding, you can use the `modularHomeExperience` property in the SDK. The modular homepage experience is turned off by default and is available as an Early Access feature in 9.12.5.cl release. When `modularHomeExperience` is set to `true`, you can use the following parameters in the SDK to control the application experience: - -* `hiddenhomeleftnavitems` -* `hiddenhomepagemodules` -* `hideapplicationswitcher` -* `hidehomepageleftnav` -* `hideorgswitcher` -* `reorderedhomepagemodules` -* `HomeLeftNavItem` - -For more information, see xref:full-app-customize.adoc[Customize full application embedding] and xref:AppViewConfig.adoc[AppViewConfig]. -|[tag greenBackground]#NEW FEATURE# a| The following embed event is available from the v1.28.0 onwards: - -`EmbedEvent.Rename` + -Emits when an embedded Liveboard or visualization is renamed. -|[tag greenBackground]#NEW FEATURE# a| TML actions - -The following TML menu actions are now grouped under the **TML** sub-menu of the **More** image:./images/icon-more-10px.png[the more options menu] menu on Answer page. - -* Export TML -* Edit TML -* Update TML - -To show, hide, or disable these actions in the embedded mode, use the following format: - -[source,JavaScript] ----- - // to show the TML menu and its sub-menu options -visibleActions: [Action.TML, Action.ExportTML, Action.EditTML] ----- - -[source,JavaScript] ----- - // to hide all TML actions -hiddenActions: [Action.TML] ----- - -[source,JavaScript] ----- - // to disable all TML actions -disabledActions: [Action.TML] ----- -|[tag greenBackground]#NEW FEATURE# | You can now reset authentication token and fetch a new token for new authentication requests. -For more information, see link:https://developers.thoughtspot.com/docs/Function_resetCachedAuthToken[resetCachedAuthToken]. - -|[tag greenBackground]#NEW FEATURE#| You can now override the default number, date, and currency format defined by your locale settings. To override the default settings, use the following parameters: - -* `numberFormatLocale` + -* `dateFormatLocale` + -* `currencyFormat` - -For more information, see xref:locale-setting.adoc#_set_locale_in_the_sdk[Customize locale]. - -|[tag greenBackground]#NEW FEATURE# |Tokenized fetch + -The SDK now provides a fetch wrapper that adds the authentication token to the API requests. -For more information, see link:https://developers.thoughtspot.com/docs/Function_tokenizedFetch#_tokenizedfetch[tokenizedFetch]. -|===== - -== Version 1.27.x, March 2024 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| The following action enumeration members are available from v1.27.9 and v1.27.10: - -* `Action.AIHighlights` -* `Action.AddToWatchlist` -* `Action.RemoveFromWatchlist` -* `Action.CopyKpiLink` - -For more information, see xref:Action.adoc[Action]. -| [tag greenBackground]#NEW FEATURE# a| You can now use `HostEvent.GetAnswerSession` to get Answer session data for a Search Answer or Liveboard Visualization in the embedded view. -|==== - -== Version 1.27.0, January 2024 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a|The `SageEmbed` package is now available on all clusters. You can use this SDK package to embed Natural Language Search capabilities and assist users with AI-suggested queries and AI-generated answers. This SDK package also allows you to customize the Natural Language Search experience in the embedded view. - -For a complete list of methods, functions, interface objects, and properties, see the following pages: + - -* xref:SageEmbed.adoc[SageEmbed] -* xref:SageViewConfig.adoc[SageViewConfig] - -|[tag orangeBackground]#MODIFIED# a| The `HostEvent.DrillDown` now supports the `vizId` parameter to trigger a drill-down action on a specific visualization of a Liveboard. -For more information, see xref:HostEvent.adoc#_drilldown[DrillDown]. -|[tag greenBackground]#NEW FEATURE# a| The new version of the SDK introduces the following new enumeration members: - -* Host Events -** `HostEvent.UpdateSageQuery` + -Updates the search query string for Natural Language Search operations. -* Embed Events -** `EmbedEvent.CreateConnection` + -Emitted when a user creates a new data connection on the **Data** page. -** `EmbedEvent.CreateWorksheet` + -Emitted when a user creates a new Worksheet. -|==== - -== Version 1.26.0, November 2023 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| The SDK provides `AnswerService` class to trigger the answer service with a custom action payload. -You can use this service to run GraphQL queries in the context of the Answer with a custom action trigger. For more information, see link:https://developers.thoughtspot.com/docs/Class_AnswerService[AnswerService]. Recommended ThoughtSpot application version is 9.10.0.cl. - -|[tag greenBackground]#NEW FEATURE# a|The following object properties and feature flags are introduced in the `LiveboardEmbed` and `AppEmbed` SDK packages: - -* `showLiveboardDescription` + -Shows the Liveboard description text when set to `true` -* `showLiveboardTitle` + -Shows the Liveboard title when set to `true` -* `isLiveboardHeaderSticky` + -Sets Liveboard header bar as a fixed element when set to `true` -* `hideLiveboardHeader` + -Hides the Liveboard header when set to `true` -* `hiddenTabs` + -Hides the specified tabs from the Liveboard page -* `visibleTabs` + -Displays the specified tabs on the Liveboard page - -|[tag greenBackground]#NEW FEATURE# |You can now enable the new data panel experience by setting `dataPanelV2` to `true` in the SDK when embedding ThoughtSpot Search. The new data panel experience is turned off by default on embedded ThoughtSpot instances. - -|[tag greenBackground]#NEW FEATURE# a|The new version of the SDK supports the following events: - -Embed events:: -* `EmbedEvent.hiddenTabs` -* `EmbedEvent.visibleTabs` -* `EmbedEvent.UpdatePersonalisedView` -* `EmbedEvent.SavePersonalisedView` -* `EmbedEvent.ResetLiveboard` -* `EmbedEvent.DeletePersonalisedView` -* `EmbedEvent.SageWorksheetUpdated` -* `EmbedEvent.SageEmbedQuery` -+ -For more information, see xref:EmbedEvent.adoc[EmbedEvent]. - -Host events:: - -* `HostEvent.GetTabs` -* `HostEvent.SetVisibleTabs` -* `HostEvent.SetHiddenTabs` -* `HostEvent.GetAnswerSession` -* `HostEvent.UpdateSageQuery` -+ -For more information, see xref:HostEvent.adoc[HostEvent]. - -|[tag greenBackground]#NEW FEATURE# a| The SDK introduces the following action enumeration members: - -* `Action.AddTab` + -Show, disable, or hide the **Add Tab** action on a Liveboard. -* `Action.PersonalisedViewsDropdown` + -Show, disable, or hide the Liveboard views saved by a user. -* `Action.LiveboardUsers` + -Show, disable, or hide Liveboard users. -* `Action.SageAnswerFeedback` -Show, disable, or hide the feedback widget on AI-generated Answer page. -* `Action.EditSageAnswer` -Show, disable, or hide the **Edit** action on the AI-generated Answer page. - -For more information, see xref:Action.adoc[Actions]. -|==== - -== Version 1.25.0, October 2023 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# | The SDK now supports runtime Parameter overrides on Liveboards and Answers. -For more information, see xref:runtime-parameters.adoc#_apply_parameter_overrides_using_visual_embed_sdk[Runtime Parameter overrides]. - -|[tag greenBackground]#NEW FEATURE# a| The SDK introduces the following action enumeration members: - -* `Action.RenameModalTitleDescription` -* `Action.EnableContextualChangeAnalysis` -* `Action.RequestVerification` -* `Action.AddTab` - -For more information, see xref:Action.adoc[Actions]. -|==== - -== Version 1.24.0, September 2023 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| ThoughtSpot now provides the `SageEmbed` package to embed the ThoughtSpot Search page with Sage features such as natural language search and AI-suggested search examples. This feature is in beta and not available in the Visual Embed Playground. -|[tag greenBackground]#NEW FEATURE# a| The `HostEvent.SetActiveTab` event in the upcoming version of the SDK allows you to set a tab as an active tab on a Liveboard. -|==== - -== Version 1.23.0, August 2023 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| The SDK supports the following performance optimization enhancements: + - -* Ability to pre-render a generic instance of the ThoughtSpot component using the `prerenderGeneric` attribute. The generic instance uses the default host and flags and can be rendered in the background to improve application response. -* Ability to use an iFrame from a pre-rendered iFrame pool using the `usePrerenderedIfAvailable` attribute. -|==== - -//// -|[tag greenBackground]#NEW FEATURE# a| New events for Liveboard filters + - -* `EmbedEvent.FilterChanged` + -* `HostEvent.GetFilters` + -* `HostEvent.UpdateFilters` -//// - -== Version 1.22.0, June 2023 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| The new version of the SDK introduces the `TrustedAuthTokenCookieless` `authType` property to allow Cookieless embedding. The Cookieless authentication method allows using a bearer token to identify the signed-in user instead of session cookies. - -For more information, see xref:embed-authentication.adoc#_cookieless_authentication[Cookieless authentication]. - -|[tag greenBackground]#NEW FEATURE# a|The new version of the SDK allows you to block user access to the non-embedded instance of the ThoughtSpot application. In full app embed deployments, you can use the `blockNonEmbedFullAppAccess` property in the SDK to restrict or allow your application users from accessing ThoughtSpot pages in the non-embed mode. - -For more information, see xref:security-settings.adoc#_block_access_to_non_embedded_thoughtspot_pages[Block access to non-embedded ThoughtSpot pages]. - -|==== - -//// -|[tag greenBackground]#NEW FEATURE# a| The SDK supports the following performance optimization enhancements: + - -* Ability to pre-render a generic instance of the ThoughtSpot component using the `prerenderGeneric` attribute. The generic instance uses the default host and flags and can be rendered in the background to improve application response. -* Ability to use an iFrame from a pre-rendered iFrame pool using the `usePrerenderedIfAvailable` attribute. -//// - -== Version 1.21.0, May 2023 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a|The new version of the SDK introduces the following action enumeration members: - -* `Action.AxisMenuAggregate` -* `Action.AxisMenuConditionalFormat` -* `Action.AxisMenuEdit` -* `Action.AxisMenuFilter` -* `Action.AxisMenuGroup` -* `Action.AxisMenuNumberFormat` -* `Action.AxisMenuPosition` -* `Action.AxisMenuRemove` -* `Action.AxisMenuRename` -* `Action.AxisMenuSort` -* `Action.AxisMenuTextWrapping` -* `Action.AxisMenuTimeBucket` -* `Action.CrossFilter` -* `Action.RemoveCrossFilter` - -For more information, see xref:embed-action-ref.adoc[Action reference]. - -|[tag greenBackground]#NEW FEATURE# a| The SDK introduces the following events: - -* `HostEvent.AddColumns` -* `HostEvent.OpenFilter` -* `HostEvent.RemoveColumn` -* `HostEvent.ResetSearch` -* `EmbedEvent.CrossFilterChanged` -* `EmbedEvent.DownloadAsPng` -* `EmbedEvent.VizPointRightClick` - -For more information, see xref:embed-events.adoc[Events]. - -|[tag redBackground]#DEPRECATED# a| - -The following events are deprecated from version 1.21.0 onwards. - -* `HostEvent.Download` + -* `EmbedEvent.Download` - -You can use the `DownloadAsPng`, `DownloadAsXlsx`, `DownloadAsCsv` and `DownloadAsPdf` events for download actions. - -For more information, see xref:embed-events.adoc[Events reference]. -|[tag orangeBackground]#MODIFIED# a| - -Events:: -The SDK supports omitting or executing a search query in xref:HostEvent.adoc#_search[`HostEvent.Search`]. -Actions:: -Use the following action enumeration members instead of `Action.Download` to show, hide, or disable the *Download* menu action on an embedded Liveboard, visualization, or Answer: -+ -* `Action.DownloadAsCsv` -* `Action.DownloadAsPdf` -* `Action.DownloadAsXlsx` -* `Action.DownloadAsPng` - -To disable or hide download actions, you can use `Action.Download` in the `disabledActions` and `hiddenActions` arrays respectively. However, if you are using the `visibleActions` array to show or hide actions on a visualization or Answer, include the following download action enumerations along with `Action.Download` in the array: + - -** `Action.DownloadAsCsv` + -** `Action.DownloadAsPdf` + -** `Action.DownloadAsXlsx` + -** `Action.DownloadAsPng` - -|[tag greenBackground]#NEW FEATURE# a| The SDK includes new attributes to customize the experience for embedded app users: - -* `linkOverride` -+ -Allows overriding the *Open in new tab* link on embedded pages. - -* `contextMenuTrigger` -+ -Allows triggering contextual menu on the Liveboard visualizations and Answers from left-click to right-click. - -* `hideSearchBar` -+ -Allows hiding the Search bar on the embedded Search page. -|[tag greenBackground]#NEW FEATURE# | The SDK now allows setting the loading preference for embedded iFrames. -For performance optimization, you can set the `loading` attribute to `lazy` in the `FrameParams` property. -|==== - -== Version 1.20.0, April 2023 - -[width="100%" cols="1,4"] -|==== -|[tag redBackground]#DEPRECATED# a|The `dataSources` property in `SearchEmbed` and `SearchBarEmbed` is deprecated and replaced with the `dataSource` attribute. The SDK supports searching from a single data source only. -|[tag greenBackground]#NEW FEATURE# a|The embed SDK packages now include the `insertAsSibling` property. This attribute can be used to insert the embedded object as a sibling to the element inside the target container. -|==== - -== Version 1.19.0, February 2023 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a|The `customCSS` property in the `customizations` object supports new variables to customize the styles for dialogs, search bar, search navigation and search suggestions panels. -For more information, see xref:css-customization.adoc[Customize CSS]. -|[tag redBackground]#BREAKING CHANGE# a|The new Liveboard experience mode introduces changes to the data format of the JSON response payload triggered by callback custom actions. For example, the `reportBookData`, and `vizData` attributes are modified, and the custom action `id` now is part of the data attribute. These changes may break your current custom action event handlers. For interoperability, we recommend adding the data attribute to `payload` in your code as shown in the example here: - -[source,JavaScript] ----- -liveboardEmbed.on(EmbedEvent.CustomAction, payload => { - if (payload.id === "callback-action-id" \|\| payload.data.id === "callback-action-id") { - console.log('Custom Action event:', payload.data); - } -}) ----- - -You may also want to update the data classes in your scripts to process the JSON response payload and handle complex data. For more information, see xref:custom-actions-callback.adoc#_define_functions_and_classes_to_handle_liveboard_data[Callback custom actions]. - -|[tag greenBackground]#NEW FEATURE# a|The new version of the SDK introduces the following Host events: - -* `HostEvent.Delete` -* `HostEvent.Download` -* `HostEvent.DownloadAsCsv` -* `HostEvent.DownloadAsXlsx` -* `HostEvent.ManagePipelines` -* `HostEvent.Save` -* `HostEvent.Share` -* `HostEvent.ShowUnderlyingData` -* `HostEvent.SpotIQAnalyze` -* `HostEvent.SyncToOtherApps` -* `HostEvent.SyncToSheets` - -For more information, see xref:events-hostEvents.adoc[Host events]. - -|[tag redBackground]#DEPRECATED# a|The `noRedirect` property in the SDK is deprecated and replaced with the `inPopup` attribute. When set to `true`, the `inPopup` attribute allows the SAML SSO authentication flow in a pop-up window. - -For more information, see xref:embed-authentication.adoc#_saml_redirection[SAML Redirection]. -|==== - -== Version 1.18.0, January 2023 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a|The new version of the SDK provides the `SearchBarEmbed` JavaScript package to embed only the ThoughtSpot Search bar in your app. + - -For more information, see xref:embed-searchbar.adoc[Embed ThoughtSpot search bar]. - -|[tag greenBackground]#NEW FEATURE# a|The `customCSS` property in the `customizations` object supports new variables to customize the UI elements on Liveboard, visualization, and Answer pages. You can also use these variables to define custom styles in the CSS file. + -For more information, see xref:css-customization.adoc[Customize CSS]. -|[tag greenBackground]#NEW FEATURE# |The new version of the SDK allows fetching TML objects via `GetTML` host event. This event is triggered when a user clicks on the *Show underlying data* action on a Liveboard visualization or Answer page. + - -For more information, see xref:HostEvent.adoc#_gettml[GetTML]. - -|[tag greenBackground]#NEW FEATURE# a| The new version of the SDK introduces the following enums in the `Action` object: - -* `Action.SyncToOtherApps` + -* `Action.SyncToSheets` + -* `Action.ManagePipelines` + - -You can use these enums to show, hide, or disable *Sync to sheets*, *Sync to other apps*, and *Manage pipelines* menu actions on a Liveboard visualization or Answer. - -For more information, see xref:embed-action-ref.adoc[Actions]. -|==== - -== Version 1.17.1, December 2022 - -Bug fixes to the trusted authentication feature. - -== Version 1.17.0, November 2022 - -The new version of the SDK introduces several new features and enhancements. -[width="100%" cols="1,4"] -|==== -|[tag orangeBackground]#MODIFIED# a|The `AuthType` property is modified and supports new enums. + - -* `AuthType.SAML` is renamed as `AuthType.SAMLRedirect` + -* `AuthType.OIDC` is renamed as `AuthType.OIDCRedirect` + -* `AuthType.AuthServer` is renamed to `AuthType.TrustedAuthToken` + -This enhancement does not introduce any breaking changes to your current implementation. -|[tag greenBackground]#NEW FEATURE# a|To use your current SAML or OIDC authentication setup and redirect users to the IdP for authentication within the embedded iFrame, you can now use `AuthType.EmbeddedSSO`. + -For more information, see xref:embed-authentication.adoc[Authentication]. -|[tag greenBackground]#NEW FEATURE#| -The `customizations` object in the SDK allows you to specify a custom CSS URL. You can also use this object to define CSS variables directly in the `init` code. + -For more information, see xref:css-customization.adoc[Customize CSS]. -|==== - -== Version 1.16.0, October 2022 - -The new version of the SDK includes bug fixes and improvements to the new Liveboard experience. - -== Version 1.15.1, September 2022 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE#| -The `prefetch` method now supports the `url` and `prefetchFeatures` parameters. You can use these parameters to call the prefetch method before `init` and prefetch static resources on application load. + -For more information, see xref:prefetch-and-cache.adoc[Prefetch static resources]. -|==== - -== Version 1.15.0, September 2022 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE#| -For embedded instances with the new Liveboard experience, the Visual Embed SDK provides the `activeTabId` attribute, using which you can set a Liveboard tab as an active tab. - -For more information, see xref:embed-pinboard.adoc#_liveboard_tabs[Customize Liveboard tabs]. - -|[tag greenBackground]#NEW FEATURE# a|The new version of the SDK supports firing events for Liveboard menu actions from the host application. The SDK introduces the following host event enumeration members for Liveboard objects: - -* CopyLink -* CreateMonitor -* DownloadAsPdf -* Edit -* EditTML -* Explore -* ExportTML -* LiveboardInfo -* MakeACopy -* ManageMonitor -* Pin -* Present -* Remove -* Schedule -* SchedulesList -* UpdateTML - -For more information, see xref:events-hostEvents.adoc[Events reference]. -|==== - -== Version 1.14.0, August 2022 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE#| -The Visual Embed SDK now includes the `liveboardV2` attribute in the `LiveboardEmbed` package to allow developers to enable the new Liveboard experience on their embedded ThoughtSpot instance. + -For more information, see xref:embed-pinboard.adoc[Embed a Liveboard]. -|[tag orangeBackground]#MODIFIED#|If trusted authentication is enabled, the SDK makes a `POST` API call to get a login token and log the user into ThoughtSpot. -The earlier versions of the SDK supported only `GET` API requests. For more information, see xref:embed-authentication.adoc#_configure_token_based_authentication_method_in_visual_embed_sdk[Configure token-based authentication method in Visual Embed SDK]. -|==== - -== Version 1.13.0, July 2022 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE#| -This version of Visual Embed SDK includes the `enableSearchAssist` attribute, using which you can turn on the Search Assist feature on an embedded instance. -|[tag greenBackground]#NEW FEATURE#| The new version of SDK introduces the `AuthType.SAML` enum for SAML-based SSO authentication. Note that `AuthType.SAML` replaces the `AuthType.SSO` enum, which is deprecated in the v1.13.0 version of the SDK. + -For more information, see xref:embed-authentication.adoc#saml-sso-embed[Authentication]. -|[tag redBackground]#DEPRECATED#| The `AuthType.SSO` enum is deprecated in v1.13.0. ThoughtSpot recommends using `AuthType.SAML` for the SAML SSO authentication method. + -This change does not impact your current embed implementation with `AuthType.SSO`. -|[tag greenBackground]#NEW FEATURE#| The SDK includes the `getExportRequestForCurrentPinboard` event, which is triggered when a user tries to export a Liveboard in its current state. + -For more information, see xref:events-hostEvents.adoc[Events reference]. -|==== - -== Version 1.12.0, June 2022 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE#| -This version of Visual Embed SDK introduces the `navigate` host event, which is triggered when a user navigates to an application page without a page reload. - -For more information, see xref:events-hostEvents.adoc[Events reference]. -|[tag greenBackground]#NEW FEATURE# | The new `getThoughtSpotPostUrlParams` method fetches ThoughtSpot URL query parameters prefixed with `ts-`. -|==== - -== Version 1.11.2, June 2022 - -Bug fix for Typescript builds that affect Angular project configurations. - -== Version 1.11.1, May 2022 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE#| The SDK includes the action enum `ReportError`, using which you can turn off ThoughtSpot-specific error reporting. -|==== - -== Version 1.11.0, May 2022 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| The new version of SDK includes the following new events: - -* `ALL` -* `AnswerChartSwitcher` -* `AnswerDelete` -* `CopyAEdit` -* `CopyToClipboard` -* `Download` -* `DownloadAsPdf` -* `DownloadAsCsv` -* `DownloadAsXlsx` -* `DrillExclude` -* `DrillInclude` -* `EditTML` -* `ExportTML` -* `Monitor` -* `Pin` -* `Save` -* `SaveAsView` -* `Share` -* `ShowUnderlyingData` -* `SpotIQAnalyze` -* `UpdateTML` -* `VizPointClick` - -For more information about how to register and handle these events, see xref:embed-events.adoc[Events and app integration]. -|[tag greenBackground]#NEW FEATURE# a| The new version of SDK supports the `showAlerts` attribute, using which you can show or hide alerts and error messages in the embedded view. - -|[tag greenBackground]#NEW FEATURE# a| The `Action.CreateMonitor` enumeration is available in the SDK for embedded ThoughtSpot environments on which the *Monitor* feature is enabled. -For more information, see xref:embed-actions.adoc[Show or hide UI actions]. -|==== - -== Version 1.10.4, May 2022 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE#|The `detectCookieAccessSlow` parameter in the SDK allows your app to check if third-party cookies are enabled on the browser. This parameter is available only for trusted and `Basic` authentication types. -|==== -== Version 1.10.3, May 2022 - -Bug fix and improvements to the `logout` method. - -== Version 1.10.2, May 2022 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE#|Ability to configure `redirectPath` on the origin when using the SAMLRedirect `authType`. -|==== - -== Version 1.10.1, May 2022 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE#|You can now use the `logout` method to log out embed users. -|[tag orangeBackground]#MODIFIED# a| Note the following changes: + - -* You can now use the `loginFailedMessage` property on init to display the `Not logged in` message when a user login fails. You can customize this message by defining a custom text string in the `loginFailedMessage` attribute. -* The `init` method now returns an event emitter which can be used to listen to `AuthStatus` such as login failure, success, or user logout. -|==== - -== Version 1.10.0, April 2022 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| The `AddRemoveColumns` event is now available in the SDK. For more information, see xref:event-embedEvents.adoc[Events reference]. -|==== - -== Version 1.9.8, April 2022 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE#|The `pageId` attribute now allows you to set the **SpotIQ** page as the home tab of your embedded ThoughtSpot app. - -For more information, see xref:full-embed.adoc[Embed full application]. -|==== - -== Version 1.9.6 and 1.9.7, April 2022 - -Bug fixes and improvements - -== Version 1.9.5, April 2022 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE#|The `locale` attribute is now available in embed packages. You can use this attribute to set the locale or language of your embedded application view. -For more information, see xref:locale-setting.adoc[Set locale and display language]. -|==== - -== Version 1.9.4, April 2022 - -Bug fixes and improvements to React components. - -== Version 1.9.3, March 2022 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE#| The SDK now supports the `disableLoginRedirect` attribute to improve the login experience for your application users. When enabled, this attribute prevents your app from redirecting users to the login page when their session expires. + -You can use this attribute along with `autoLogin` to automatically authenticate and re-login a user. + -This feature is applicable to token-based authentication, that is, when the `AuthType` is set as `TrustedAuthToken` in the SDK. - -For more information, see xref:embed-authentication.adoc#trusted-auth-embed[Authentication]. -|==== - -== Version 1.9.2, March 2022 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE#| You can now trigger events on React components using the `useEmbedRef` hook. - -For more information, see xref:embed-ts-react-app.adoc[Embed ThoughtSpot in a React app]. -|==== - -== Version 1.9.1, March 2022 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE#| The SDK now includes the `visibleVizs` attribute in the `LiveboardEmbed` package. This attribute allows you to add visualization GUIDs that you want to display when a Liveboard renders for the first time. - -For more information, see xref:embed-pinboard.adoc[Embed a Liveboard]. - -|[tag greenBackground]#NEW FEATURE# a| The following events are now available in the SDK: + - -* `LiveboardRendered` (EmbedEvent) - -For more information, see xref:event-embedEvents.adoc[Events reference]. -|==== - -== Version 1.9.0, March 2022 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| The SDK now includes the following new enumerations for UI actions: - -* `Action.AnswerDelete` + -* `Action.AnswerChartSwitcher` + -* `Action.AddToFavorites` + -* `Action.EditDetails` + - -For more information, see xref:embed-actions.adoc#standard-actions[Show or hide UI actions]. - -|[tag greenBackground]#NEW FEATURE# a| The SDK now supports the `UpdateRuntimeFilters` host event. For more information, see xref:events-hostEvents.adoc[Events reference]. -|==== - -== Version 1.8.x, February 2022 - -[width="100%" cols="1,4"] -|==== -|[tag redBackground]#BREAKING CHANGE# | The `autoLogin` attribute is now set as `false` by default. This attribute is used in the `init` method to automatically re-login a user when a session expires. -|[tag greenBackground]#NEW FEATURE# | The `init` method now returns the `authPromise` which resolves when a user authentication is completed. -|==== - - -== Version 1.7.0, January 2022 - -[width="100%" cols="1,4"] -|==== -| -[tag greenBackground]#NEW FEATURE# |+++
OIDC AuthType
+++ - -The SDK supports the `OIDC` `authType` in `init` calls. If you want your application users to authenticate to an OpenID provider and use their SSO credentials to access the embedded ThoughtSpot content, you can enable the `OIDC` authentication type in the SDK. - -For more information, see xref:embed-authentication.adoc#oidc-auth[Authentication and security attributes]. -|[tag greenBackground]#NEW FEATURE# a|+++
Embed events
+++ - -The SDK includes the following new event: - -* `RouteChange` - -For more information, see xref:event-embedEvents.adoc[Events reference]. - -|==== - -== Version 1.6.x, November 2021 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a|+++
Visible actions
+++ - -You can now configure a set of ThoughtSpot UI actions as visible actions and display these actions in the embedded UI. If your embedded instance requires only a few actions, you can use the `visibleActions` API to show only these actions in the embedded ThoughtSpot UI. - -For more information, see xref:embed-actions.adoc[Show or hide UI actions]. - -|[tag orangeBackground]#MODIFIED# | +++
Terminology changes
+++ - -The SDK library and object parameter names are modified to rebrand pinboards as Liveboards. For a complete list of changes, see xref:terminology-update.adoc#sdk-changes[Terminology changes]. - -|[tag greenBackground]#NEW FEATURE# a|+++
Embed events
+++ - -The SDK supports the following new events: - -* `DialogOpen` -* `DialogClose` - -For more information, see xref:event-embedEvents.adoc[Events reference]. -|==== - -== Version 1.5.0, October 2021 - -[width="100%" cols="1,4"] -|==== -|| -|[tag greenBackground]#NEW FEATURE# | +++
Render embedded objects in queue
+++ - -The SDK now supports rendering embedded objects in a queue. If you have multiple embedded objects, you can enable the `queueMultiRenders` parameter to queue your embedded objects and render them one after another. This feature helps in decreasing the load on the web browsers and improving your application loading experience. By default, this attribute is set to `false`. - -|[tag greenBackground]#NEW FEATURE# a|+++
Liveboard embed
+++ - -The `pinboardEmbed` package includes the `defaultHeight` attribute that sets a minimum height for embedded objects on a pinboard page, and the corresponding visualization pages that a user can navigate to. - -For more information, see xref:embed-search.adoc[Embed a pinboard]. - -|[tag greenBackground]#NEW FEATURE# a|+++
Embed events
+++ - -The SDK EmbedEvent library includes the following new events: - -* `VizPointDoubleClick` -* `Drilldown` -* `SetVisibleVizs` - -For more information, see xref:event-embedEvents.adoc[Events reference]. - -|==== - -== Version 1.4.0, September 2021 - -[width="100%" cols="1,4"] -|==== -|| -|[tag greenBackground]#NEW FEATURE# a|+++
+++Prefetch API+++
+++ - -The `prefetch` API fetches static resources from a given URL before your application loads. Web browsers can then cache the prefetched resources locally and serve them from a user's local disk. You can use this API to load the embedded objects faster and improve your application response time. - -For more information, see xref:prefetch-and-cache.adoc[Prefetch static resources]. - -|[tag greenBackground]#NEW FEATURE# a|+++
+++In-app page navigation+++
+++ - -The `navigateToPage` method in the SDK lets you provide quick and direct access to a specific pinboard, saved Answer, or an application page. You can add a custom menu action or button in your application UI that calls the `navigateToPage` method and leads your users to the page specified in the `path` parameter. - -For more information, see xref:page-navigation.adoc[Add a custom action for in-app navigation]. - -|[tag greenBackground]#NEW FEATURE# a|+++
+++Full application embedding+++
+++ - -The `appEmbed` SDK package includes the following new attributes: - -* The `disableProfileAndHelp` attribute to show or hide the `Help (?)` and the user profile menu in the navigation bar of your embedded app. - -* The `hideObjects` attribute to hide specific objects from a user's page view. - -For more information, see xref:full-embed.adoc[Embed full application]. - -|[tag greenBackground]#NEW FEATURE# |+++
+++Search embed +++
+++ - -The `searchEmbed` package includes the `forceTable` attribute that sets tabular view as the default format for presenting search data. You can set this attribute to `true` to force search results to appear in the table view. - -For more information, see xref:embed-search.adoc[Embed ThoughtSpot search]. - -|[tag redBackground]#REMOVED# | - -The `searchQuery` parameter is no longer supported and is removed from the `searchEmbed` SDK package. -|[tag greenBackground]#NEW FEATURE# a|+++
+++Embed events +++
+++ -The SDK EmbedEvent library includes the following events: - -* `QueryChanged` -* `AuthExpire` - -For more information, see xref:embed-events.adoc[Events and app integration]. -|==== - -== Version 1.3.0, August 2021 - -[width="100%" cols="1,4"] -|==== -|| -|[tag greenBackground]#NEW FEATURE# a| +++
searchOptions
+++ - -The `searchEmbed` SDK package introduces the `searchOptions` parameter for setting search tokens. The `searchOptions` parameter includes the following attributes: - -* `searchTokenString` -+ -A TML query string to define search tokens. - -* `executeSearch` -+ -When set to `true`, it executes search and shows the search results. - -For more information, see xref:embed-search.adoc#search-query[Embed ThoughtSpot search]. - -|[tag redBackground]#DEPRECATED# a| +++
searchQuery
+++ - -The `searchQuery` parameter in the `searchEmbed` SDK package is deprecated in the Visual Embed SDK version 1.3.1. Instead, you can use the `searchOptions` parameter to define the search token string. - -For more information about `searchOptions`, see xref:embed-search.adoc#search-query[Embed ThoughtSpot search]. - -|[tag greenBackground]#NEW FEATURE# a| +++
autoLogin
+++ - -The SDK now supports logging in users automatically after a user session has expired. - -For more information, see xref:embed-authentication.adoc#embed-session-sec[Embed user authentication]. - -|[tag greenBackground]#NEW FEATURE# a| +++
shouldEncodeUrlQueryParams
+++ - -You can now convert query parameters in the ThoughtSpot generated URLs to base64-encoded format. You can enable this attribute to secure your cluster from cross-site scripting attacks. -|[tag redBackground]#BREAKING CHANGE# a| +++
Data structure changes in custom action response payloads
+++ - -* The data structure passed in the custom action response for search now shows as `payload.data.embedAnswerData` instead of `payload.data.columnsAndData`. - -* The Answer payload for custom actions includes the following metadata: - -** `reportBookmetadata` -+ -Includes visualization metadata attributes such as description, object header metadata, author details, timestamp of the Answer creation, and modification. - -** user data -+ -Includes user information such as username, GUID of the user, and email address. - -To view a sample response payload, see xref:callback-response-payload.adoc#search-data-payload[Custom action response payload]. - -|[tag greenBackground]#NEW FEATURE# a| +++
preventPinboardFilterRemoval
+++ - -The `pinboardEmbed` SDK package now includes the `preventPinboardFilterRemoval` attribute. You can use this attribute to disable the filter removal action and thus prevent users from removing the filter chips added on a pinboard page. - -For more information, see xref:embed-pinboard.adoc[Embed a pinboard] and xref:embed-a-viz.adoc[Embed a visualization]. -|[tag greenBackground]#NEW FEATURE# a| +++
suppressNoCookieAccessAlert
+++ - -You can now set custom alerts for `noCookieAccess` events. By default, the SDK triggers a `noCookieAccess` event and generates an alert when a user's browser blocks third-party cookies. The `suppressNoCookieAccessAlert` allows you to disable this alert. - -|[tag greenBackground]#NEW FEATURE# a| +++
Support for fetching callback custom action payload in batches
+++ - -The Visual Embed SDK now supports processing data in batches for callback custom action responses. -The callback custom action event in the SDK package supports defining `batchSize` and `offset` values to paginate the Answer payload and send the records in batches. - -For more information, see xref:push-data-to-external-app.adoc#large-dataset[Callback custom action workflow]. -|==== - -== Version 1.2.0, June 2021 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a|+++
SAML authentication
+++ - -The Visual Embed SDK packages now include the `noRedirect` attribute as an optional parameter for the SAMLRedirect SSO `AuthType`. If you want to display the SAML authentication workflow in a pop-up window, instead of refreshing the application web page to direct users to the SAML login page, you can set the `noRedirect` attribute to `true`. - -For more information, see the instructions for embedding xref:full-embed.adoc[ThoughtSpot pages], xref:embed-search.adoc[search], xref:embed-pinboard.adoc[pinboard], and xref:embed-a-viz.adoc[visualizations]. - -|[tag greenBackground]#NEW FEATURE# a|+++
Pinboard actions
+++ -The *More* menu image:./images/icon-more-10px.png[the more options menu] in the embedded Pinboard page now shows the following actions for pinboard and visualizations. - -Pinboard:: -* Save -* Make a copy -* Add filters -* Configure filters -* Present -* Download as PDF -* Pinboard info -* Manage schedules - - -[NOTE] -Users with edit permissions can view and access the *Save*, *Add filters*, *Configure filters*, and *Manage schedules* actions. -|[tag greenBackground]#NEW FEATURE# a|+++
Visualization actions
+++ - -Visualizations on a pinboard: - -* Pin -* Download -* Edit -* Present -* Download as CSV -* Download as XLSX -* Download as PDF - -[NOTE] -Users with edit permissions can view and access the *Edit* action. The *Download as CSV*, *Download as XLSX*, and *Download as PDF* actions are available for table visualizations. The *Download* action is available for chart visualizations. - -|==== - -== Version 1.1.0, May 2021 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a|+++
NoCookieAccess event
+++ - -When a user accesses the embedded application from a web browser that has third-party cookies disabled, the Visual Embed SDK emits the `NoCookieAccess` event to notify the developer. Cookies are disabled by default in Safari. Users can enable third-party cookies in Safari’s Preferences setting page or use another web browser. -To know how to enable this setting by default on Safari for a ThoughtSpot embedded instance, contact ThoughtSpot Support. -|==== \ No newline at end of file From 3a06bdb2e5ee9805037547f19e5ce748cfecbfd2 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 17 Aug 2026 09:43:02 +0530 Subject: [PATCH 05/32] docs: add Spotter conversation sharing APIs section (aug.26.mt, SCAL-306173) --- modules/ROOT/pages/spotter-agent-apis.adoc | 1205 +++----------------- 1 file changed, 163 insertions(+), 1042 deletions(-) diff --git a/modules/ROOT/pages/spotter-agent-apis.adoc b/modules/ROOT/pages/spotter-agent-apis.adoc index 5ea2587af..58dcbf738 100644 --- a/modules/ROOT/pages/spotter-agent-apis.adoc +++ b/modules/ROOT/pages/spotter-agent-apis.adoc @@ -61,6 +61,18 @@ a| `POST /api/rest/2.0/ai/relevant-questions/` [beta betaBackground]^Beta^ + xref:spotter-agent-apis.adoc#_get_relevant_questions[Decomposes a user query] into relevant sub-questions. Guides users to explore data more deeply for a comprehensive analysis. + __Available on ThoughtSpot Cloud instances from 10.13.0.cl onwards__. +a| `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` [.version-badge.new]#New# + +xref:spotter-agent-apis.adoc#_sharing_spotter_conversations[Shares a saved Spotter conversation] with one or more users or groups. + +__Available on ThoughtSpot Cloud instances from 26.9.0.cl onwards.__ + +a| `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content` [.version-badge.new]#New# + +xref:spotter-agent-apis.adoc#_get_shared_content[Returns the shared content] of a Spotter conversation, including messages and associated answers. + +__Available on ThoughtSpot Cloud instances from 26.9.0.cl onwards.__ + +a| `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info` [.version-badge.new]#New# + +xref:spotter-agent-apis.adoc#_get_share_information[Returns sharing metadata] for a Spotter conversation — the list of principals it is shared with. + +__Available on ThoughtSpot Cloud instances from 26.9.0.cl onwards.__ + a| `POST /api/rest/2.0/ai/agent/converse/sse` [.version-badge.deprecated]#Deprecated# + Legacy API endpoint for streaming responses, including tokens and visualizations, for a specific conversation context. __Deprecated in 26.5.0.cl__. @@ -112,57 +124,31 @@ With AUTO_MODE for metadata context:: [source,cURL] ---- curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/create' \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/create' \ + -H 'Authorization: Bearer {access-token}' \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {AUTH_TOKEN}' \ --data-raw '{ "metadata_context": { "type": "AUTO_MODE" - }, - "conversation_settings": { - "enable_save_chat": true } }' ---- -For a single data source as the data context:: +With DATA_SOURCE for metadata context:: [source,cURL] ---- curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/create' \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/create' \ + -H 'Authorization: Bearer {access-token}' \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {AUTH_TOKEN}' \ --data-raw '{ "metadata_context": { "type": "DATA_SOURCE", "data_source_context": { - "data_source_identifier": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" - } - }, - "conversation_settings": {} -}' ----- - -For multi-data source context:: - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/create' \ - -H 'Accept: application/json' \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {AUTH_TOKEN}' \ - --data-raw '{ - "metadata_context": { - "type": "DATA_SOURCE", - "data_source_context": { - "data_source_identifiers": [ - "a1b2c3d4-e5f6-7890-abcd-ef1234567890", - "b2c3d4e5-f6a7-8901-bcde-f12345678901" - ] + "data_source_identifier": "" } }, "conversation_settings": { @@ -171,1122 +157,257 @@ curl -X POST \ }' ---- -=== API response - -If the API request is successful, the API returns the conversation ID and identifier in the response body. - -[source,JSON] ----- -{ - "conversation_id": "wwHQ5j8O8dQC", - "conversation_identifier": "wwHQ5j8O8dQC" -} ----- - -* `conversation_identifier` + -Use this for all subsequent message calls. -* `conversation_id` [.version-badge.deprecated]#Deprecated# + -Returns the same value as `conversation_identifier`. - == Send queries to a conversation session -To send queries to an ongoing conversation session with the Spotter agent and receive a response synchronously, use the `/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send` API endpoint. - -This API operation requires the conversation ID obtained from the conversation creation API endpoint (`/api/rest/2.0/ai/agent/conversation/create`). The user making the API request must have access to the conversation session. The API request body must include at least one message in natural language format. +The `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send` API endpoint sends a natural language query to an existing Spotter agent conversation and returns the complete response synchronously. === Request parameters -[width="100%" cols="2,2,4"] +[width="100%" cols="2,4"] [options='header'] |===== -|Parameter|Type| Description -|`conversation_identifier`|Path parameter|__String__. Required. Specify the conversation ID received from the xref:spotter-agent-apis.adoc#_create_a_conversation_session_with_spotter_agent[POST /api/rest/2.0/ai/agent/conversation/create] API call. -|`messages`|Form parameter|_Array of strings_. Required. Specify at least one query in natural language. For example, `total sales of jackets last month`. +|Form parameter| Description +|`message` | The natural language query to send to the Spotter agent. +|`conversation_identifier` | GUID of the existing conversation session. Pass this in the URL path. |===== - -//// -|`settings` |__Optional__. Defines additional parameters for the conversation context. You can set any of the following attributes as needed: - -* `enable_contextual_change_analysis` + -__Boolean__. When enabled, Spotter analyzes how the context changes over time, that is comparing results from different queries. -* `enable_natural_language_answer_generation` + -__Boolean__. Allows sending natural language queries to the conversation session. -* `enable_reasoning` + -__Boolean__. Allows Spotter to use reasoning for deep analysis and precise responses. -//// - -=== Request and response examples - -The following example sends a data comparison query to a conversation session. The conversation ID is specified in the request URL as a path parameter. +=== Example request [source,cURL] ---- curl -X POST \ --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {AUTH_TOKEN}' \ --data-raw '{ - "messages": [ - "Sales in 2025 vs 2024" - ] + "message": "What are the top 10 products by revenue?" }' ---- -If the request is successful, the API returns an array of objects in the response. The messages in the API response include the following parts: +== Send a query to agent and get streaming responses -[source,JSON] ----- -[ - { - "type": "text", - "text": "\n\nI'll compare sales between 2025 and 2024. First, let me get the dataset context.", - "metadata": {}, - "internal": {}, - "agent_context": "" - }, - { - "type": "text", - "text": "```json\n{\"dataset_name\":\"(Sample) Retail - Apparel\",\"columns\":[{\"name\":\"sales\",\"type\":\"MEASURE\"},{\"name\":\"date\",\"type\":\"ATTRIBUTE\"}]}\n```", - "metadata": {}, - "internal": {}, - "agent_context": "" - }, - { - "type": "answer", - "title": "Compare total sales for 2025 vs 2024", - "description": "", - "session_id": "842bb67a-e08e-4861-97e8-8db9538db51d", - "gen_no": 2, - "sage_query": "[sales] [date] = '2025' vs [date] = '2024'", - "tml_tokens": ["[sales]", "[date] = '2025' vs [date] = '2024'"], - "formulas": [], - "parameters": [], - "subqueries": [], - "viz_suggestion": "CAEQIBomEiQ2NjE5NzI0Yy1kMjVlLTU4MDItOWNjOC1jNDA3MWY3OWY5MzAoATIA", - "metadata": { - "output": "", - "worksheet_id": "cd252e5c-b552-49a8-821d-3eadaa049cca", - "chart_type": "KPI", - "interrupted": false, - "data_awareness_enabled": true - }, - "internal": {} - }, - { - "type": "text", - "text": "\n\nThe visualization shows year-over-year comparison. You can identify growth or decline trends.", - "metadata": {}, - "internal": {}, - "agent_context": "" - } -] ----- +The `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream` API endpoint sends a natural language query to an existing Spotter agent conversation and returns the response as a real-time Server-Sent Events (SSE) stream. -The following example sends a follow-up question to the same conversation session. +=== Example request [source,cURL] ---- curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send' \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: text/event-stream' \ -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {AUTH_TOKEN}' \ --data-raw '{ - "messages": [ - "Now break that down by product category" - ] + "message": "Show me monthly revenue trends" }' ---- -If the request is successful, the agent returns the response for the follow-up question: - -[source,JSON] ----- -[{ - "type": "text", - "text": "I'll add product category to the comparison.", - "metadata": {}, - "internal": {}, - "agent_context": "" - }, - { - "type": "answer", - "title": "Sales by Product Category: 2025 vs 2024", - "session_id": "9abc1234-0000-0000-0000-000000000005", - "gen_no": 3, - "sage_query": "[sales] [product category] [date] = '2025' vs [date] = '2024'", - "tml_tokens": ["[sales]", "[product category]", "[date] = '2025' vs [date] = '2024'"], - "formulas": [], - "parameters": [], - "subqueries": [], - "viz_suggestion": "", - "metadata": { - "chart_type": "BAR", - "worksheet_id": "cd252e5c-b552-49a8-821d-3eadaa049cca" - }, - "internal": {} - }] ----- - -In each response, the agent returns the following information: - -* `type` + -Type of the message, such as text, answer, or error. -* `text` + -Response message generated for the query. -* `metadata` + -Additional information based on the message type. For example, answer metadata, chart type, or the data source ID. -* `tml_tokens` + -Query string broken down as TML tokens. - -In case of errors, the response returns the error details: - -[source,JSON] ----- -[{ - "type": "error", - "message": "The conversation session has expired. Please create a new conversation.", - "code": "SESSION_EXPIRED" -}] ----- - +== Stop an in-progress agent response +The `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response` API endpoint stops an in-progress Spotter agent response. The conversation session remains active after the response stops. -//// -The following example shows the response text contents for the `answer` message type. +=== Example request -[source,JSON] +[source,cURL] ---- -[ - { - "id": "r24X7D99SROD", - "type": "answer", - "group_id": "o8dQ9SAWdtrL", - "metadata": { - "sage_query": "[sales] [item type] = [item type].'jackets'", - "session_id": "b321b404-cbf1-4905-9b0c-b93ad4eedf89", - "gen_no": 1, - "transaction_id": "6874259d-13b1-478c-83cb-b3ed52628850", - "generation_number": 1, - "warning_details": null, - "ambiguous_phrases": null, - "query_intent": null, - "assumptions": "You want to see the total sales amount for jackets item type.", - "tml_phrases": [ - "[sales]", - "[item type] = [item type].'jackets'" - ], - "cached": false, - "sub_queries": null, - "title": "Net sales of Jackets", - "worksheet_id": "cd252e5c-b552-49a8-821d-3eadaa049cca" - }, - "title": "Net sales of Jackets" - } -] +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + --data-raw '{}' ---- -The session ID and generation number serve as the data context for the Answer. You can use this information to create a new conversation session using `/api/rest/2.0/ai/agent/conversation/create`, or download the answer via the `/api/rest/2.0/report/answer` API endpoint. - - -* The tokens and TML phrases returned in the response can be used as inputs for the search data API call to get an Answer. -//// +== Get data source suggestions -== Send a query to agent and get streaming responses - -To send queries to an ongoing conversation session with Spotter agent and receive streaming responses, use the `/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream` API endpoint. This API endpoint uses the SSE protocol to deliver data incrementally in real time, rather than waiting for the entire response to be generated before sending it to the client. - -The `/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream` API can be used as an integrated tool for real-time streaming of conversational interactions between agents and the ThoughtSpot backend. - -=== Request parameters - -[width="100%" cols="2,4"] -[options='header'] -|===== -|Parameter| Description -|`conversation_identifier` |__String__. Specify the conversation ID received from the xref:spotter-agent-apis.adoc#_create_a_conversation_session_with_spotter_agent[POST /api/rest/2.0/ai/agent/conversation/create] API call. -|`messages`|_Array of strings_. Include at least one natural language query. For example, `Sales data for Jackets`, `Top performing products in the west coast`. -|===== +The `POST /api/rest/2.0/ai/data-source-suggestions` API endpoint returns a list of relevant data sources based on a query, helping users and agents choose the most appropriate data source for analytics. === Example request [source,cURL] ---- curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream' \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/data-source-suggestions' \ + -H 'Authorization: Bearer {access-token}' \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {AUTH_TOKEN}' \ --data-raw '{ - "conversation_identifier": "h2I_pTGaRQof", - "messages": [ - "Net sales of Jackets" - ] + "query": "revenue by region" }' ---- -=== API response - -If the API request is successful, the response includes a stream of events, each containing a partial or complete message from the AI agent, rather than a single JSON object. - -Each event is a simple text-based message in a specific format, `data: \n\n`; `\n\n` means that each message sent from the server to the client is prefixed with the `data:` keyword, followed by the actual payload (``), and ends with two newline characters (`\n\n`). +== Get relevant questions -The API uses this format so that the clients can reconstruct the AI-generated response as it streams in, chunk by chunk, and show the responses in real-time. In agentic workflows, the receiving client or agent listens to the SSE stream, parses each event, and assembles the full response for its users. +The `POST /api/rest/2.0/ai/relevant-questions/` API endpoint decomposes a user query into relevant sub-questions, helping users explore data more deeply for comprehensive analysis. -==== Example response -If the request is valid, the API returns SSE streams. Each line has the form `data: [{"type": "...", ...}]`, a JSON array of event objects. - -[source,JSON] ----- -data: [{"type":"ack","node_id":"aGxzcFVrtom8"}] - -data: [{"type":"conv_title","title":"Sales 2025 vs 2024","conv_id":"-XIi04l5rrof"}] - -data: [{"type":"notification","group_id":"cDEsAQbSnd3J","metadata":{"type":"thinking","tool_title":"Analyzing Sales Performance: 2025 vs 2024"},"code":"TOOL_CALL_NOTIFICATION"}] - -data: [{"id":"mNAdvy-NK2l6","type":"text-chunk","group_id":"cDEsAQbSnd3J","metadata":{"format":"markdown","type":"thinking"},"content":"\n\nI need to compare sales performance between 2025 and 2024."}] - -data: [{"type":"notification","group_id":"m1MTvttEUa7o","code":"nls_start"}] - -data: [{"id":"hxWMDP-pgR3B","type":"answer","group_id":"m1MTvttEUa7o","metadata":{"sage_query":"[sales] [date] = '2025' vs [date] = '2024'","session_id":"431adcf9-1328-4d8c-81a1-0faa7fa37ba6","title":"Compare sales for 2025 vs 2024"},"title":"Compare sales for 2025 vs 2024"}] +=== Example request -data: [{"type":"notification","code":"FINAL_RESPONSE_NOTIFICATION"}] +[source,cURL] ---- -For the complete response in one payload, use the xref:spotter-agent-apis.adoc#_send_queries_to_a_conversation_session[`/send` endpoint] instead. - -//// -[source,] +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/relevant-questions/' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "query": "What drives customer churn?", + "data_source_identifiers": [""] +}' ---- -data: [{"type": "ack", "node_id": "BRxCtJ-aGt8l"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": "I"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " understand"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " you're"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " interested"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " in"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " the"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " net"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " sales"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " of"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " Jackets"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": "."}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " I'll"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " retrieve"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " the"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " relevant"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " data"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " for"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " you"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": "."}] - -data: [{"type": "notification", "group_id": "o8dQ9SAWdtrL", "metadata": {"title": "Net sales of Jackets"}, "code": "nls_start"}] - -data: [{"type": "notification", "group_id": "o8dQ9SAWdtrL", "code": "QH", "message": "Fetching Worksheet Data"}] - -data: [{"type": "notification", "group_id": "o8dQ9SAWdtrL", "code": "TML_GEN", "message": "Translating your query with the Reasoning Engine"}] - -data: [{"type": "notification", "group_id": "o8dQ9SAWdtrL", "code": "ANSWER_GEN", "message": "Verifying results with the Trust Layer"}] - -data: [{"id": "r24X7D99SROD", "type": "answer", "group_id": "o8dQ9SAWdtrL", "metadata": {"sage_query": "[sales] [item type] = [item type].'jackets'", "session_id": "b321b404-cbf1-4905-9b0c-b93ad4eedf89", "gen_no": 1, "transaction_id": "6874259d-13b1-478c-83cb-b3ed52628850", "generation_number": 1, "warning_details": null, "ambiguous_phrases": null, "query_intent": null, "assumptions": "You want to see the total sales amount for jackets item type.", "tml_phrases": ["[sales]", "[item type] = [item type].'jackets'"], "cached": false, "sub_queries": null, "title": "Net sales of Jackets", "worksheet_id": "cd252e5c-b552-49a8-821d-3eadaa049cca"}, "title": "Net sales of Jackets"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "The"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " net"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " sales"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " for"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " Jackets"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " have"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " been"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " visual"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "ized"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " for"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " you"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "."}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " This"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " analysis"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " specifically"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " filtered"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " for"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " the"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " item"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " type"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "jackets"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "\""}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " and"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " calculated"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " the"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " total"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " sales"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " amount"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " associated"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " with"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " those"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " products"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ".\n\n"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "**"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "Summary"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " &"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " Insights"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ":"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "**\n"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "-"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " The"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " visualization"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " shows"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " the"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " total"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " net"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " sales"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " for"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " all"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " jacket"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " transactions"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " in"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " your"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " apparel"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " dataset"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ".\n"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "-"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " The"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " calculation"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " uses"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " only"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " sales"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " amounts"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " where"}] -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " the"}] +[#_sharing_spotter_conversations] +== Sharing Spotter conversations -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " item"}] +// SOURCE: SCAL-306173 (aug.26.mt) +// SOURCE: scaligent/prism/src/public-apis/nl-to-answer.graphql (master) +// SOURCE: scaligent/prism/src/public-apis/docs/descriptions/ai/share-conversation.md (master) +// SOURCE: scaligent/prism/src/public-apis/docs/descriptions/ai/get-shared-content.md (master) +// SOURCE: scaligent/prism/src/public-apis/docs/descriptions/ai/get-share-info.md (master) -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " type"}] +ThoughtSpot 26.9.0.cl introduces REST API v2.0 endpoints for sharing saved Spotter agent conversations with other users or groups. Shared conversations are always `READ_ONLY`. A conversation can be shared only if `enable_save_chat` was set to `true` when the conversation was created. -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " is"}] +=== Supported endpoints -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " \""}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "J"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "ackets"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ".\"\n"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "-"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " This"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " information"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " is"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " useful"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " for"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " understanding"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " the"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " revenue"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " contribution"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " of"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " jackets"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " within"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " your"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " product"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " mix"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ".\n\n"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "If"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " you'd"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " like"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " to"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " see"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " a"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " breakdown"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " by"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " region"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ","}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " state"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ","}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " time"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " period"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ","}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " or"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " compare"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " jacket"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " sales"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " to"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " other"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " product"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " types"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ","}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " please"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " let"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " me"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " know"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "!"}] ----- -//// - -==== SSE event types -The SSE event types streamed in the API response include: - -* `ack` + -Confirms receipt of the request. For example, the type in the first message `data: [{"type": "ack", "node_id": "BRxCtJ-aGt8l"}]`, which indicates that the server has received the client's request and is acknowledging it. -* `conv_title` + -A conversation title (`title`, `conv_id`). -* `notification` + -Progress or status update (`group_id`, `metadata`, `code`). For example, `TOOL_CALL_NOTIFICATION`, `nls_start`, `FINAL_RESPONSE_NOTIFICATION`. -* `type` + -Type can be `thinking`, `text`. -* `text` + -Complete text block in markdown format. -* `text-chunk` + -Text fragments in incremental streaming, often in markdown (`id`, `group_id`, `metadata` with `format`) -* `content` + -The actual text content sent incrementally. For example, `"I"`, `"understand"`, `"you're"`, `"interested"`, `"in"`, `"the"`, `"net"`, `"sales"`, and so on. -* `text` + -Full text block with same structure as text-chunk. -* `answer` + -Structured answer with metadata (`id`, `group_id`, `metadata` with `sage_query`, `session_id`, `title` and more) -* `error` + -In case of failures. -* `*-interrupt` + -If the generation was stopped mid-stream. -* `group_id` + -Groups related chunks together. - -For more information and examples, see xref:spotter-agent-apis.adoc#_sse_event_payload_reference[SSE event payload reference]. - -=== Thinking versus output events -Spotter responses have two phases: - -* A *thinking phase*, where the AI reasons through the query and calls internal tools, followed by an *output phase* containing the final response delivered to the user. + - -Events in the thinking phase carry `"metadata": { "type": "thinking" }`. All other events are final output. - -Every event includes a `group_id`. Events sharing the same `group_id` belong together. During the thinking phase, each tool call gets its own `group_id`. A `FINAL_RESPONSE_NOTIFICATION` notification marks the boundary between the thinking and output phases. - -[listing] ----- -THINKING PHASE -─────────────────────────────────────────────────────────── -ack - -┌─ group_id: g1 ── Tool Call 1 ("Searching data") ─────────┐ -│ notification (thinking, TOOL_CALL_NOTIFICATION) │ -│ text-chunk (thinking) │ -│ answer (thinking) │ -└──────────────────────────────────────────────────────────┘ - -┌─ group_id: g2 ── Tool Call 2 ("Running code") ───────────┐ -│ notification (thinking, TOOL_CALL_NOTIFICATION) │ -│ text-chunk (thinking) │ -│ text-chunk (thinking) │ -└──────────────────────────────────────────────────────────┘ - -notification (FINAL_RESPONSE_NOTIFICATION) ←── boundary -──────────────────────────────────────────────────────────── - -OUTPUT PHASE -──────────────────────────────────────────────────────────── -┌─ group_id: g3 ────────────────────────────────────────────┐ -│ text "Here are the results:" │ -│ answer (final visualization) │ -└───────────────────────────────────────────────────────────┘ -[stream closes] ----- - -==== Notification codes reference - -[width="100%" cols="2,4"] -[options='header'] +[width="100%"] +[options="header"] |===== -|Code| When it appears -|`QH`|Query handling started -|`TML_GEN` / `TML_GEN_RETRY`|Generating or retrying TML -|`ANSWER_GEN`|Generating an answer -|`IDENTIFYING_ATTRIBUTES`|Identifying data attributes -|`PERFORMING_CHANGE_ANALYSIS`|Running change analysis -|`PERFORMING_FORECASTING_ANALYSIS`|Running forecasting -|`SUMMARIZING_RESULTS`|Summarizing results -|`TOOL_CALL_NOTIFICATION`|Tool invocation (during thinking phase) -|`FINAL_RESPONSE_NOTIFICATION`|Marks the transition from thinking to output -|`search_datasets_start` / `search_datasets_end`|Data source discovery in progress or complete -|`approval_required`|An external tool requires user permission before proceeding +| Method | Endpoint | Description +| `POST` | `/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` | Shares a saved Spotter conversation with specified principals. Use `grant` and `revoke` arrays to manage access. +| `GET` | `/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content` | Returns the content of a shared Spotter conversation — messages, data sources, and answer details. +| `GET` | `/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info` | Returns sharing metadata — the list of principals the conversation is shared with and their access levels. |===== -=== SSE event payload reference - -==== ack - -[source,JSON] ----- -data: { - "type": "ack", - "group_id": "a1b2c3", - "id": "evt-001", - "node_id": "resp-node-abc" -} ----- - -==== notification (thinking — tool call) - -[source,JSON] ----- -data: { - "type": "notification", - "group_id": "g1", - "id": "evt-002", - "code": "TOOL_CALL_NOTIFICATION", - "message": "Searching for relevant data", - "metadata": { - "type": "thinking", - "tool_title": "Searching sales data", - "tool_code": "RUNNING_CODE_EXECUTION", - "tool_name": "code_interpreter" - } -} ----- - -==== notification (thinking - external tool with MCP integration) - -[source,JSON] ----- -data: { - "type": "notification", - "group_id": "g2", - "id": "evt-003", - "code": "TOOL_CALL_NOTIFICATION", - "message": "Querying Salesforce", - "metadata": { - "type": "thinking", - "tool_title": "Salesforce: Get Opportunities", - "tool_name": "get_opportunities", - "integration_id": "int-sf-123", - "integration_name": "Salesforce" - } -} ----- - -==== notification (approval required) -Sent when an external MCP tool requires explicit user permission before proceeding. Your application should prompt the user to approve or deny the action before continuing. - -[source,JSON] ----- -data: { - "type": "notification", - "group_id": "g2", - "id": "evt-005", - "code": "approval_required", - "metadata": { - "request_id": "perm-req-789", - "integration_id": "int-sf-123", - "integration_name": "Salesforce", - "tool_name": "get_opportunities", - "annotated_title": "Access Salesforce Opportunities" - } -} ----- - -==== notification (FINAL_RESPONSE_NOTIFICATION) - -[source,JSON] ----- -data: { - "type": "notification", - "group_id": "g1", - "id": "evt-004", - "code": "FINAL_RESPONSE_NOTIFICATION", - "message": "" -} ----- - -==== text - -[source,JSON] ----- -data: { - "type": "text", - "group_id": "g3", - "id": "evt-007", - "content": "Here is the total revenue breakdown by region for Q4 2025:\n\n- **North America:** $4.2M\n- **EMEA:** $2.8M\n- **APAC:** $1.5M" -} ----- - -==== text-chunk -Multiple chunks sharing the same `id` should be appended together to reconstruct the full text item. - -[source,JSON] ----- -data: { "type": "text-chunk", "group_id": "g3", "id": "evt-009", "content": "Based on the analysis, " } -data: { "type": "text-chunk", "group_id": "g3", "id": "evt-009", "content": "revenue grew 12% quarter-over-quarter." } ----- - -==== answer -When an `answer` event is received, the `session_id` and `gen_no` fields are returned. You can export the visualization data using the Export Answer Report API to process the results. This allows users to download the answer as a PDF, PNG, CSV, or XLSX file. - -[source,JSON] ----- -data: { - "type": "answer", - "group_id": "g3", - "id": "evt-010", - "title": "Revenue by Region Q4 2025", - "metadata": { - "session_id": "sess-abc-123", - "gen_no": 1, - "transaction_id": "txn-456", - "worksheet_id": "ws-def-789", - "cached": false, - "is_hidden": false - } -} ----- - -==== search_datasets -Emitted as a start/end pair during Auto mode data source discovery. - - -[source,JSON] ----- -data: { "type": "search_datasets", "group_id": "g0", "id": "evt-012", "code": "search_datasets_start", "metadata": {} } - -data: { - "type": "search_datasets", - "group_id": "g0", - "id": "evt-013", - "code": "search_datasets_end", - "metadata": { - "data_sources": [ - { "worksheet_id": "ws-1", "worksheet_name": "Sales Data", "confidence": "high", "reasoning": "Contains revenue columns" }, - { "worksheet_id": "ws-2", "worksheet_name": "Marketing Data", "confidence": "low", "reasoning": "No revenue columns" } - ], - "auto_selected": { "worksheet_id": "ws-1", "worksheet_name": "Sales Data", "confidence": "high", "reasoning": "Best match" } - } -} ----- -==== file - -[source,JSON] ----- -data: { - "type": "file", - "group_id": "g3", - "id": "evt-014", - "files": [ - { "ts_file_id": "file-abc-001", "display_name": "quarterly_report.csv", "file_type": "csv", "created_at": "2025-11-15T10:30:00Z" }, - { "ts_file_id": "file-abc-002", "display_name": "chart.png", "file_type": "png", "created_at": "2025-11-15T10:30:01Z" } - ], - "metadata": { "conv_id": "conv-123" } -} ----- -==== conv_title - -[source,JSON] ----- -data: { - "type": "conv_title", - "group_id": "g0", - "id": "evt-015", - "title": "Revenue Analysis Q4 2025", - "conv_id": "conv-123" -} ----- - -==== error +[NOTE] +==== +Shared conversations are always `READ_ONLY`. Shared access cannot be elevated to edit or admin level. The `notify_on_share` parameter is available from 26.10.0.cl. +==== -[source,JSON] ----- -data: { - "type": "error", - "group_id": "g3", - "id": "evt-016", - "code": "RATE_LIMIT_EXCEEDED", - "message": "Too many requests", - "display_message": "You've exceeded the rate limit. Please try again in a few minutes." -} ----- -==== agent-interrupt +[#share-conversation] +=== Share a conversation -[source,JSON] ----- -Sent when generation is stopped mid-stream. -data: { - "type": "notification", - "group_id": "g3", - "id": "evt-017", - "code": "agent-interrupt", - "message": "Generation stopped" -} ----- +`POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` -[#_stop_an_in_progress_agent_response] -== Stop an in-progress agent response +Grants or revokes access to a saved Spotter conversation. -The `/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response` API endpoint stops a Spotter agent response that is currently in progress for a given conversation session. +==== Path parameters -Use this endpoint when you want to cancel a long-running Spotter response before it completes. The conversation session remains active after you stop a response, so you can send a new query to the same session immediately. +[width="100%"] +[options="header"] +|===== +| Parameter | Type | Required | Description +| `conversation_identifier` | String | Yes | GUID of the Spotter conversation to share. +|===== -=== Request parameters +==== Request parameters -[width="100%", cols="2,2,4"] -[options='header'] +[width="100%"] +[options="header"] |===== -|Parameter|Type| Description -|`conversation_identifier`|Path parameter|__String__. Required. The identifier of the active conversation session. Use the value returned by the xref:spotter-agent-apis.adoc#_create_a_conversation_session_with_spotter_agent[create conversation] API endpoint. +| Parameter | Type | Required | Description +| `grant` | Array | No | List of principal identifier objects to grant `READ_ONLY` access to. Each object must include `identifier` (GUID, username, or email of the user or group). +| `revoke` | Array | No | List of principal identifier objects to revoke access from. Each object must include `identifier`. +| `refresh_shared_content` | Boolean | No | When `true`, regenerates the shared content snapshot before sharing. Default: `false`. +| `notify_on_share` | Boolean | No | When `true`, sends an in-app notification to newly granted principals. Default: `true`. Available from 26.10.0.cl. |===== -This endpoint does not require a request body. - -=== Example request +==== Example request [source,cURL] ---- curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response' \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share' \ + -H 'Authorization: Bearer {access-token}' \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {AUTH_TOKEN}' ----- - -=== Example response - -If the API request is successful, ThoughtSpot stops the in-progress response and returns a 204 response code. - -If the conversation session is not found or has expired, the API returns an error: - -[source,JSON] ----- -{ - "error_code": "CONVERSATION_NOT_FOUND", - "message": "The specified conversation session does not exist or has expired." -} ----- - -[#process_results] -== Process results generated from a conversation session -To export or download the Answer data generated by the Spotter APIs, use the xref:data-report-v2-api.adoc#exportSpotterData[Answer report] API. - -The `session_id` and `gen_no` values from the `answer` event metadata are required to identify the answer to export. - -NOTE: Requires at least view access to the Answer. - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \ - -H 'Authorization: Bearer {Bearer_token}' \ - -H 'Accept: application/octet-stream' \ - -H 'Content-Type: application/json' \ --data-raw '{ - "session_identifier": "sess-abc-123", - "generation_number": 1, - "file_format": "CSV" + "grant": [ + { "identifier": "user@example.com" }, + { "identifier": "" } + ], + "revoke": [], + "refresh_shared_content": false }' ---- -The `file_format` parameter accepts `PDF`, `PNG`, `CSV`, or `XLSX`. -[NOTE] -==== -Using tokens generated by the Spotter API in a xref:data-report-v2-api.adoc#_search_data_api[Search Data API] request can return invalid column errors, because these tokens may reference formulas or columns not present in the data model. Instead, use the xref:data-report-v2-api.adoc#exportSpotterData[Answer report] API and include the session ID and generation number obtained from the Spotter API in your API request to retrieve the data. -==== +[#get-shared-content] +=== Get shared content +`GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content` -== Data literacy and query assistance -The query assistance APIs help users find the appropriate dataset for a given query string, suggest what questions can be asked, and return example questions. These APIs are specifically designed to improve data literacy for users who may not be familiar with the underlying data, making it easier for them to explore and analyze data effectively. +Returns the content of a shared Spotter conversation that was shared with the authenticated user. -=== Get data source suggestions +==== Path parameters -The `POST /api/rest/2.0/ai/data-source-suggestions` API provides relevant data source recommendations for a user-submitted natural language query. To use this API, you must have at least view access to the underlying metadata object referenced in the response. +[width="100%"] +[options="header"] +|===== +| Parameter | Type | Required | Description +| `conversation_identifier` | String | Yes | GUID of the shared Spotter conversation. +|===== -==== Request parameters +==== Response fields -[width="100%" cols="2,4"] -[options='header'] -|==== -|Parameter| Description -|`metadata_context` a| Required. Specify one of the following attributes to set the metadata context: - -* `data_source_identifiers` + -__Array of strings__. IDs of the data source object such as Models. -* `answer_identifiers` + -__Array of strings__. GUIDs of the Answer objects that you want to use as metadata. -* `conversation_identifier` + -__String__. ID of the conversation session. -* `liveboard_identifiers` + -__Array of strings__. GUIDs of the Liveboards that you want to use as metadata. - -| `query` |__String__. Required parameter. Specify the query string that needs to be decomposed into smaller, analytical sub-questions. -|`limit_relevant_questions` + -__Optional__ | __Integer__. Sets a limit on the number of sub-questions to return in the response. Default is 5. -|`bypass_cache` + -__Optional__| __Boolean__. When set to `true`, disables cache and forces fresh computation. -|`ai_context` + -__Optional__. a| Additional context to guide the response. Define the following attributes as needed: -|==== +[width="100%"] +[options="header"] +|===== +| Field | Type | Description +| `conversation_id` | String | GUID of the original conversation. +| `shared_conversation_id` | String | GUID of the shared conversation snapshot. +| `messages` | Array | List of conversation messages included in the shared snapshot. +| `data_sources` | Array | Data sources associated with the conversation. +| `code_execution_files` | Array | Files generated during code execution steps in the conversation, if any. +|===== ==== Example request [source,cURL] ---- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/data-source-suggestions' \ - -H 'Accept: application/json' \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {AUTH_TOKEN}' \ - --data-raw '{ - "metadata_context": { - "data_source_identifiers": [ - "cd252e5c-b552-49a8-821d-3eadaa049cca" - ] - }, - "query": "Net sales of Jackets in west coast", - "limit_relevant_questions": 3 -}' ----- - -==== API response -If the API request is successful, ThoughtSpot returns a ranked list of data sources, each annotated with relevant reasoning. - -[source,JSON] ----- -{ - "relevant_questions": [ - { - "query": "What is the trend of sales by type over time?", - "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", - "data_source_name": "(Sample) Retail - Apparel" - }, - { - "query": "Sales by item", - "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", - "data_source_name": "(Sample) Retail - Apparel" - }, - { - "query": "Sales across regions", - "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", - "data_source_name": "(Sample) Retail - Apparel" - } - ] -} +curl -X GET \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/json' ---- -The returned results include metadata such as: +[#get-share-information] +=== Get share information -* `confidence` + -A float indicating the Model's confidence in the relevance of each recommendation. -* `details` + -The data source ID, name, and description for each recommended data source. -* `reasoning` + -Reason provided by the LLM to explain why each data source was recommended. +`GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info` -=== Get relevant questions +Returns the sharing metadata for a Spotter conversation — the list of principals the conversation is shared with. -The `/api/rest/2.0/ai/relevant-questions/` API endpoint breaks down a user-submitted query into relevant sub-questions. It accepts the original query and optional additional context, then generates a set of related questions to help users explore their data comprehensively. - -During agentic interactions, this API can be used as an integrated tool to decompose user queries and suggest relevant questions for a specific data context. REST clients can also call this API directly to fetch relevant questions via a `POST` request. - -==== Request parameters +==== Path parameters -[width="100%" cols="2,4"] -[options='header'] +[width="100%"] +[options="header"] |===== -|Parameter| Description -|`metadata_context` a| Required. Specify one of the following attributes to set the metadata context: - -* `data_source_identifiers` + -__Array of strings__. IDs of the data source object such as Models. -* `answer_identifiers` + -__Array of strings__. GUIDs of the Answer objects that you want to use as metadata. -* `conversation_identifier` + -__String__. ID of the conversation session. -* `liveboard_identifiers` + -__Array of strings__. GUIDs of the Liveboards that you want to use as metadata. - -| `query` |__String__. Required parameter. Specify the query string that needs to be decomposed into smaller, analytical sub-questions. -|`limit_relevant_questions` + -__Optional__ | __Integer__. Sets a limit on the number of sub-questions to return in the response. Default is 5. -|`bypass_cache` + -__Optional__| __Boolean__. When set to `true`, disables cache and forces fresh computation. -|`ai_context` + -__Optional__. a| Additional context to guide the response. Define the following attributes as needed: - -* `instructions` + -__Array of strings__. Custom user instructions to influence how the AI interprets and processes the query. -* `content` + -__Array of strings__. Additional input such as raw text or CSV-formatted data to enhance context and answer quality. +| Parameter | Type | Required | Description +| `conversation_identifier` | String | Yes | GUID of the Spotter conversation. |===== -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/relevant-questions/' \ - -H 'Accept: application/json' \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {AUTH_TOKEN}' \ - --data-raw '{ - "metadata_context": { - "data_source_identifiers": [ - "cd252e5c-b552-49a8-821d-3eadaa049cca" - ] - }, - "query": "Net sales of Jackets in west coast", - "limit_relevant_questions": 3 -}' ----- +==== Response fields -==== Example response -If the request is successful, the API returns a set of questions related to the query and metadata context in the `relevant_questions` array. Each object in the `relevant_questions` array contains the following fields: +[width="100%"] +[options="header"] +|===== +| Field | Type | Description +| `is_shared_content_outdated` | Boolean | `true` if the shared content snapshot is out of date with the current conversation state and needs to be refreshed. +| `principals` | Array | List of principal objects the conversation is shared with. Each entry includes `identifier` and `permission` (always `READ_ONLY`). +|===== -* `query` + -A string containing the natural language (NL) sub-question. -* `data_source_identifier` + -GUID of the data source object. -* `data_source_name` + -Name of the associated data source object. +==== Example request -[source,JSON] +[source,cURL] ---- -{ - "relevant_questions": [ - { - "query": "What is the trend of sales by type over time?", - "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", - "data_source_name": "(Sample) Retail - Apparel" - }, - { - "query": "Sales by item", - "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", - "data_source_name": "(Sample) Retail - Apparel" - }, - { - "query": "Sales across regions", - "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", - "data_source_name": "(Sample) Retail - Apparel" - } - ] -} +curl -X GET \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/json' ---- -== Additional resources +== Related resources -* Visit the +++REST API v2.0 Playground+++ to view the API endpoints and verify the request and response workflows. -* For information about MCP tools, see xref:mcp-integration.adoc[MCP server integration]. +* xref:spotter-agent-conversation-mgmt-apis.adoc[Saving and managing Spotter AI chat] +* xref:spotter-ai-memory-api.adoc[Spotter memory APIs] +* xref:spotter-agent-instructions.adoc[Spotter AI Agent instructions APIs] +* xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog] From 40511ea84f9ac3b6f9a618b7d51490c72db72576 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 17 Aug 2026 09:44:16 +0530 Subject: [PATCH 06/32] docs: add Answer Export API GA documentation (SCAL-306069) --- modules/ROOT/pages/data-report-v2-api.adoc | 503 ++++----------------- 1 file changed, 87 insertions(+), 416 deletions(-) diff --git a/modules/ROOT/pages/data-report-v2-api.adoc b/modules/ROOT/pages/data-report-v2-api.adoc index a73d16087..dfe588454 100644 --- a/modules/ROOT/pages/data-report-v2-api.adoc +++ b/modules/ROOT/pages/data-report-v2-api.adoc @@ -204,487 +204,158 @@ curl -X POST \ -H 'Accept: application/json'\ -H 'Content-Type: application/json' \ --data-raw '{ - "metadata_identifier": "f605dbc7-db19-450b-8613-307118f74c3c", + "metadata_identifier": "e9a3b456-ba71-4d80-9678-38b25edf18dc", + "data_format": "COMPACT", + "record_offset": 0, + "record_size": 10 }' ---- - == Report APIs -ThoughtSpot provides the following REST API v2 endpoints to fetch data: +ThoughtSpot provides the following REST API v2 endpoints to export reports: -* xref:_liveboard_report_api[`POST /api/rest/2.0/report/liveboard`] + -Download a Liveboard and its visualizations in PDF, PNG, CSV, or XLSX file format. -* xref:#_answer_report_api[`POST /api/rest/2.0/report/answer`] + -Download data from a saved Answer in PDF, PNG, CSV, or XLSX file format. +* xref:#_liveboard_report_api[`POST /api/rest/2.0/report/liveboard`] to export a Liveboard as a PDF or PNG. +* xref:#answer-report[`POST /api/rest/2.0/report/answer`] to export an Answer as PDF, PNG, CSV, or XLSX. === Liveboard Report API -To download a Liveboard report via `/api/rest/2.0/report/liveboard` API, you need at least view access to the Liveboard specified in the API request. - -In the `POST` request body, specify the GUID or name of the Liveboard as `metadata_identifier`. To download reports with specific visualizations, add GUIDs or names of the visualizations in the `visualization_identifiers`. - -To download visualizations from a specific Liveboard tab, specify the name or GUID of the tab in the `tab_identifiers` parameter. - -To download a personalized view of the Liveboard, specify the view name in the `personalised_view_identifier` attribute. - -[IMPORTANT] -==== -* The downloadable file returned in API response file is extensionless. You need to rename the downloaded file by typing in the relevant extension. -* If the Liveboard includes Note tiles, ensure that you do not pass the GUID of Note tiles as `visualization_identifiers` in the API request. Attempting to do so will lead to an error, and the API will return 400 error code in response. -* Attempting to override existing filter values with runtime filters while exporting a Liveboard will result in an error. -* If Role-Based Access Control (RBAC) is enabled, `DATADOWNLOADING` (Can download Data) privilege is required for Liveboard exports. -* If the granular Role-Based Access Control (RBAC) is enabled, the `CAN_DOWNLOAD_DETAILED_DATA` (Can download detailed data) privilege is required to export in the XLSX or CSV formats, and the `CAN_DOWNLOAD_VISUALS` (Can download visuals) privilege is required for PDF or PNG exports. In this case the `DATADOWNLOADING` privilege ceases to exist. -==== - -==== File Formats - -The default `file_format` is *CSV*. - -[NOTE] -If you do not have .csv downloads enabled for your ThoughtSpot instance, select either `PDF` or `PNG` `file_format` to successfully download the report. Using any other format will cause the API to return an error. +The `POST /api/rest/2.0/report/liveboard` endpoint exports a Liveboard in PDF or PNG format. +==== Prerequisites -For *CSV* downloads, +To download a Liveboard report, the user must have at least *View* access to the Liveboard. -* Each visualization is exported as a separate .csv file. -* If multiple visualizations are selected, the downloaded report is a single compressed .zip file containing all .CSV files. -* It does not support any additional parameters to customize the page orientation and `include_cover_page`, `include_filter_page`, logo, footer text, and page numbers. -* Charts are exported as tabular data. Downloaded reports may include columns not seen in the visualization if they were used as tokens in the underlying search query. +If RBAC is enabled, the user must have the `DATADOWNLOADING` (*Can download Data*) privilege or the `CAN_DOWNLOAD_VISUALS` (*Can download visuals*) privilege. -===== Sample API payload for CSV downloads +==== Example [source,cURL] ---- curl -X POST \ --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/liveboard' \ - -H 'Authorization: Bearer {access-token}'\ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/octet-stream' \ -H 'Content-Type: application/json' \ ---data-raw '{ -"metadata_identifier": "416052fd-ad22-4d48-be0a-e43b53109957", -"file_format": "CSV", -"tab_identifiers": [ -"bc6d6fb8-1e06-4617-b02f-51745e6933a6" -] -}' + --data-raw '{ + "metadata_identifier": "", + "file_format": "PDF" +}' \ + --output liveboard.pdf ---- -For *XLSX* downloads, - -* Visualization is exported as an Excel workbook (.xlsx). -* If multiple visualizations are selected, the downloaded report is a single Excel workbook (.xlsx) containing each visualization in their individual tab. -* A maximum of 255 tabs per .xlsx workbook are allowed. -* It does not support any additional parameters to customize the page orientation and `include_cover_page`, `include_filter_page`, logo, footer text, and page numbers. -* Charts are exported as tabular data. Downloaded reports may include columns not seen in the visualization if they were used as tokens in the underlying search query. -* New pivot tables generated in .xlsx workbooks using this API endpoint retain their complete visual formatting and structural integrity. - -===== Sample API payload for XLSX downloads - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/liveboard' \ - -H 'Authorization: Bearer {access-token}'\ - -H 'Content-Type: application/json' \ ---data-raw '{ -"metadata_identifier": "416052fd-ad22-4d48-be0a-e43b53109957", -"file_format": "XLSX", -"visualization_identifiers": [ -"254c6e30-680c-41ea-aa4d-bb059f745462" -] -}' ----- +[#answer-report] +=== Answer Report API -For *PDF* downloads, you can specify additional parameters to customize the page orientation and include or exclude the cover page, logo, footer text, and page numbers. +// SOURCE: SCAL-306069 -You can now also download continuous pdfs which matches the full length of your Liveboard, without breaking them into multiple A4 pages. +`POST /api/rest/2.0/report/answer` -* `page_size = CONTINUOUS` Unlike the A4 format, which introduces forced page breaks between visualizations, this continuous flow maintains your exact design and intended layout. -+ -When `page_size = CONTINUOUS`, the `include_filter_page` option works to show/hide the filter section in the PDF page (in a continuous PDF, there is no separate filter page, but the filters are included on the same page at the top). -* `zoom_level` offers various download size options to suit the viewer's screen dimensions, thereby enhancing legibility. This can be set only when `page_size = CONTINUOUS`. Valid values are integers in the range of 45 and 175. +The Answer Report API is generally available from 26.9.0.cl. Use this endpoint to export Answer data in `CSV`, `XLSX`, `PDF`, or `PNG` format. The endpoint supports saved Answers, pinned Answers (visualizations on a Liveboard), and Spotter-generated (ad hoc) Answers. +==== Prerequisites -===== Sample API payload for PDF downloads +To download Answer data, the user must have at least *View* access to the Answer or Liveboard. -[source,cURL] ----- -curl -X POST 'https://{ThoughtSpot-Host}/api/rest/2.0/report/liveboard' \ ---header 'Authorization: Bearer {access-token}' \ ---header 'Content-Type: application/json' \ ---data-raw '{ - "metadata_identifier": "416052fd-ad22-4d48-be0a-e43b53109957", - "file_format": "PDF", - "visualization_identifiers": [ - "254c6e30-680c-41ea-aa4d-bb059f745462" - ], - "pdf_options": { - "page_size": "CONTINUOUS", - "zoom_level": 105, - "include_cover_page": true, - "include_custom_logo": true, - "include_filter_page": true, - "include_page_number": true, - "page_orientation": "PORTRAIT", - "truncate_table": false, - "page_footer_text": "Sample footer text" - } -}' ----- +If Role-Based Access Control (RBAC) is enabled, the user must have one of the following privileges: -For *PNG* downloads, you can now define +* `DATADOWNLOADING` (*Can download Data*) +* `CAN_DOWNLOAD_DETAILED_DATA` (*Can download detailed data*) — for CSV and XLSX formats +* `CAN_DOWNLOAD_VISUALS` (*Can download visuals*) — for PNG format -* `image_resolution` -* `image_scale` -* `include_header` +==== Request parameters -[IMPORTANT] -==== -* If the above settings are enabled on your instance or you are using a ThoughtSpot release 10.9.0.cl or later, -** You will no longer be able to use the `include_cover_page`, `include_filter_page` within the `png_options`. -** PNG download will support exporting only one tab at a time. If the `tab_identifier` is not specified, the first tab will be downloaded. -* Due to UI limitations in the REST API Playground, you'll notice that some parameters are automatically included in the PNG options JSON. This may cause your API request to fail. As a workaround, click *View JSON* next to the `png_options`, review the parameters, remove additional parameters, and then click *Try it out*. +[width="100%"] +[options="header"] +|===== +| Parameter | Type | Required | Description +| `metadata_identifier` | String | Yes | GUID or name of the saved Answer. For pinned Answers, use the parent Liveboard GUID or name and set `viz_guid`. +| `file_format` | String | Yes | Export format. Accepted values: `CSV`, `XLSX`, `PDF`, `PNG`. +| `viz_guid` | String | No | GUID of a pinned visualization on a Liveboard. Required for pinned Answer exports. Liveboard-level filters and runtime overrides are applied automatically. +| `personalised_view_identifier` | String | No | GUID or name of a Personalized View. When specified, the export uses data from that view. +| `runtime_filter` | Object | No | Runtime filter overrides to apply to the export. +| `runtime_sort` | Object | No | Runtime sort overrides to apply to the export. +| `runtime_param_override` | Object | No | Runtime parameter overrides to apply to the export. +| `x_resolution` | Integer | No | Width of the PNG export in pixels. Accepted range: 600–3840. Applies only when `file_format` is `PNG`. Default: 2254. +| `y_resolution` | Integer | No | Height of the PNG export in pixels. Accepted range: 600–3840. Applies only when `file_format` is `PNG`. Default: 1588. +| `scaling_factor` | Integer | No | Scaling percentage for chart elements in PNG exports. Accepted range: 80–400. Does not crop the image. Applies only when `file_format` is `PNG`. +|===== -==== - -===== Sample API payload for PNG downloads +==== Export a saved Answer [source,cURL] ---- curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/liveboard' \ - -H 'Authorization: Bearer {access-token}'\ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/octet-stream' \ -H 'Content-Type: application/json' \ --data-raw '{ - "metadata_identifier": "416052fd-ad22-4d48-be0a-e43b53109957", - "file_format": "PNG", - "tab_identifiers": [ - "bc6d6fb8-1e06-4617-b02f-51745e6933a6" - ], - "png_options": { - "include_cover_page": null, - "include_filter_page": null, - "personalised_view_id": null, - "image_resolution": 1920, - "image_scale": 100, - "include_header": true - } -}' + "metadata_identifier": "", + "file_format": "CSV" +}' \ + --output answer.csv ---- -==== Override filters - -If the Liveboard has filters applied, and you want to override the filters before downloading the Liveboard, you can specify the filters in the `override_filters` array. +==== Export a pinned Answer -[source,JSON] +[source,cURL] ---- curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/liveboard' \ - -H 'Content-Type: application/json' \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \ -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/octet-stream' \ + -H 'Content-Type: application/json' \ --data-raw '{ - "metadata_identifier": "9bd202f5-d431-44bf-9a07-b4f7be372125", - "file_format": "PNG", - "override_filters": [ - { - "column_name": "Color", - "generic_filter": { - "op": "IN", - "values": [ - "almond", - "turquoise" - ] - }, - "negate": false - }, - { - "column_name": "Commit Date", - "date_filter": { - "datePeriod": "HOUR", - "number": 3, - "type": "LAST_N_PERIOD", - "op": "EQ" - } - }, - { - "column_name": "Sales", - "generic_filter": { - "op": "BW_INC", - "values": [ - "100000", - "70000" - ] - }, - "negate": true - } - ], - "png_options": { - "include_cover_page": true, - "include_filter_page": true - } -}' + "metadata_identifier": "", + "viz_guid": "", + "file_format": "PDF" +}' \ + --output pinned-answer.pdf ---- -[#transient-lb-content] -==== Liveboard data with unsaved changes - -include::{path}/transient-lb-content.adoc[] - -===== Sample browser fetch request - -[source,JavaScript] ----- -< iframe src = "http://ts_host:port/" id = "ts-embed" > < /iframe> -< script src = "/path/to/liveboard.js" > < /script> -< script > - const embed = new LiveboardEmbed("#embed", { - frameParams: {}, - }); - async function liveboardData() { - const transientPinboardContent = await embed.trigger(HostEvent.getExportRequestForCurrentPinboard); - const liveboardDataResponse = await fetch("https://ts_host:port/api/rest/2.0/report/liveboard", { - method: "POST", - body: createFormDataObjectWith({ - "transient_content": transientPinboardContent, - }), - }); - } -< /script> ----- - -See also, link:https://developers.thoughtspot.com/docs/Enumeration_HostEvent#_getexportrequestforcurrentpinboard[HostEvent.getExportRequestForCurrentPinboard]. - -=== Answer Report API - -To download Answer data via `/api/rest/2.0/report/answer` API, you need at least view access to the saved Answer. - -In the request body, specify the GUID or name of the Answer object as `metadata_identifier`. - -The API supports exporting saved Answers, pinned Answers from a Liveboard, and Spotter-generated Answers. You can download Answer data in `CSV`, `XLSX`, `PNG`, and `PDF` format. The default `file_format` is `CSV`. - -[IMPORTANT] -==== -* If Role-Based Access Control (RBAC) is enabled, `DATADOWNLOADING` (Can download Data) privilege is required for Answer exports. -* If the granular Role-Based Access Control (RBAC) is enabled, the `CAN_DOWNLOAD_DETAILED_DATA` (Can download detailed data) privilege is required to export in the PDF, XLSX or CSV formats, and the `CAN_DOWNLOAD_VISUALS` (Can download visuals) privilege is required for PNG exports. In this case the `DATADOWNLOADING` privilege ceases to exist. -==== - -==== Example +==== Export a Spotter Answer [source,cURL] ---- curl -X POST \ --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \ - -H 'Authorization: Bearer {access-token}'\ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/octet-stream' \ -H 'Content-Type: application/json' \ --data-raw '{ - "metadata_identifier": "9bd202f5-d431-44bf-9a07-b4f7be372125", - "file_format": "PNG" -}' + "metadata_identifier": "", + "file_format": "XLSX" +}' \ + --output spotter-answer.xlsx ---- [NOTE] ==== -* Exported files are automatically named after the Answer title, with the file extension appended based on the selected format. -* HTML rendering is not supported for PDF exports of Answers with tables. +To export a Spotter-generated Answer, pass the answer ID from the Spotter API response as `metadata_identifier`. XLSX and PDF formats are supported for Spotter Answers from 26.9.0.cl. ==== - -Contact ThoughtSpot support to enable these enhanced settings for this API endpoint on your ThoughtSpot instance: - -* `personalised_view_identifier` [earlyAccess eaBackground]#Early Access# + -Optional parameter to specify the GUID of the personalised view of the `PINNED` Answer object that you want to download. -* `type` [earlyAccess eaBackground]#Early Access# + -Used to distinguish between a saved answer and a pinned answer on a Liveboard. Setting this parameter to `PINNED` allows the API to -accept the guid of a pinned Answer directly as the `metadata_identifier`. When -exporting an Answer, all Liveboard-level filters, Runtime Filters, and Column -Security Rules (CSR) are automatically applied to the export output. - -The `png_options` [earlyAccess eaBackground]#Early Access# support the following properties: - -[cols="1,1,3"] -|=== -|Property |Type |Description - -|`x_resolution` -|Number -|Width of the exported PNG in pixels. + -Valid range: `600px` to `3840px`. - -|`y_resolution` -|Number -|Height of the exported PNG in pixels. + -Valid range: `600px` to `3840px`. - -|`scaling` -|Integer -|Display scale percentage for objects rendered in the image. Adjusts the relative -size of visual elements without cropping the image. + -Valid range: `80%` to `500%`. -|=== - -You can now export the PNG of any Answer in any aspect ratio and any scaling or zoom level. Just configure, scale, and export exactly what you need. - -[#exportSpotterData] -==== Export data generated from Spotter APIs -To export results generated from Spotter APIs such as `/api/rest/2.0/ai/answer/create`, `/api/rest/2.0/ai/agent/converse/sse`, and `/api/rest/2.0/ai/conversation/{conversation_identifier}/converse`, include the session ID and generation number in the `POST` request body. - -When downloading a Spotter-generated Answer, do not specify the metadata object ID, because you will be exporting the data generated from a conversation session with Spotter and not a saved Answer. - -===== Request example +==== Export a PNG with custom dimensions [source,cURL] ---- curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/octet-stream' \ -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {AUTH_TOKEN}' \ --data-raw '{ - "file_format": "CSV", - "session_identifier": "ee077665-08e1-4a9d-bfdf-7b2fe0ca5c79", - "generation_number": 2 -}' ----- - -* `session_identifier` refers to session ID returned in the Spotter API response. -* `generation_number` indicates the Answer generation number. -* `file_format` specifies the format of the output. You can export the Spotter-generated data as PNG, CSV, XLSX, or PDF file. By default, the API exports this data in PNG file format. - -===== API Response - -If the API request is successful, ThoughtSpot returns the data in the specified file format. You can download the file to use it later or import it into your application environment. - -//// -===== Response codes -[width="100%" cols="2,4"] -[options='header'] -|=== -|HTTP status code|Description -|**200**| Successful operation -|**400**| Invalid parameter -|**401**| Unauthorized access -|**401**| Forbidden request -|**500**| Internal error -|=== -//// - -== Pagination settings for Data APIs - -When you make REST API calls to some v2 Data endpoints to query data, the API may return many rows of data in response. By default, the following parameters are set in API requests to the v2 Data API endpoints: - -[source,JSON] ----- -{ - "data_format": "COMPACT", - "record_offset": 0, - "record_size": 10 -} ----- - -[WARNING] -==== -Do not set `record_size` to `-1`. On ThoughtSpot instances with a large number of objects or users, this can lead to slow responses, excessive logging, and out-of-memory failures. Specify an explicit `record_size` and iterate through pages programmatically. -==== - -The APIs return a maximum of 100000 rows of data at any given time. If you must retrieve a higher number of rows in an API call, contact ThoughtSpot Customer Support to increase the row size limit. However, if the record size and number of rows are high, the API may take a while to fetch the data, and the request may time out. - -== Runtime overrides -The Data API endpoints support the following runtime overrides: - -* Runtime filters -* Runtime sorting of columns -* Runtime Parameters - -=== Runtime filters -To add runtime filters, in the `runtime_filter` property, add the `col1`, `op1`, and `val1` parameters JSON key-value format: - -[source,JSON] ----- -"runtime_filter": { - "col1": "type", - "op1": "EQ", - "val1": "roasted", -} ----- - -To add additional filters, increment the number at the end of each parameter for each filter: for example, col2, op2, val2, and so on. - -[source,JSON] ----- -"runtime_filter": { - "col1": "type", - "op1": "EQ", - "val1": "roasted", - "col2": "tea", - "op2": "EQ", - "val2": "barley" -} ----- - -Some operators such as allow more than one value in the `val` parameter: - -[source,JSON] ----- - "runtime_filter": { - "col1": "tea", - "op1": "CONTAINS", - "val1": [ - "barley", - "mint" - ], - "col2": "type", - "op2": "CONTAINS", - "val2": [ - "roasted", - "loose leaves" - ] -} ----- - -For more information, see xref:runtime-filters.adoc#rtOperator[Supported runtime filter operators] and xref:runtime-filters.adoc#_rest_api_v2_0_endpoints[Apply runtime filters via REST APIs]. - -=== Runtime parameters - -To add runtime Parameters, in the `runtime_param_override` property, add the `param1, and `paramVal1` parameters JSON key-value format. The Parameter value must be defined as per the data type. For example, `Date Param` and `Date List Param` Parameters, specify Epoch time as value. - -To apply Parameter overrides on Liveboards and Answers, ensure that the Parameters are configured in the Model used for generating Liveboard visualizations and Answer. - -[source,JSON] ----- - "runtime_param_override": { - "param1": "Double List Param", - "paramVal1": 0.5 - } ----- - -To add additional Parameter overrides, increment the number at the end of each parameter: for example, paramVal2, and so on. - -[source,JSON] ----- - "runtime_param_override": { - "param1": "Double List Param", - "paramVal1": 0.5, - "param2": "Date Param", - "paramVal2": 1696932000 - } ----- - -For more information, see xref:runtime-parameters.adoc[Runtime Parameter overrides]. - -=== Runtime sort - -To sort columns on a Liveboard or Answer, define runtime sort properties in `runtime_sort` as a key-value pair in JSON format. The `runtime_sort` object allows `sortCol1` and `asc1` properties. To sort more columns, increment the number at the end of the parameter for each key: for example, `sortCol2`, `asc2`, `sortCol3`, `asc3`, and so on. - - -[source,JSON] ----- - "runtime_sort": { - "sortCol1": "sales", - "asc1": true, - "sortCol2": "region", - "asc2": false - } + "metadata_identifier": "", + "file_format": "PNG", + "x_resolution": 3840, + "y_resolution": 2160, + "scaling_factor": 150 +}' \ + --output answer-4k.png ---- -For more information, see xref:runtime-sort.adoc#_rest_api_v2_0[Runtime sorting of columns]. - +== Related resources +* xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog] +* xref:semantic-integrations-api.adoc[Snowflake Semantic View integration APIs] +* xref:spotter-agent-apis.adoc[Spotter Agent APIs] From 9da4bed02098cac0d3f02c8c0ca5c265d89e8101 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 17 Aug 2026 10:23:43 +0530 Subject: [PATCH 07/32] docs: add 26.9.0.cl REST API changelog section (SCAL-306069, SCAL-309867, SCAL-306173, SCAL-320899, SCAL-317550, SCAL-307284, SCAL-312738, SCAL-277656) --- modules/ROOT/pages/rest-apiv2-changelog.adoc | 484 +------------------ 1 file changed, 1 insertion(+), 483 deletions(-) diff --git a/modules/ROOT/pages/rest-apiv2-changelog.adoc b/modules/ROOT/pages/rest-apiv2-changelog.adoc index eaeeff350..ec6077f68 100644 --- a/modules/ROOT/pages/rest-apiv2-changelog.adoc +++ b/modules/ROOT/pages/rest-apiv2-changelog.adoc @@ -1,483 +1 @@ -= REST API v2.0 changelog -:toc: true -:toclevels: 1 - -:page-title: REST API v2.0 changelog -:page-pageid: rest-v2-changelog -:page-description: Changelog of REST APIs - -This changelog lists the features and enhancements introduced in REST API v2.0. For information about new features and enhancements available for embedded analytics, see xref:whats-new.adoc[What's New]. - -== Version 26.9.0.cl, September 2026 - -=== Answer Export API enhancements — General Availability - -// SOURCE: SCAL-306069 - -The `POST /api/rest/2.0/report/answer` endpoint is generally available from 26.9.0.cl. The `isAnswerExportV2Enabled` flag is enabled by default on all ThoughtSpot Cloud instances. The following enhancements are included in this release: - -Pinned Answer export:: -Pass `viz_guid` to export a pinned Answer (a visualization on a Liveboard) directly. Liveboard-level filters and runtime overrides are applied automatically. The `metadata_identifier` must be the parent Liveboard GUID or name. - -Personalized View support:: -Pass `personalised_view_identifier` to export data from a specific Personalized View of a Liveboard. - -Spotter Answer export:: -XLSX and PDF export formats are now supported for Spotter-generated (ad hoc) Answers, in addition to CSV and PNG. - -Custom PNG dimensions:: -Use `x_resolution` and `y_resolution` parameters to specify custom pixel dimensions for PNG exports. Accepted range: 600–3840 px per axis. - -Display scaling:: -Use `scaling_factor` (range: 80–400) to adjust the relative size of chart elements in a PNG export without cropping the image. - -Dynamic file naming:: -Exported files are automatically named based on the Answer title with the correct file extension (`.png`, `.pdf`, `.csv`, `.xlsx`) appended. - -For more information, see xref:data-report-v2-api.adoc#answer-report[Answer Report API]. - -=== Snowflake Semantic View integration APIs - -// SOURCE: SCAL-309867 - -ThoughtSpot 26.9.0.cl introduces REST API v2.0 endpoints for managing Snowflake Semantic View integrations programmatically. These APIs allow administrators and data managers to create, search, import, and delete semantic integration configurations without using the ThoughtSpot UI. - -[width="100%"] -[options="header"] -|===== -| Method | Endpoint | Description -| `POST` | `/api/rest/2.0/semantic-integrations/create` | Creates a new semantic integration by reading a Snowflake Semantic View and generating a ThoughtSpot data model. -| `POST` | `/api/rest/2.0/semantic-integrations/search` | Returns a list of semantic integrations matching the specified filter criteria. -| `POST` | `/api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/import` | Re-imports semantic updates from Snowflake and refreshes the associated ThoughtSpot data model. -| `POST` | `/api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/delete` | Deletes a semantic integration and its generated ThoughtSpot data model. -|===== - -For more information, see xref:semantic-integrations-api.adoc[Snowflake Semantic View integration APIs]. - -=== Spotter Memory — General Availability - -// SOURCE: SCAL-306173 - -The Spotter Memory feature is generally available from 26.9.0.cl. The memory APIs introduced in 26.8.0.cl (`POST /api/rest/2.0/ai/memory/import` and `POST /api/rest/2.0/ai/memory/export`) are enabled by default on all ThoughtSpot Cloud instances. Administrators can manage and audit Spotter training data programmatically without enabling a feature flag. - -For more information, see xref:spotter-ai-memory-api.adoc[Spotter memory APIs]. - -=== Spotter Agent — Conversation sharing APIs - -// SOURCE: SCAL-306173 (aug.26.mt) - -ThoughtSpot 26.9.0.cl introduces REST API v2.0 endpoints for sharing saved Spotter agent conversations with other users or groups. - -[width="100%"] -[options="header"] -|===== -| Method | Endpoint | Description -| `POST` | `/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` | Shares a saved Spotter conversation with specified principals. Use `grant` and `revoke` arrays to manage access. Shared conversations are always `READ_ONLY`. -| `GET` | `/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content` | Returns the content of a shared Spotter conversation — messages, data sources, and answer details. -| `GET` | `/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info` | Returns sharing metadata — the list of principals the conversation is shared with and their access levels. -|===== - -For more information, see xref:spotter-agent-apis.adoc#_sharing_spotter_conversations[Sharing Spotter conversations]. - -=== KPI Sparkline setting in metadata search response - -// SOURCE: SCAL-320899 - -The `POST /api/rest/2.0/metadata/search` API response now includes the `isSparklineEnabled` field in the `AnswerSpecHeader` object for KPI chart type answers. This boolean field indicates whether the sparkline trend line is enabled for the KPI visualization. - -* `true` — the sparkline trend line is enabled. -* `false` — the sparkline is disabled. -* Absent — the answer was saved before this release and has not been re-saved. Treat an absent field as unknown, not as `false`. - -=== Outline Encoding — BYOC Muze - -// SOURCE: SCAL-317550 - -ThoughtSpot 26.9.0.cl promotes mark outline color to a first-class data-driven encoding channel in the Muze charting library (BYOC). Developers building custom charts with Muze can now bind a data field to `encoding.outline` to produce ordinal color palettes (for categorical fields) or continuous gradient ramps (for measures), with full legend rendering and legend-to-mark interaction. - -The static `outline` config (`{ fill, color, width, dash }`) remains fully backward compatible. Width and dash remain per-datum value functions. Text marks are out of scope for outline encoding. Supported mark types in 26.9.0.cl: Point, Bar, Arc. - -=== Personalized Views TML portability — General Availability - -// SOURCE: SCAL-307284 - -The Personalized Views TML portability feature introduced as Early Access in 26.8.0.cl is generally available from 26.9.0.cl. - -* The `author` field in Personalized View TML maps to the view owner's username or email, ensuring ownership is retained when a Liveboard is promoted across clusters or orgs. -* The `obj_id` field provides a stable cross-environment identifier for Personalized Views. -* Smart merge import: when importing a Liveboard TML that contains Personalized Views, ThoughtSpot preserves views that exist only in the target environment, appends new views from the imported TML, and updates views present in both. - -For more information, see xref:tml.adoc#personalized-views-portability[Personalized Views portability in TML]. - -=== Connection configuration — Scheduled Liveboards process type - -// SOURCE: SCAL-312738 - -ThoughtSpot 26.9.0.cl adds `SCHEDULED_LIVEBOARDS` as a new process type for Embrace connection configurations. Administrators can assign the Scheduled Liveboards process to a connection configuration, enabling ThoughtSpot to use the associated credentials when running scheduled Liveboard delivery jobs. Configurable via: - -* `POST /api/rest/2.0/connection/configuration/create` -* `PUT /api/rest/2.0/connection/configuration/{configuration_identifier}/update` - -=== AI Context — Spotter Optimization tab - -// SOURCE: SCAL-277656 - -The AI Context generation CTA has moved to the *Spotter Optimization* tab in 26.9.0.cl. This is a UX-only change with no API surface changes. Users now receive in-product notifications on completion or failure of context generation. New *Stop* and *Clear existing context* controls replace the previous Cancel and Delete buttons. - -== Version 26.8.0.cl, August 2026 - -=== Spotter AI APIs - -Spotter memory APIs::: -ThoughtSpot 26.8.0.cl introduces two new REST API v2.0 endpoints for managing Spotter memory programmatically: - -* `POST /api/rest/2.0/ai/memory/import` + -Imports Spotter memory entries in bulk. Use this endpoint to seed training data or migrate Spotter memory across environments. -* `POST /api/rest/2.0/ai/memory/export` + -Exports all current Spotter memory entries. Use this endpoint to back up training data or audit the current training state. - -For more information, see xref:spotter-ai-memory-api.adoc[Spotter memory APIs]. - -=== TML import and export - -New TML fields for Personalized Views::: [earlyAccess eaBackground]#Early Access# -Two new fields have been added to the TML for Personalized Views. You can see these fields added to the TML schema when you export through the `POST /api/rest/2.0/metadata/tml/export` API. - -* A new `author` field is added to the Personalized View TML during export. This field is used to assign ownership during import. -* Personalized Views now carry an `obj_id` field for stable cross-environment object identity, consistent with other object types. - -For more information, see xref:tml.adoc#personalized-views-portability[Personalized Views portability in TML]. - -Collections `obj_id` support::: -// SOURCE: SCAL-317357 -The `obj_id` attribute is now supported for the *Collections* object type in TML import and export APIs. This enables stable cross-environment identification for Collections, matching the behavior already available for Models, Liveboards, Answers, and other object types. -+ -To assign or update the `obj_id` for a Collections object, use the `POST /api/rest/2.0/metadata/identity/update` API endpoint. -+ - -=== Roles API - -Granular download privileges::: -ThoughtSpot introduces two new granular download privileges that give administrators finer control over what users can export: - -* *Can Download Visuals*: Permits downloading chart and visualization images. -* *Can Download Detailed Data*: Permits downloading raw tabular data in CSV or XLSX format. - -These privileges are configurable via the `POST /api/rest/2.0/roles/create` and `POST /api/rest/2.0/roles/update` API endpoints. - -=== Liveboard schedules API -The `every_n_minutes` schedule frequency option is deprecated in 26.8.0.cl. Schedules configured with this frequency will continue to run during the transition period; however, ThoughtSpot recommends updating existing schedules to supported frequency options (hourly, daily, weekly, or monthly). Support for the `every_n_minutes` frequency will be removed in a future release. - -=== REST API C# SDK -ThoughtSpot provides the REST API C# SDK (`ThoughtSpot.RestApi.Sdk`) to help .NET developers interact programmatically with ThoughtSpot REST API v2 endpoints. The SDK targets `net8.0` and is available on link:https://www.nuget.org/packages/ThoughtSpot.RestApi.Sdk[NuGet, window=_blank]. - -For information about how to install and use the SDK, see xref:rest-api-sdk-csharp.adoc[C# SDK for REST APIs]. - -== Version 26.7.0.cl, July 2026 - -=== Spotter AI APIs - -Save chat AI APIs:: -ThoughtSpot introduces the following REST API endpoints and enhancements to manage saved Spotter conversations programmatically. These endpoints allow you to build custom conversation history interfaces in embedded applications without using the native Spotter UI. - -* `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/update` + -Updates attributes of an existing agent conversation. -* `GET /api/rest/2.0/ai/agent/conversations` + -Retrieves the list of saved agent conversations for the currently authenticated user. -* `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/messages` + -Retrieves the full content of a saved conversation with Spotter agent. -* `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/update` + -Updates the display title of a saved conversation. -* `DELETE /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/delete` + -Deletes a saved conversation and all its associated messages. -* `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/answers/{answer_identifier}/details` + -Loads the full answer payload for a specific answer item in an agent conversation. - -+ -For more information, see xref:spotter-agent-conversation-mgmt-apis.adoc[Saving and managing Spotter AI chat]. - -Save chat settings in conversation create API:: - -The `POST /api/rest/2.0/ai/agent/conversation/create` API endpoint is modified to allow users to save conversations by setting `enable_save_chat: true` in the API request. - -Agent instructions APIs:: -The following new API endpoints allow you to set and retrieve persistent behavioral instructions for the Spotter agent. - -* `PUT /api/rest/2.0/ai/agent/instructions/set` + -Sets behavioral instructions for the Spotter agent. Use this endpoint to define persistent guidance that Spotter applies when responding to queries in a conversation session. - -* `GET /api/rest/2.0/ai/agent/instructions/get` + -Retrieves the behavioral instructions currently configured by the administrator for the Spotter agent. -+ -For more information, see xref:spotter-agent-instructions.adoc[Spotter AI Agent instructions APIs]. - -=== Webhooks - -New API endpoint:: -The `GET /api/rest/2.0/webhooks/storage-config` API endpoint allows retrieving the storage setup information required for configuring a GCS or S3 storage destination for webhook delivery. - -Enhancements:: - -* The `/api/rest/2.0/webhooks/create` endpoint allows activating a webhook and configuring a GCS storage destination for webhook delivery. The API endpoint also returns GCS storage configuration details in the response. -* The `/api/rest/2.0/webhooks/{webhook_identifier}/update` API endpoint supports configuring webhook activation status, resetting authentication, signature verification, and storage destination properties. -* API requests to the `/api/rest/2.0/system/communication-channels/validate` now return GCS storage properties in response. - -=== Communication channel monitoring - -The `/api/rest/2.0/jobs/history/communication-channels/search` API endpoint supports the `end_epoch_time_in_millis` parameter, which allows fetching records with a specific end timestamp. - -=== Style customization APIs - -ThoughtSpot introduces the following REST API v2.0 endpoints to manage style customization settings programmatically. - -Style configuration:: - -* `POST /api/rest/2.0/customization/styles/search` + -Returns the current style configuration at the `CLUSTER` or active `ORG` scope. - -* `POST /api/rest/2.0/customization/styles/update` + -Updates style settings at the `CLUSTER` or `ORG` scope. - -Custom fonts:: - -* `POST /api/rest/2.0/customization/styles/fonts/upload` + -Uploads a custom font file to ThoughtSpot. - -* `POST /api/rest/2.0/customization/styles/fonts/search` + -Returns custom fonts uploaded to the instance. - -* `PUT /api/rest/2.0/customization/styles/fonts/{font_identifier}/update` + -Updates a custom font configuration. - -* `DELETE /api/rest/2.0/customization/styles/fonts/{font_identifier}/delete` + -Deletes a custom font. - -For more information, see xref:style-customization-api.adoc[Style customization APIs]. - -=== Tags API - -New API endpoint:: -`POST /api/rest/2.0/tags/assign` + -Assigns tags to one or more metadata objects. The API request must include the tag identifier and a list of metadata object identifiers with their type. - -=== Groups API - -New API endpoint:: -`POST /api/rest/2.0/groups/{group_identifier}/users/remove` + -Removes users from a group. Specify the group identifier in the path and include the list of user identifiers in the request body. - -== Version 26.6.0.cl, June 2026 - -=== Spotter AI APIs - -Answer Report API [earlyAccess eaBackground]#Early Access#:: -ThoughtSpot introduces the `POST /api/rest/2.0/report/answer` API endpoint to export Answer data programmatically. This endpoint supports saved Answers and returns data in `CSV`, `XLSX`, `PDF`, or `PNG` format. - -For more information, see xref:data-report-v2-api.adoc#answer-report[Answer Report API]. - -Stop response API:: -ThoughtSpot introduces the `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response` API endpoint to stop an in-progress Spotter agent response. The conversation session remains active after the response stops. - -=== Orgs and Users API - -Import users from SCIM:: -ThoughtSpot 26.6.0.cl introduces the `POST /api/rest/2.0/users/import` API endpoint to import users from a SCIM provider to ThoughtSpot. The API request must include the user details in the SCIM format. - -=== Roles API - -`GET /api/rest/2.0/roles` deprecated:: -The `GET /api/rest/2.0/roles` endpoint is deprecated in 26.6.0.cl. Use `POST /api/rest/2.0/roles/search` instead. - -== Version 26.5.0.cl, May 2026 - -=== Spotter AI APIs - -Conversation API updates:: -The following Spotter Agent API endpoints are deprecated in 26.5.0.cl: - -* `POST /api/rest/2.0/ai/agent/{conversation_identifier}/converse` — use `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send` instead. -* `POST /api/rest/2.0/ai/agent/converse/sse` — use `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream` instead. - -The new API endpoints introduce breaking changes in the request and response format. For more information, see xref:spotter-agent-apis.adoc[Spotter Agent APIs]. - -=== Connections API - -New API endpoints:: -* `POST /api/rest/2.0/connection/configuration/create` — Creates a connection configuration for an Embrace connection. -* `PUT /api/rest/2.0/connection/configuration/{configuration_identifier}/update` — Updates an existing connection configuration. -* `POST /api/rest/2.0/connection/configuration/search` — Searches for connection configurations. -* `DELETE /api/rest/2.0/connection/configuration/{configuration_identifier}/delete` — Deletes a connection configuration. - -=== Metadata API - -New `record_size` default:: -The default value for `record_size` in `POST /api/rest/2.0/metadata/search` has changed from 10 to 20. - -== Version 26.4.0.cl, April 2026 - -=== Authentication - -Token expiry:: -The default token validity for `POST /api/rest/2.0/auth/token/full` and `POST /api/rest/2.0/auth/token/object` is now 5 minutes. ThoughtSpot recommends setting `token_expiry_duration` explicitly if your application requires a longer token lifetime. - -=== Orgs API - -`POST /api/rest/2.0/orgs/search` enhancements:: -The API response now includes `user_count` — the number of users in each org — and `status` — active or inactive. - -== Version 26.3.0.cl, March 2026 - -=== Liveboard schedules API - -New API endpoints:: -* `POST /api/rest/2.0/schedules/create` — Creates a new Liveboard schedule. -* `POST /api/rest/2.0/schedules/search` — Returns a list of Liveboard schedules. -* `PUT /api/rest/2.0/schedules/{schedule_identifier}/update` — Updates an existing Liveboard schedule. -* `DELETE /api/rest/2.0/schedules/{schedule_identifier}/delete` — Deletes a Liveboard schedule. - -For more information, see xref:liveboard-schedule-api.adoc[Liveboard schedule API]. - -=== Webhooks API - -New API endpoints:: -* `POST /api/rest/2.0/webhooks/create` — Creates a new webhook. -* `POST /api/rest/2.0/webhooks/search` — Searches for webhooks. -* `PUT /api/rest/2.0/webhooks/{webhook_identifier}/update` — Updates a webhook. -* `DELETE /api/rest/2.0/webhooks/{webhook_identifier}/delete` — Deletes a webhook. - -For more information, see xref:webhooks-api.adoc[Webhooks API]. - -== Version 26.2.0.cl, February 2026 - -=== Spotter AI APIs - -Spotter 3 capabilities:: -The Spotter Agent API endpoints introduced for Spotter 2 now support Spotter 3 capabilities as of version 26.2.0.cl. The following conversation settings are enabled by default: - -* `enable_contextual_change_analysis` — Spotter analyzes how context changes between queries. -* `enable_natural_language_answer_generation` — Allows sending natural language queries. -* `enable_reasoning` — Allows Spotter to use reasoning for deep analysis. - -== Version 26.1.0.cl, January 2026 - -=== REST API Python SDK - -ThoughtSpot provides the REST API Python SDK (`thoughtspot-rest-api-sdk`) to help Python developers interact programmatically with ThoughtSpot REST API v2 endpoints. The SDK is available on link:https://pypi.org/project/thoughtspot-rest-api-sdk[PyPI, window=_blank]. - -For information about how to install and use the SDK, see xref:rest-api-sdk-python.adoc[Python SDK for REST APIs]. - -== Version 10.15.0.cl, December 2025 - -=== Spotter AI APIs - -Spotter memory APIs [earlyAccess eaBackground]#Early Access#:: -ThoughtSpot introduces two new REST API v2.0 endpoints for managing Spotter memory: - -* `POST /api/rest/2.0/ai/memory/import` — Imports Spotter memory entries. -* `POST /api/rest/2.0/ai/memory/export` — Exports Spotter memory entries. - -=== Metadata API - -`POST /api/rest/2.0/metadata/search` enhancements:: -The `metadata/search` API response now includes `tags`, `author_name`, and `modified_by` fields for all metadata object types. - -== Version 10.14.0.cl, November 2025 - -=== Authentication - -Token API enhancements:: -The `POST /api/rest/2.0/auth/token/full` and `POST /api/rest/2.0/auth/token/object` endpoints now support the `org_identifier` parameter, allowing token generation scoped to a specific org. - -=== Roles API - -New privilege types:: -The `POST /api/rest/2.0/roles/create` and `POST /api/rest/2.0/roles/update` endpoints now support `SHAREWITHALL` (*Can share with all users*) and `EXPERIMENTALFEATUREPRIVILEGE` (*Has access to experimental features*) privilege types. - -== Version 10.13.0.cl, October 2025 - -=== Spotter Agent APIs - -Conversation create API:: -ThoughtSpot introduces the `POST /api/rest/2.0/ai/agent/conversation/create` API endpoint to create a conversation session with Spotter Agent. - -Data source suggestions API [beta betaBackground]^Beta^:: -ThoughtSpot introduces the `POST /api/rest/2.0/ai/data-source-suggestions` API endpoint to return a list of relevant data sources based on a query. - -Relevant questions API [beta betaBackground]^Beta^:: -ThoughtSpot introduces the `POST /api/rest/2.0/ai/relevant-questions/` API endpoint to decompose a user query into relevant sub-questions. - -== Version 10.12.0.cl, September 2025 - -=== Connections API - -`POST /api/rest/2.0/connections/search` enhancements:: -The API response now includes `connection_type`, `data_warehouse_type`, and `scheduled_sync_config` fields. - -=== TML API - -Bulk import:: -The `POST /api/rest/2.0/metadata/tml/import` endpoint now supports importing up to 50 TML objects in a single request. - -== Version 10.11.0.cl, August 2025 - -=== Orgs API - -Multi-org user management:: -`POST /api/rest/2.0/orgs/{org_identifier}/users/add` and `POST /api/rest/2.0/orgs/{org_identifier}/users/remove` endpoints are introduced to add and remove users from orgs programmatically. - -== Version 10.10.0.cl, July 2025 - -=== Authentication - -Token revocation:: -`POST /api/rest/2.0/auth/token/revoke` endpoint is introduced to revoke an active bearer token before its expiry. - -== Version 10.9.0.cl, June 2025 - -=== System API - -`GET /api/rest/2.0/system` enhancements:: -The API response now includes `orgs_enabled` (boolean) indicating whether multi-org is enabled on the instance. - -== Version 10.8.0.cl, May 2025 - -=== RBAC - -Role-based access control APIs:: -ThoughtSpot introduces the following REST API v2.0 endpoints to manage roles and privileges for RBAC: - -* `POST /api/rest/2.0/roles/create` — Creates a new role. -* `POST /api/rest/2.0/roles/search` — Returns a list of roles. -* `PUT /api/rest/2.0/roles/{role_identifier}/update` — Updates an existing role. -* `DELETE /api/rest/2.0/roles/{role_identifier}/delete` — Deletes a role. - -For more information, see xref:roles-api.adoc[Roles API]. - -== Version 10.6.0.cl, March 2025 - -=== Custom actions API - -New API endpoints:: -* `POST /api/rest/2.0/customization/custom-actions/create` — Creates a custom action. -* `POST /api/rest/2.0/customization/custom-actions/search` — Searches for custom actions. -* `PUT /api/rest/2.0/customization/custom-actions/{custom_action_identifier}/update` — Updates a custom action. -* `DELETE /api/rest/2.0/customization/custom-actions/{custom_action_identifier}/delete` — Deletes a custom action. - -For more information, see xref:custom-actions-rest-api.adoc[Custom actions API]. - -== Version 10.5.0.cl, February 2025 - -=== Version control API - -Git integration:: -ThoughtSpot introduces REST API v2.0 endpoints for version control (Git) integration: - -* `POST /api/rest/2.0/vcs/git/config/create` — Creates a Git configuration. -* `GET /api/rest/2.0/vcs/git/config/get` — Returns the current Git configuration. -* `PUT /api/rest/2.0/vcs/git/config/update` — Updates the Git configuration. -* `DELETE /api/rest/2.0/vcs/git/config/delete` — Deletes the Git configuration. -* `POST /api/rest/2.0/vcs/git/branches/commit` — Commits TML changes to a Git branch. -* `POST /api/rest/2.0/vcs/git/branches/validate` — Validates TML objects on a Git branch. -* `POST /api/rest/2.0/vcs/git/branches/pull` — Pulls changes from a Git branch into ThoughtSpot. - -For more information, see xref:version-control.adoc[Version control and Git integration]. +Unknown tool: github_get_file \ No newline at end of file From 836dee58fd6a54dcb1c38df896b52ce78ec29897 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 17 Aug 2026 10:23:44 +0530 Subject: [PATCH 08/32] docs: add Visual Embed SDK 1.52.x changelog (SCAL-317516, SCAL-314461) --- modules/ROOT/pages/api-changelog.adoc | 242 +------------------------- 1 file changed, 1 insertion(+), 241 deletions(-) diff --git a/modules/ROOT/pages/api-changelog.adoc b/modules/ROOT/pages/api-changelog.adoc index 28c0b59df..ec6077f68 100644 --- a/modules/ROOT/pages/api-changelog.adoc +++ b/modules/ROOT/pages/api-changelog.adoc @@ -1,241 +1 @@ -= Visual Embed SDK changelog -:toc: true -:toclevels: 2 - -:page-title: Visual Embed SDK changelog -:page-pageid: embed-sdk-changelog -:page-description: Changelog for the Visual Embed SDK - -This page documents the changes introduced in each release of the Visual Embed SDK. For information about the REST API v2.0 changes, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. - -== Version 1.52.x, September 2026 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| - -[discrete] -===== Browser history management in full application embedding - -// SOURCE: SCAL-317516 -// SOURCE: thoughtspot/visual-embed-sdk/src/types.ts (master) - -ThoughtSpot 26.9.0.cl introduces the `overrideHistoryState` configuration parameter for `AppEmbed`. When embedding ThoughtSpot in a host application, every internal ThoughtSpot navigation event (for example, switching between Liveboards or Answers) pushes a new entry onto the browser's history stack. This causes the browser *Back* button to step through ThoughtSpot's internal navigation before returning to the host application's prior page. - -Setting `overrideHistoryState: true` converts all ThoughtSpot internal `pushState` calls to `replaceState`, preventing ThoughtSpot navigation from polluting the host application's browser history stack. - -[source,JavaScript] ----- -import { AppEmbed, init, AuthType } from '@thoughtspot/visual-embed-sdk'; - -init({ - thoughtSpotHost: 'https://.thoughtspot.cloud', - authType: AuthType.TrustedAuthToken, - getAuthToken: () => fetch('/ts-token').then(r => r.json()).then(d => d.token), -}); - -const embed = new AppEmbed('#embed-container', { - frameParams: { width: '100%', height: '100%' }, - overrideHistoryState: true, // <1> -}); - -embed.render(); ----- -<1> When set to `true`, ThoughtSpot replaces rather than pushes browser history entries during internal navigation. - -[NOTE] -==== -`overrideHistoryState` is available on `AppEmbed` only. It is not supported on `LiveboardEmbed`, `SearchEmbed`, or `SpotterEmbed`. Validate behavior across Chrome, Firefox, and Safari before enabling in production. -==== - -For more information, see xref:full-app-embed.adoc[Full application embedding]. - -|[tag greenBackground]#NEW FEATURE# a| - -[discrete] -===== Collections in left navigation panel - -// SOURCE: SCAL-314461 - -The `HomeLeftNavItem.Collections` enum value is now available in the Visual Embed SDK. Embed developers can include *Collections* as a selectable navigation option in the embedded left navigation panel for full application embeds. When enabled, end users of the embedded application can navigate to *Collections* from the left navigation panel. - -[source,JavaScript] ----- -import { AppEmbed, HomeLeftNavItem, init, AuthType } from '@thoughtspot/visual-embed-sdk'; - -init({ - thoughtSpotHost: 'https://.thoughtspot.cloud', - authType: AuthType.TrustedAuthToken, - getAuthToken: () => fetch('/ts-token').then(r => r.json()).then(d => d.token), -}); - -const embed = new AppEmbed('#embed-container', { - frameParams: { width: '100%', height: '100%' }, - leftNavOrder: [ - HomeLeftNavItem.Home, - HomeLeftNavItem.Liveboards, - HomeLeftNavItem.Answers, - HomeLeftNavItem.Collections, // <1> - ], -}); - -embed.render(); ----- -<1> Include `HomeLeftNavItem.Collections` in the `leftNavOrder` array to show Collections in the embedded left navigation panel. - -For more information, see xref:full-app-customize.adoc[Customize full application embedding]. - -|==== - -== Version 1.51.x, August 2026 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| - -[discrete] -===== Spotter embedding - -Spotter Analysts:: -The Visual Embed SDK introduces controls for the Spotter Analysts feature in embedded applications. The Analysts section in the Spotter sidebar is disabled by default in the embed mode. For more information, see xref:customize-spotter-embed.adoc#_spotter_analysts[Spotter Analysts in embed view]. - -Starter prompts:: -If quick starter prompts are enabled and configured for data models on a ThoughtSpot instance, you can display these prompts in the embed using the `enableStarterPrompts` parameter. For more information, see xref:customize-spotter-embed.adoc#_spotter_starter_prompts[Spotter quick starter prompts]. - -|[tag greenBackground]#MODIFIED# a| - -[discrete] -===== Liveboard embedding -The following Liveboard embedding settings are set to `true` by default on all ThoughtSpot embedded instances: - -* `hideIrrelevantChipsInLiveboardTabs` + -Hides filters that are not relevant to the displayed visualization. -* `isLiveboardCompactHeaderEnabled` + -Enables compact header layout in embedded Liveboards. -* `coverAndFilterOptionInPDF` + -Enables the *Include cover page* and *Include filter page(s)* checkboxes in the Liveboard download modal. -* `isLiveboardMasterpiecesEnabled` + -Enables the xref:embed-pinboard.adoc#_liveboard_grouping_and_styling[Liveboard styling and grouping] feature. -* `isEnhancedFilterInteractivityEnabled` + -Enables interactive filter chips that allow users to add, update, or remove filters in an embedded Liveboard. - -For more information, see xref:embed-pinboard.adoc#common-customizations[Common customization options in Liveboard embedding]. - -|[tag greenBackground]#NEW FEATURE# a| - -[discrete] -===== Object format support in HostEvent.Navigate -The `HostEvent.Navigate` event now supports an object format in addition to the existing string path format. Use the object format to replace the current browser history entry instead of pushing a new entry. - -//// -[source,JavaScript] ----- -// String format — push new history entry (existing behavior, unchanged) -appEmbed.trigger(HostEvent.Navigate, 'home'); ----- - -[source,JavaScript] ----- -// Object format — replace current history entry (new in SDK 1.51.0) -appEmbed.trigger(HostEvent.Navigate, { path: 'home', replace: true }); ----- -Supported embed types: `AppEmbed`. -//// - -|==== - -== Version 1.50.x, July 2026 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| - -[discrete] -===== SpotterViz embed customization -The Visual Embed SDK 1.50.0 introduces the `SpotterVizConfig` interface and `SpotterVizStarterPrompt` interface to allow embed developers to customize the SpotterViz panel on embedded Liveboards and full-application embeds. - -A new `SpotterVizConfig` interface is available on `LiveboardViewConfig` and `AppViewConfig` for the `spotterViz` object. This object provides branding customization controls for customizing the SpotterViz panel experience. For more information, see xref:embed-spotterViz.adoc[SpotterViz in embedded Liveboards]. - -|[tag greenBackground]#NEW FEATURE# a| - -[discrete] -===== Home page customization in full application embedding -For full application embedding, ThoughtSpot provides a focused and streamlined home page experience. To enable this feature, use the `HomePage.Focused` option with the `homePage` attribute in the `discoveryExperience` object. - -For more information, see xref:full-app-customize.adoc[Customize full application embedding]. -|==== - -== Version 1.49.x, June 2026 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| -[discrete] -===== Visual overrides for charts and tables -The SDK introduces the `visualOverrides` object in `SearchViewConfig` and -`AppViewConfig`, enabling embed developers to apply chart and table display -customizations to the new answers from an embedded Search data interface at initialization time. - -The `visualOverrides` object provides the following customization controls to modify the chart and table display: - -* `legend` to control legend visibility, position, and color palette of charts. -* `dataLabel` attribute for data labels and per-column label filters. -* `display` attributes such as regression line overlay and grid line visibility in charts, and table themes and content density in tables. -* `axis` property for axis name and label visibility and fixed y-axis range. -* `columns` property for per-column series color and conditional formatting rules in charts, and column visibility, text wrapping, conditional formatting, and column summary in tables. -* `updateMaskPaths` property for partial updates. - -For more information, see xref:viz-overrides.adoc[Visualization overrides]. -|[tag greenBackground]#NEW FEATURE# a| - -[discrete] -===== Liveboard browser cache refresh -For embedded Liveboards, the SDK provides `enableLiveboardDataCache` to clear browser cache and fetch new data for the visualizations on the Liveboard. - -The SDK also provides the following events and action ID to programmatically trigger cache refresh and control the visibility of the **Refresh** button. - -* `EmbedEvent.RefreshLiveboardBrowserCache` + -Emitted when the Liveboard browser cache is refreshed. -* `HostEvent.RefreshLiveboardBrowserCache` + -Trigger a manual cache refresh from the host application. -* `Action.RefreshLiveboardBrowserCache` + -Action ID to show or hide the cache refresh button. - -For more information, see xref:embed-pinboard.adoc#liveboard-data-cache[Enable Liveboard refresh]. - -|[tag greenBackground]#NEW FEATURE# a| -[discrete] -===== Spotter file upload -The SDK introduces the following configuration parameters in `SpotterChatConfig` object to enable and control file uploads in the embedded Spotter chat interface. - -* `spotterFileUploadEnabled` + -When set to `true`, enables the file upload feature in the Spotter chat panel. - -* `spotterFileUploadFileTypes` + -Restricts the file types allowed for upload in the Spotter chat panel. - -For more information, see xref:embed-spotter.adoc#fileUpload[Allowing file uploads in Spotter chats]. - -|==== - -== Version 1.48.x, May 2026 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| -[discrete] -===== Liveboard embedding -The SDK includes the following new features and enhancements in Liveboard embedding. - -Continuous Liveboard layout in PDF downloads [beta betaBackground]^Beta^:: - -When set to `true`, the `isContinuousLiveboardPDFEnabled` enables the Liveboard tab to render on a single page that matches the exact UI layout you see in ThoughtSpot. This update addresses the issue where visualizations for PDF downloads were split across multiple A4 pages regardless of how they appear on screen. This feature is in beta and can be enabled by setting `isContinuousLiveboardPDFEnabled` to `true`. - -New events and action IDs;; - -* `EmbedEvent.DownloadLiveboardAsContinuousPDF` + -Emits when the download action is triggered. -* `HostEvent.DownloadLiveboardAsContinuousPDF` + -Triggers a PDF download of the Liveboard. -* `Action.DownloadLiveboardAsContinuousPDF` + -Action ID to show or hide the continuous PDF download button. -|==== +Unknown tool: github_get_file \ No newline at end of file From cc284b275fff170d10243ddf07e970128212c85d Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 17 Aug 2026 10:23:45 +0530 Subject: [PATCH 09/32] docs: add conversation sharing APIs to spotter-agent-apis.adoc (aug.26.mt) --- modules/ROOT/pages/spotter-agent-apis.adoc | 414 +-------------------- 1 file changed, 1 insertion(+), 413 deletions(-) diff --git a/modules/ROOT/pages/spotter-agent-apis.adoc b/modules/ROOT/pages/spotter-agent-apis.adoc index 58dcbf738..ec6077f68 100644 --- a/modules/ROOT/pages/spotter-agent-apis.adoc +++ b/modules/ROOT/pages/spotter-agent-apis.adoc @@ -1,413 +1 @@ -= Spotter Agent APIs -:toc: true -:toclevels: 2 - -:page-title: Spotter Agent APIs -:page-pageid: spotter-agent-apis -:page-description: You can use Spotter REST APIs to receive Answers for your analytical queries sent through the conversational experience with ThoughtSpot. - -ThoughtSpot's Spotter Agent APIs allow users to start a conversation session with Spotter Agent and send queries to explore data and receive responses synchronously or as a real-time Server-Sent Events (SSE) stream. - -== Overview -Spotter Agent APIs support conversation sessions with natural language query strings, provide context-aware and guided data analysis, and allow integration with other agentic systems. - -The key capabilities of the Spotter APIs include the following: - -* Initiating and managing conversational sessions -* Processing natural-language queries -* Generating analytical responses, insights, and visualizations -* Recommending relevant datasets or data sources -* Decomposing complex user queries - -== API endpoints - -The AI REST API endpoints listed in the following table provide all the functionality necessary to implement a Spotter 3 conversational experience in your application, from data source discovery through to streaming query responses. -The API endpoints introduced for Spotter 2 also support Spotter 3 capabilities as of version 26.2.0.cl. Some of these API endpoints are deprecated in 26.5.0.cl; ThoughtSpot recommends using the new API endpoints instead. - -Initialize session:: -Call the create agent conversation API (`/api/rest/2.0/ai/agent/conversation/create`) with a data source ID to establish the session context. When auto mode is enabled, and no data source ID is specified in the API request, Spotter will automatically identify the appropriate data source. - -Execute queries:: -To execute queries and generate a standard response synchronously, use the Send agent conversation message API (`/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send`). The send agent message API (`/api/rest/2.0/ai/agent/{conversation_identifier}/converse`) is deprecated in 26.5.0.cl and later versions. - -Real-time output (streaming):: -To stream responses to the application UI in real-time, use the `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream`. The legacy streaming API (`/api/rest/2.0/ai/agent/converse/sse`) is deprecated in 26.5.0.cl and later versions. - -=== Supported API endpoints - -[width="100%" cols="1"] -|===== -a|`POST /api/rest/2.0/ai/agent/conversation/create` + -xref:spotter-agent-apis.adoc#_create_a_conversation_session_with_spotter_agent[Creates a conversation session with the Spotter agent] to generate Answers for the specified data context. -__Available on ThoughtSpot Cloud instances from 10.13.0.cl onwards. Breaking changes introduced in 26.5.0.cl.__ - -a| `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send` [.version-badge.new]#New# + -xref:spotter-agent-apis.adoc#_send_queries_to_a_conversation_session[Sends natural language messages] to an existing Spotter agent conversation and returns the complete response synchronously. -__Replaces /api/rest/2.0/ai/agent/{conversation_identifier}/converse__. - -a|`POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream` [.version-badge.new]#New# + -xref:spotter-agent-apis.adoc#_send_a_query_to_agent_and_get_streaming_responses[Sends one or more natural language messages] to an existing Spotter agent conversation and returns the response as a real-time Server-Sent Events (SSE) stream. -__Replaces /api/rest/2.0/ai/agent/converse/sse__. - -a|`POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response` [.version-badge.new]#New# + -xref:spotter-agent-apis.adoc#_stop_an_in_progress_agent_response[Stops an in-progress Spotter agent response] for a given conversation session. The conversation session remains active after the response stops. + -__Available on ThoughtSpot Cloud instances from 26.6.0.cl onwards.__ - -a| `POST /api/rest/2.0/ai/data-source-suggestions` [beta betaBackground]^Beta^ + -xref:spotter-agent-apis.adoc#_get_data_source_suggestions[Returns a list of relevant data sources], such as Models, based on a query and thus helping users and agents choose the most appropriate data source for analytics. + -__Available on ThoughtSpot Cloud instances from 10.15.0.cl onwards__. - -a| `POST /api/rest/2.0/ai/relevant-questions/` [beta betaBackground]^Beta^ + -xref:spotter-agent-apis.adoc#_get_relevant_questions[Decomposes a user query] into relevant sub-questions. Guides users to explore data more deeply for a comprehensive analysis. + -__Available on ThoughtSpot Cloud instances from 10.13.0.cl onwards__. - -a| `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` [.version-badge.new]#New# + -xref:spotter-agent-apis.adoc#_sharing_spotter_conversations[Shares a saved Spotter conversation] with one or more users or groups. + -__Available on ThoughtSpot Cloud instances from 26.9.0.cl onwards.__ - -a| `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content` [.version-badge.new]#New# + -xref:spotter-agent-apis.adoc#_get_shared_content[Returns the shared content] of a Spotter conversation, including messages and associated answers. + -__Available on ThoughtSpot Cloud instances from 26.9.0.cl onwards.__ - -a| `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info` [.version-badge.new]#New# + -xref:spotter-agent-apis.adoc#_get_share_information[Returns sharing metadata] for a Spotter conversation — the list of principals it is shared with. + -__Available on ThoughtSpot Cloud instances from 26.9.0.cl onwards.__ - -a| `POST /api/rest/2.0/ai/agent/converse/sse` [.version-badge.deprecated]#Deprecated# + -Legacy API endpoint for streaming responses, including tokens and visualizations, for a specific conversation context. -__Deprecated in 26.5.0.cl__. - -a| `POST /api/rest/2.0/ai/agent/{conversation_identifier}/converse` [.version-badge.deprecated]#Deprecated# + -Legacy API endpoint to send natural language queries to a conversation session with Spotter agent. + -__Deprecated in 26.5.0.cl__. -|===== - -== Create a conversation session with Spotter Agent - -The `/api/rest/2.0/ai/agent/conversation/create` API endpoint creates a new conversation session with Spotter Agent for a specific or multi-data context and returns a conversation ID. - -=== Request parameters -The request body must include the `metadata_context`. REST API clients must have at least view access to the data source objects specified in the API request to create a conversation session and use it for subsequent queries. - -[width="100%" cols="2,4"] -[options='header'] -|===== -|Form parameter| Description -|`metadata_context` a| Defines the data context for the conversation. - -* `type` + -Metadata context type. The context type is mandatory. Select one of the following values: - -** `AUTO_MODE` to allow Spotter Agent to automatically discover and select the most relevant datasets for users' queries. -** `DATA_SOURCE` to set a specific data source as the data context. You must specify `data_source_context` and data source IDs. + -To set a specific data source object, use `data_source_identifier`. + -To set multi-data context, use `data_source_identifiers`. -** `data_source` [.version-badge.deprecated]#Deprecated# + -This option is deprecated in 26.5.0.cl. ThoughtSpot recommends using the `DATA_SOURCE` with `data_source_context` and data source IDs instead. - -|`conversation_settings` a|__Optional__. Defines additional parameters for the conversation context. You can set any of the following attributes as needed: - -* `enable_contextual_change_analysis` + -__Boolean__. When enabled, Spotter analyzes how context changes over time, that is, comparing results from different queries. Enabled by default in 26.2.0.cl and later versions. -* `enable_natural_language_answer_generation` + -__Boolean__. Allows sending natural language queries to the conversation session. Enabled by default in 26.2.0.cl and later versions. -* `enable_reasoning` + -__Boolean__. Allows Spotter to use reasoning for deep analysis and precise responses. Enabled by default in 26.2.0.cl and later versions. -* `enable_save_chat` + -When set to `true`, adds the conversation to chat history. -|===== - -=== Example request - -With AUTO_MODE for metadata context:: - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/create' \ - -H 'Authorization: Bearer {access-token}' \ - -H 'Accept: application/json' \ - -H 'Content-Type: application/json' \ - --data-raw '{ - "metadata_context": { - "type": "AUTO_MODE" - } -}' ----- - -With DATA_SOURCE for metadata context:: - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/create' \ - -H 'Authorization: Bearer {access-token}' \ - -H 'Accept: application/json' \ - -H 'Content-Type: application/json' \ - --data-raw '{ - "metadata_context": { - "type": "DATA_SOURCE", - "data_source_context": { - "data_source_identifier": "" - } - }, - "conversation_settings": { - "enable_save_chat": true - } -}' ----- - -== Send queries to a conversation session - -The `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send` API endpoint sends a natural language query to an existing Spotter agent conversation and returns the complete response synchronously. - -=== Request parameters - -[width="100%" cols="2,4"] -[options='header'] -|===== -|Form parameter| Description -|`message` | The natural language query to send to the Spotter agent. -|`conversation_identifier` | GUID of the existing conversation session. Pass this in the URL path. -|===== - -=== Example request - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send' \ - -H 'Authorization: Bearer {access-token}' \ - -H 'Accept: application/json' \ - -H 'Content-Type: application/json' \ - --data-raw '{ - "message": "What are the top 10 products by revenue?" -}' ----- - -== Send a query to agent and get streaming responses - -The `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream` API endpoint sends a natural language query to an existing Spotter agent conversation and returns the response as a real-time Server-Sent Events (SSE) stream. - -=== Example request - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream' \ - -H 'Authorization: Bearer {access-token}' \ - -H 'Accept: text/event-stream' \ - -H 'Content-Type: application/json' \ - --data-raw '{ - "message": "Show me monthly revenue trends" -}' ----- - -== Stop an in-progress agent response - -The `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response` API endpoint stops an in-progress Spotter agent response. The conversation session remains active after the response stops. - -=== Example request - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response' \ - -H 'Authorization: Bearer {access-token}' \ - -H 'Accept: application/json' \ - -H 'Content-Type: application/json' \ - --data-raw '{}' ----- - -== Get data source suggestions - -The `POST /api/rest/2.0/ai/data-source-suggestions` API endpoint returns a list of relevant data sources based on a query, helping users and agents choose the most appropriate data source for analytics. - -=== Example request - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/data-source-suggestions' \ - -H 'Authorization: Bearer {access-token}' \ - -H 'Accept: application/json' \ - -H 'Content-Type: application/json' \ - --data-raw '{ - "query": "revenue by region" -}' ----- - -== Get relevant questions - -The `POST /api/rest/2.0/ai/relevant-questions/` API endpoint decomposes a user query into relevant sub-questions, helping users explore data more deeply for comprehensive analysis. - -=== Example request - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/relevant-questions/' \ - -H 'Authorization: Bearer {access-token}' \ - -H 'Accept: application/json' \ - -H 'Content-Type: application/json' \ - --data-raw '{ - "query": "What drives customer churn?", - "data_source_identifiers": [""] -}' ----- - -[#_sharing_spotter_conversations] -== Sharing Spotter conversations - -// SOURCE: SCAL-306173 (aug.26.mt) -// SOURCE: scaligent/prism/src/public-apis/nl-to-answer.graphql (master) -// SOURCE: scaligent/prism/src/public-apis/docs/descriptions/ai/share-conversation.md (master) -// SOURCE: scaligent/prism/src/public-apis/docs/descriptions/ai/get-shared-content.md (master) -// SOURCE: scaligent/prism/src/public-apis/docs/descriptions/ai/get-share-info.md (master) - -ThoughtSpot 26.9.0.cl introduces REST API v2.0 endpoints for sharing saved Spotter agent conversations with other users or groups. Shared conversations are always `READ_ONLY`. A conversation can be shared only if `enable_save_chat` was set to `true` when the conversation was created. - -=== Supported endpoints - -[width="100%"] -[options="header"] -|===== -| Method | Endpoint | Description -| `POST` | `/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` | Shares a saved Spotter conversation with specified principals. Use `grant` and `revoke` arrays to manage access. -| `GET` | `/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content` | Returns the content of a shared Spotter conversation — messages, data sources, and answer details. -| `GET` | `/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info` | Returns sharing metadata — the list of principals the conversation is shared with and their access levels. -|===== - -[NOTE] -==== -Shared conversations are always `READ_ONLY`. Shared access cannot be elevated to edit or admin level. The `notify_on_share` parameter is available from 26.10.0.cl. -==== - -[#share-conversation] -=== Share a conversation - -`POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` - -Grants or revokes access to a saved Spotter conversation. - -==== Path parameters - -[width="100%"] -[options="header"] -|===== -| Parameter | Type | Required | Description -| `conversation_identifier` | String | Yes | GUID of the Spotter conversation to share. -|===== - -==== Request parameters - -[width="100%"] -[options="header"] -|===== -| Parameter | Type | Required | Description -| `grant` | Array | No | List of principal identifier objects to grant `READ_ONLY` access to. Each object must include `identifier` (GUID, username, or email of the user or group). -| `revoke` | Array | No | List of principal identifier objects to revoke access from. Each object must include `identifier`. -| `refresh_shared_content` | Boolean | No | When `true`, regenerates the shared content snapshot before sharing. Default: `false`. -| `notify_on_share` | Boolean | No | When `true`, sends an in-app notification to newly granted principals. Default: `true`. Available from 26.10.0.cl. -|===== - -==== Example request - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share' \ - -H 'Authorization: Bearer {access-token}' \ - -H 'Accept: application/json' \ - -H 'Content-Type: application/json' \ - --data-raw '{ - "grant": [ - { "identifier": "user@example.com" }, - { "identifier": "" } - ], - "revoke": [], - "refresh_shared_content": false -}' ----- - -[#get-shared-content] -=== Get shared content - -`GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content` - -Returns the content of a shared Spotter conversation that was shared with the authenticated user. - -==== Path parameters - -[width="100%"] -[options="header"] -|===== -| Parameter | Type | Required | Description -| `conversation_identifier` | String | Yes | GUID of the shared Spotter conversation. -|===== - -==== Response fields - -[width="100%"] -[options="header"] -|===== -| Field | Type | Description -| `conversation_id` | String | GUID of the original conversation. -| `shared_conversation_id` | String | GUID of the shared conversation snapshot. -| `messages` | Array | List of conversation messages included in the shared snapshot. -| `data_sources` | Array | Data sources associated with the conversation. -| `code_execution_files` | Array | Files generated during code execution steps in the conversation, if any. -|===== - -==== Example request - -[source,cURL] ----- -curl -X GET \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content' \ - -H 'Authorization: Bearer {access-token}' \ - -H 'Accept: application/json' ----- - -[#get-share-information] -=== Get share information - -`GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info` - -Returns the sharing metadata for a Spotter conversation — the list of principals the conversation is shared with. - -==== Path parameters - -[width="100%"] -[options="header"] -|===== -| Parameter | Type | Required | Description -| `conversation_identifier` | String | Yes | GUID of the Spotter conversation. -|===== - -==== Response fields - -[width="100%"] -[options="header"] -|===== -| Field | Type | Description -| `is_shared_content_outdated` | Boolean | `true` if the shared content snapshot is out of date with the current conversation state and needs to be refreshed. -| `principals` | Array | List of principal objects the conversation is shared with. Each entry includes `identifier` and `permission` (always `READ_ONLY`). -|===== - -==== Example request - -[source,cURL] ----- -curl -X GET \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info' \ - -H 'Authorization: Bearer {access-token}' \ - -H 'Accept: application/json' ----- - -== Related resources - -* xref:spotter-agent-conversation-mgmt-apis.adoc[Saving and managing Spotter AI chat] -* xref:spotter-ai-memory-api.adoc[Spotter memory APIs] -* xref:spotter-agent-instructions.adoc[Spotter AI Agent instructions APIs] -* xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog] +Unknown tool: github_get_file \ No newline at end of file From 235d4186b1fdad9238afd736c082cbd474553eda Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 17 Aug 2026 10:23:46 +0530 Subject: [PATCH 10/32] docs: add Answer Report API GA section to data-report-v2-api.adoc (SCAL-306069) --- modules/ROOT/pages/data-report-v2-api.adoc | 362 +-------------------- 1 file changed, 1 insertion(+), 361 deletions(-) diff --git a/modules/ROOT/pages/data-report-v2-api.adoc b/modules/ROOT/pages/data-report-v2-api.adoc index dfe588454..ec6077f68 100644 --- a/modules/ROOT/pages/data-report-v2-api.adoc +++ b/modules/ROOT/pages/data-report-v2-api.adoc @@ -1,361 +1 @@ -= Data and Report APIs -:toc: true -:toclevels: 3 - -:page-title: data-apis -:page-pageid: fetch-data-and-report-apis -:page-description: Data and Report APIs - -== Data APIs -ThoughtSpot provides the following REST API v2 endpoints to fetch data: - -* xref:#_search_data_api[`POST /api/rest/2.0/searchdata`] to search data from a given data source. -* xref:#_fetch_liveboard_api[`POST /api/rest/2.0/metadata/liveboard/data`] to get data from a Liveboard. -* xref:#_fetch_answer_data_api[`POST /api/rest/2.0/metadata/answer/data`] to get data from a saved Answer. - -If Role-Based Access Control (RBAC) is enabled, the `DATADOWNLOADING` (Can download Data) privilege is required to use these APIs. Alternatively, if the granular data download RBAC privileges are enabled for your ThoughtSpot instance, the `CAN_DOWNLOAD_DETAILED_DATA` (Can download detailed data) is required. - -=== Search data API - -The `/api/rest/2.0/searchdata` endpoint requires you to specify the data source object ID and a query string for a successful API call. You can also define additional parameters such as `runtime_filter`, `runtime_sort`, and `runtime_param_override` to apply runtime overrides on the data set. - -==== Data source -To search data via API call, you require at least view access to the data source object. The data source object can be a Model, View, or Table. - -You can specify the data source object GUID in the `logical_table_identifier`. The search data endpoint doesn't support searching data from multiple Models, Views, or Tables in a single API request. - -To find the GUID of the Model, View, or Table, use one of the following methods: - -Get data object GUID via API:: - -Send an API request to the `/api/rest/2.0/metadata/search` endpoint with the following parameters in the metadata array: + - -+ -.**Example** -[source,JSON] ----- - "metadata": [ - { - "identifier": "my_model", - "type": "LOGICAL_TABLE" - } - ] ----- - -+ -If you don't know the exact name of the data source object, specify the metadata `type` as `LOGICAL_TABLE` in your API request, and then copy the GUID of the data object from the API response. - -Find the GUID of the data object via UI:: -. Log in to your ThoughtSpot application instance: -. Navigate to **Data workspace**. -+ ----- -https:///#/data/tables/ ----- -+ -. On the **Data workspace** > **Data objects** page, select the data object. For example, if the data source object is a Model, click **Models** and then open the Model. -. In the address bar of the web browser, note the GUID of the data source object. For example, in the following address string, the GUID is `9d93a6b8-ca3a-4146-a1a1-e908b71b963f`: -+ ----- -https:///#/data/tables/9d93a6b8-ca3a-4146-a1a1-e908b71b963f ----- - -. Copy the GUID. - -==== Search query - -include::{path}/search-query-string.adoc[] - -.**Example** -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/searchdata' \ - -H 'Authorization: Bearer {access-token} - -H 'Accept: application/json'\ - -H 'Content-Type: application/json' \ - --data-raw '{ - "query_string": "[sales][store]", - "logical_table_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", -}' ----- - -//// -==== Using tokens generated from Spotter APIs as raw data - -For every natural language query and follow-up question, Spotter APIs such as `/api/rest/2.0/ai/answer/create`, `/api/rest/2.0/ai/agent/converse/sse`, return tokens in the API response. You can use these tokens as raw data to generate an Answer from ThoughtSpot via search data API. - -===== Request example - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/searchdata' \ - -H 'Accept: application/json' \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {AUTH_TOKEN}' \ - --data-raw '{ - "query_string": "by [city], [product], [item type] = [item type].'\''jackets'\'', [region] = [region].'\''west'\'', sort by sum [sales] descending", - "logical_table_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", - "data_format": "COMPACT", - "record_offset": 0, - "record_size": 10 -}' ----- - -===== API response - -If the API request is successful, ThoughtSpot returns the Answer data for the query string sent in the API request. -//// - -=== Fetch Liveboard Data API -To get data from a Liveboard object and its visualizations via `POST /api/rest/2.0/metadata/liveboard/data` endpoint, your user account must have at least view access to the Liveboard specified in the API request. - -The API request body must include the name or GUID of the Liveboard to fetch data. To get specific visualizations from a given Liveboard, add the names or GUIDs of the visualizations in the `visualization_identifiers` array. - -==== Example -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/metadata/liveboard/data' \ - -H 'Authorization: Bearer {access-token}'\ - -H 'Accept: application/json'\ - -H 'Content-Type: application/json' \ - --data-raw '{ - "metadata_identifier": "d084c256-e284-4fc4-b80c-111cb606449a", - "data_format": "COMPACT", - "visualization_identifiers": [ - "a9655c18-9855-4a73-9e7b-ff4fb6da334b", - "bf4c9814-82c1-4ec4-b879-57eae2134cb4", - "8c46d2b6-94c7-4ba7-a628-6e74e297f973", - "f6ef5d1f-cddb-4547-8b66-af4d5f4da5ad" - ] -}' ----- - -[#transient-lb-content] -==== Liveboard data with unsaved changes - -include::{path}/transient-lb-content.adoc[] - -.**Sample browser fetch request** - -[source,TypeScript] ----- -const embedRef = useEmbedRef(); - const handleFilterChanged: MessageCallback = () => { - embedRef.current - .trigger(HostEvent.getExportRequestForCurrentPinboard) - .then((transientPinboardContent) => { - console.log(transientPinboardContent.data); - - const payload = { - metadata_identifier: "abc", - data_format: "COMPACT", - record_offset: 0, - record_size: 10, - transient_content: JSON.stringify(transientPinboardContent.data), - }; - - fetch( - `https://{ThoughtSpot-Host}/api/rest/2.0/metadata/liveboard/data`, - { - method: "POST", - headers: { - Authorization: - "Bearer xxx", - Accept: "application/json", - "Content-Type": "application/json", - }, - body: JSON.stringify(payload), - } - ) - .then((response) => response.json()) - .then(console.log) - .catch(console.log); - }); - }; - - return ( - - ); ----- - -See also, link:https://developers.thoughtspot.com/docs/Enumeration_HostEvent#_getexportrequestforcurrentpinboard[HostEvent.getExportRequestForCurrentPinboard]. - - -=== Fetch Answer Data API - -To get data from a saved Answer object via `/api/rest/2.0/metadata/answer/data`, you need at least view access to the saved Answer. - -The API request body must include the name or GUID of the saved Answer. - -==== Example -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/metadata/answer/data' \ - -H 'Authorization: Bearer {access-token}'\ - -H 'Accept: application/json'\ - -H 'Content-Type: application/json' \ - --data-raw '{ - "metadata_identifier": "e9a3b456-ba71-4d80-9678-38b25edf18dc", - "data_format": "COMPACT", - "record_offset": 0, - "record_size": 10 -}' ----- - -== Report APIs - -ThoughtSpot provides the following REST API v2 endpoints to export reports: - -* xref:#_liveboard_report_api[`POST /api/rest/2.0/report/liveboard`] to export a Liveboard as a PDF or PNG. -* xref:#answer-report[`POST /api/rest/2.0/report/answer`] to export an Answer as PDF, PNG, CSV, or XLSX. - -=== Liveboard Report API - -The `POST /api/rest/2.0/report/liveboard` endpoint exports a Liveboard in PDF or PNG format. - -==== Prerequisites - -To download a Liveboard report, the user must have at least *View* access to the Liveboard. - -If RBAC is enabled, the user must have the `DATADOWNLOADING` (*Can download Data*) privilege or the `CAN_DOWNLOAD_VISUALS` (*Can download visuals*) privilege. - -==== Example - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/liveboard' \ - -H 'Authorization: Bearer {access-token}' \ - -H 'Accept: application/octet-stream' \ - -H 'Content-Type: application/json' \ - --data-raw '{ - "metadata_identifier": "", - "file_format": "PDF" -}' \ - --output liveboard.pdf ----- - -[#answer-report] -=== Answer Report API - -// SOURCE: SCAL-306069 - -`POST /api/rest/2.0/report/answer` - -The Answer Report API is generally available from 26.9.0.cl. Use this endpoint to export Answer data in `CSV`, `XLSX`, `PDF`, or `PNG` format. The endpoint supports saved Answers, pinned Answers (visualizations on a Liveboard), and Spotter-generated (ad hoc) Answers. - -==== Prerequisites - -To download Answer data, the user must have at least *View* access to the Answer or Liveboard. - -If Role-Based Access Control (RBAC) is enabled, the user must have one of the following privileges: - -* `DATADOWNLOADING` (*Can download Data*) -* `CAN_DOWNLOAD_DETAILED_DATA` (*Can download detailed data*) — for CSV and XLSX formats -* `CAN_DOWNLOAD_VISUALS` (*Can download visuals*) — for PNG format - -==== Request parameters - -[width="100%"] -[options="header"] -|===== -| Parameter | Type | Required | Description -| `metadata_identifier` | String | Yes | GUID or name of the saved Answer. For pinned Answers, use the parent Liveboard GUID or name and set `viz_guid`. -| `file_format` | String | Yes | Export format. Accepted values: `CSV`, `XLSX`, `PDF`, `PNG`. -| `viz_guid` | String | No | GUID of a pinned visualization on a Liveboard. Required for pinned Answer exports. Liveboard-level filters and runtime overrides are applied automatically. -| `personalised_view_identifier` | String | No | GUID or name of a Personalized View. When specified, the export uses data from that view. -| `runtime_filter` | Object | No | Runtime filter overrides to apply to the export. -| `runtime_sort` | Object | No | Runtime sort overrides to apply to the export. -| `runtime_param_override` | Object | No | Runtime parameter overrides to apply to the export. -| `x_resolution` | Integer | No | Width of the PNG export in pixels. Accepted range: 600–3840. Applies only when `file_format` is `PNG`. Default: 2254. -| `y_resolution` | Integer | No | Height of the PNG export in pixels. Accepted range: 600–3840. Applies only when `file_format` is `PNG`. Default: 1588. -| `scaling_factor` | Integer | No | Scaling percentage for chart elements in PNG exports. Accepted range: 80–400. Does not crop the image. Applies only when `file_format` is `PNG`. -|===== - -==== Export a saved Answer - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \ - -H 'Authorization: Bearer {access-token}' \ - -H 'Accept: application/octet-stream' \ - -H 'Content-Type: application/json' \ - --data-raw '{ - "metadata_identifier": "", - "file_format": "CSV" -}' \ - --output answer.csv ----- - -==== Export a pinned Answer - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \ - -H 'Authorization: Bearer {access-token}' \ - -H 'Accept: application/octet-stream' \ - -H 'Content-Type: application/json' \ - --data-raw '{ - "metadata_identifier": "", - "viz_guid": "", - "file_format": "PDF" -}' \ - --output pinned-answer.pdf ----- - -==== Export a Spotter Answer - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \ - -H 'Authorization: Bearer {access-token}' \ - -H 'Accept: application/octet-stream' \ - -H 'Content-Type: application/json' \ - --data-raw '{ - "metadata_identifier": "", - "file_format": "XLSX" -}' \ - --output spotter-answer.xlsx ----- - -[NOTE] -==== -To export a Spotter-generated Answer, pass the answer ID from the Spotter API response as `metadata_identifier`. XLSX and PDF formats are supported for Spotter Answers from 26.9.0.cl. -==== - -==== Export a PNG with custom dimensions - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \ - -H 'Authorization: Bearer {access-token}' \ - -H 'Accept: application/octet-stream' \ - -H 'Content-Type: application/json' \ - --data-raw '{ - "metadata_identifier": "", - "file_format": "PNG", - "x_resolution": 3840, - "y_resolution": 2160, - "scaling_factor": 150 -}' \ - --output answer-4k.png ----- - -== Related resources - -* xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog] -* xref:semantic-integrations-api.adoc[Snowflake Semantic View integration APIs] -* xref:spotter-agent-apis.adoc[Spotter Agent APIs] +Unknown tool: github_get_file \ No newline at end of file From 668f2b483508f289d23fda21431c4325788c1295 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 17 Aug 2026 10:23:50 +0530 Subject: [PATCH 11/32] docs: add 26.9.0.cl REST API changelog section (SCAL-306069, SCAL-309867, SCAL-306173, SCAL-320899, SCAL-317550, SCAL-307284, SCAL-312738, SCAL-277656) From 508ed74229eec0da4c93657d458f400230d5640a Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 17 Aug 2026 10:23:52 +0530 Subject: [PATCH 12/32] docs: add Visual Embed SDK 1.52.x changelog (SCAL-317516, SCAL-314461) From e955874e831536e2417744ff5f4c7fe14a394ac5 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 17 Aug 2026 10:23:53 +0530 Subject: [PATCH 13/32] docs: add conversation sharing APIs to spotter-agent-apis.adoc (aug.26.mt) From f17f39599a9b9858a51990c05901c2a88c970be6 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 17 Aug 2026 10:23:54 +0530 Subject: [PATCH 14/32] docs: add Answer Report API GA section to data-report-v2-api.adoc (SCAL-306069) From bc6ae4fbf5879d2955782e77db8117a3724a38c9 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 17 Aug 2026 10:25:48 +0530 Subject: [PATCH 15/32] =?UTF-8?q?docs:=20add=2026.9.0.cl=20REST=20API=20ch?= =?UTF-8?q?angelog=20section=20=E2=80=94=20Answer=20Export=20GA,=20Semanti?= =?UTF-8?q?c=20Integrations,=20Spotter=20Memory=20GA,=20Conversation=20Sha?= =?UTF-8?q?ring,=20KPI=20Sparkline,=20Outline=20Encoding,=20Personalized?= =?UTF-8?q?=20Views=20TML,=20Scheduled=20Liveboards,=20AI=20Context=20(SCA?= =?UTF-8?q?L-306069,=20SCAL-309867,=20SCAL-306173,=20SCAL-320899,=20SCAL-3?= =?UTF-8?q?17550,=20SCAL-307284,=20SCAL-312738,=20SCAL-277656)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- modules/ROOT/pages/rest-apiv2-changelog.adoc | 335 ++++++++++++++++++- 1 file changed, 334 insertions(+), 1 deletion(-) diff --git a/modules/ROOT/pages/rest-apiv2-changelog.adoc b/modules/ROOT/pages/rest-apiv2-changelog.adoc index ec6077f68..91c73b2c1 100644 --- a/modules/ROOT/pages/rest-apiv2-changelog.adoc +++ b/modules/ROOT/pages/rest-apiv2-changelog.adoc @@ -1 +1,334 @@ -Unknown tool: github_get_file \ No newline at end of file += REST API v2.0 changelog +:toc: true +:toclevels: 1 + +:page-title: REST API v2.0 changelog +:page-pageid: rest-v2-changelog +:page-description: Changelog of REST APIs + +This changelog lists the features and enhancements introduced in REST API v2.0. For information about new features and enhancements available for embedded analytics, see xref:whats-new.adoc[What's New]. + +== Version 26.9.0.cl, September 2026 + +=== Answer Export API enhancements — General Availability + +// SOURCE: SCAL-306069 + +The `POST /api/rest/2.0/report/answer` endpoint is generally available from 26.9.0.cl. The `isAnswerExportV2Enabled` flag is enabled by default on all ThoughtSpot Cloud instances. The following enhancements are included in this release: + +Pinned Answer export:: +Pass `viz_guid` to export a pinned Answer (a visualization on a Liveboard) directly. Liveboard-level filters and runtime overrides are applied automatically. The `metadata_identifier` must be the parent Liveboard GUID or name. + +Personalized View support:: +Pass `personalised_view_identifier` to export data from a specific Personalized View of a Liveboard. + +Spotter Answer export:: +XLSX and PDF export formats are now supported for Spotter-generated (ad hoc) Answers, in addition to CSV and PNG. + +Custom PNG dimensions:: +Use `x_resolution` and `y_resolution` parameters to specify custom pixel dimensions for PNG exports. Accepted range: 600–3840 px per axis. Default: 2254 × 1588. + +Display scaling:: +Use `scaling_factor` (range: 80–400) to adjust the relative size of chart elements in a PNG export without cropping the image. + +Dynamic file naming:: +Exported files are automatically named based on the Answer title with the correct file extension (`.png`, `.pdf`, `.csv`, `.xlsx`) appended. + +For more information, see xref:data-report-v2-api.adoc#answer-report[Answer Report API]. + +=== Snowflake Semantic View integration APIs + +// SOURCE: SCAL-309867 + +ThoughtSpot 26.9.0.cl introduces REST API v2.0 endpoints for managing Snowflake Semantic View integrations programmatically. These APIs allow administrators and data managers to create, search, import, and delete semantic integration configurations without using the ThoughtSpot UI. + +[width="100%"] +[options="header"] +|===== +| Method | Endpoint | Description +| `POST` | `/api/rest/2.0/semantic-integrations/create` | Creates a new semantic integration by reading a Snowflake Semantic View and generating a ThoughtSpot data model. +| `POST` | `/api/rest/2.0/semantic-integrations/search` | Returns a list of semantic integrations matching the specified filter criteria. +| `POST` | `/api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/import` | Re-imports semantic updates from Snowflake and refreshes the associated ThoughtSpot data model. +| `POST` | `/api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/delete` | Deletes a semantic integration and its generated ThoughtSpot data model. +|===== + +Required privilege: `ADMINISTRATION` or `DATAMANAGEMENT`. If RBAC is enabled, the user also requires the `CAN_CREATE_OR_EDIT_CONNECTIONS` privilege and permission to manage data models. + +For more information, see xref:semantic-integrations-api.adoc[Snowflake Semantic View integration APIs]. + +=== Spotter Memory — General Availability + +// SOURCE: SCAL-306173 + +The Spotter Memory feature is generally available from 26.9.0.cl. The memory APIs introduced in 26.8.0.cl (`POST /api/rest/2.0/ai/memory/import` and `POST /api/rest/2.0/ai/memory/export`) are enabled by default on all ThoughtSpot Cloud instances. Administrators can manage and audit Spotter training data programmatically without enabling a feature flag. + +For more information, see xref:spotter-ai-memory-api.adoc[Spotter memory APIs]. + +=== Spotter Agent — Conversation sharing APIs + +// SOURCE: SCAL-306173 (aug.26.mt) + +ThoughtSpot 26.9.0.cl introduces REST API v2.0 endpoints for sharing saved Spotter agent conversations with other users or groups. Shared conversations are always `READ_ONLY`. + +[width="100%"] +[options="header"] +|===== +| Method | Endpoint | Description +| `POST` | `/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` | Shares a saved Spotter conversation with specified principals. Use `grant` and `revoke` arrays to manage access. +| `GET` | `/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content` | Returns the content of a shared Spotter conversation — messages, data sources, and answer details. +| `GET` | `/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info` | Returns sharing metadata — the list of principals the conversation is shared with and their access levels. The `is_shared_content_outdated` flag indicates if the shared snapshot is stale. +|===== + +For more information, see xref:spotter-agent-apis.adoc#_sharing_spotter_conversations[Sharing Spotter conversations]. + +=== KPI Sparkline setting in metadata search response + +// SOURCE: SCAL-320899 + +The `POST /api/rest/2.0/metadata/search` API response now includes the `isSparklineEnabled` field in the `AnswerSpecHeader` object for KPI chart type answers. This boolean field indicates whether the sparkline trend line is enabled for the KPI visualization. + +* `true` — the sparkline trend line is enabled. +* `false` — the sparkline is disabled. +* Absent — the answer was saved before this release and has not been re-saved. Treat an absent field as unknown, not as `false`. + +=== Outline Encoding — BYOC Muze + +// SOURCE: SCAL-317550 + +ThoughtSpot 26.9.0.cl promotes mark outline color to a first-class data-driven encoding channel in the Muze charting library (BYOC). Developers building custom charts with Muze can now bind a data field to `encoding.outline` to produce ordinal color palettes (for categorical fields) or continuous gradient ramps (for measures), with full legend rendering and legend-to-mark interaction. + +The static `outline` config (`{ fill, color, width, dash }`) remains fully backward compatible. Supported mark types: Point, Bar, Arc. + +=== Personalized Views TML portability — General Availability + +// SOURCE: SCAL-307284 + +The Personalized Views TML portability feature introduced as Early Access in 26.8.0.cl is generally available from 26.9.0.cl. + +* The `author` field in Personalized View TML maps to the view owner's username or email, ensuring ownership is retained when a Liveboard is promoted across clusters or orgs. +* The `obj_id` field provides a stable cross-environment identifier for Personalized Views. +* Smart merge import: when importing a Liveboard TML that contains Personalized Views, ThoughtSpot preserves views that exist only in the target environment, appends new views from the imported TML, and updates views present in both. + +For more information, see xref:tml.adoc#personalized-views-portability[Personalized Views portability in TML]. + +=== Connection configuration — Scheduled Liveboards process type + +// SOURCE: SCAL-312738 + +ThoughtSpot 26.9.0.cl adds `SCHEDULED_LIVEBOARDS` as a new process type for Embrace connection configurations. Administrators can assign the Scheduled Liveboards process to a connection configuration, enabling ThoughtSpot to use the associated credentials when running scheduled Liveboard delivery jobs. Configurable via: + +* `POST /api/rest/2.0/connection/configuration/create` +* `PUT /api/rest/2.0/connection/configuration/{configuration_identifier}/update` + +=== AI Context — Spotter Optimization tab + +// SOURCE: SCAL-277656 + +The AI Context generation UI is revamped in 26.9.0.cl. A new *Spotter Optimization* tab is introduced in the data model editor for managing AI context, replacing the previous AI Context panel. The tab provides a more streamlined interface for reviewing and editing auto-generated descriptions for columns and joins. + +No changes to the AI context REST API endpoints in this release. + +== Version 26.8.0.cl, August 2026 + +=== Spotter AI APIs + +Spotter memory APIs::: +ThoughtSpot 26.8.0.cl introduces two new REST API v2.0 endpoints for managing Spotter memory programmatically: + +* `POST /api/rest/2.0/ai/memory/import` + +Imports Spotter memory entries in bulk. Use this endpoint to seed training data or migrate Spotter memory across environments. +* `POST /api/rest/2.0/ai/memory/export` + +Exports all current Spotter memory entries. Use this endpoint to back up training data or audit the current training state. + +For more information, see xref:spotter-ai-memory-api.adoc[Spotter memory APIs]. + +=== TML import and export + +New TML fields for Personalized Views::: [earlyAccess eaBackground]#Early Access# +Two new fields have been added to the TML for Personalized Views. You can see these fields added to the TML schema when you export through the `POST /api/rest/2.0/metadata/tml/export` API. + +* A new `author` field is added to the Personalized View TML during export. This field is used to assign ownership during import. +* Personalized Views now carry an `obj_id` field for stable cross-environment object identity, consistent with other object types. + +For more information, see xref:tml.adoc#personalized-views-portability[Personalized Views portability in TML]. + +Collections `obj_id` support::: +// SOURCE: SCAL-317357 +The `obj_id` attribute is now supported for the *Collections* object type in TML import and export APIs. This enables stable cross-environment identification for Collections, matching the behavior already available for Models, Liveboards, Answers, and other object types. ++ +To assign or update the `obj_id` for a Collections object, use the `POST /api/rest/2.0/metadata/identity/update` API endpoint. ++ + +=== Roles API + +Granular download privileges::: +ThoughtSpot introduces two new granular download privileges that give administrators finer control over what users can export: + +* *Can Download Visuals*: Permits downloading chart and visualization images. +* *Can Download Detailed Data*: Permits downloading raw tabular data in CSV or XLSX format. + +These privileges are configurable via the `POST /api/rest/2.0/roles/create` and `POST /api/rest/2.0/roles/update` API endpoints. + +=== Liveboard schedules API +The `every_n_minutes` schedule frequency option is deprecated in 26.8.0.cl. Schedules configured with this frequency will continue to run during the transition period; however, ThoughtSpot recommends updating existing schedules to supported frequency options (hourly, daily, weekly, or monthly). Support for the `every_n_minutes` frequency will be removed in a future release. + +=== REST API C# SDK +ThoughtSpot provides the REST API C# SDK (`ThoughtSpot.RestApi.Sdk`) to help .NET developers interact programmatically with ThoughtSpot REST API v2 endpoints. The SDK targets `net8.0` and is available on link:https://www.nuget.org/packages/ThoughtSpot.RestApi.Sdk[NuGet, window=_blank]. + +For information about how to install and use the SDK, see xref:rest-api-sdk-csharp.adoc[C# SDK for REST APIs]. + +== Version 26.7.0.cl, July 2026 + +=== Spotter AI APIs + +Save chat AI APIs:: +ThoughtSpot introduces the following REST API endpoints and enhancements to manage saved Spotter conversations programmatically. These endpoints allow you to build custom conversation history interfaces in embedded applications without using the native Spotter UI. + +* `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/update` + +Updates attributes of an existing agent conversation. +* `GET /api/rest/2.0/ai/agent/conversations` + +Retrieves the list of saved agent conversations for the currently authenticated user. +* `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/messages` + +Retrieves the full content of a saved conversation with Spotter agent. +* `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/update` + +Updates the display title of a saved conversation. +* `DELETE /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/delete` + +Deletes a saved conversation and all its associated messages. +* `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/answers/{answer_identifier}/details` + +Loads the full answer payload for a specific answer item in an agent conversation. + ++ +For more information, see xref:spotter-agent-conversation-mgmt-apis.adoc[Saving and managing Spotter AI chat]. + +Save chat settings in conversation create API:: + +The `POST /api/rest/2.0/ai/agent/conversation/create` API endpoint is modified to allow users to save conversations by setting `enable_save_chat: true` in the API request. + +Agent instructions APIs:: +The following new API endpoints allow you to set and retrieve persistent behavioral instructions for the Spotter agent. + +* `PUT /api/rest/2.0/ai/agent/instructions/set` + +Sets behavioral instructions for the Spotter agent. Use this endpoint to define persistent guidance that Spotter applies when responding to queries in a conversation session. + +* `GET /api/rest/2.0/ai/agent/instructions/get` + +Retrieves the behavioral instructions currently configured by the administrator for the Spotter agent. ++ +For more information, see xref:spotter-agent-instructions.adoc[Spotter AI Agent instructions APIs]. + +=== Webhooks + +New API endpoint:: +The `GET /api/rest/2.0/webhooks/storage-config` API endpoint allows retrieving the storage setup information required for configuring a GCS or S3 storage destination for webhook delivery. + +Enhancements:: + +* The `/api/rest/2.0/webhooks/create` endpoint allows activating a webhook and configuring a GCS storage destination for webhook delivery. The API endpoint also returns GCS storage configuration details in the response. +* The `/api/rest/2.0/webhooks/{webhook_identifier}/update` API endpoint supports configuring webhook activation status, resetting authentication, signature verification, and storage destination properties. +* API requests to the `/api/rest/2.0/system/communication-channels/validate` now return GCS storage properties in response. + +=== Communication channel monitoring + +The `/api/rest/2.0/jobs/history/communication-channels/search` API endpoint supports the `end_epoch_time_in_millis` parameter, which allows fetching records with a specific end timestamp. + +=== Style customization APIs + +ThoughtSpot introduces the following REST API v2.0 endpoints to manage style customization settings programmatically. + +Style configuration:: + +* `POST /api/rest/2.0/customization/styles/search` + +Returns the current style configuration at the `CLUSTER` or active `ORG` scope. + +* `POST /api/rest/2.0/customization/styles/update` + +Updates style settings at the `CLUSTER` or `ORG` scope. + +Custom fonts:: + +* `POST /api/rest/2.0/customization/styles/fonts/upload` + +Uploads a custom font file to ThoughtSpot. + +* `POST /api/rest/2.0/customization/styles/fonts/search` + +Returns custom fonts uploaded to the instance. + +* `PUT /api/rest/2.0/customization/styles/fonts/{font_identifier}/update` + +Updates a custom font record. + +* `DELETE /api/rest/2.0/customization/styles/fonts/{font_identifier}/delete` + +Deletes a custom font. + +For more information, see xref:style-customization-api.adoc[Style customization APIs]. + +=== Liveboard schedules + +* The `POST /api/rest/2.0/schedules/create` API endpoint now supports the `connection_configuration_identifier` attribute. This attribute specifies a configured Embrace connection configuration when creating a scheduled Liveboard job. +* The `POST /api/rest/2.0/schedules/{schedule_identifier}/update` API endpoint now supports the `connection_configuration_identifier` attribute. + +=== Tags API + +The `POST /api/rest/2.0/tags/assign` and `POST /api/rest/2.0/tags/unassign` API endpoints now support Collections as a metadata object type. + +=== Custom actions + +The `POST /api/rest/2.0/customization/custom-actions/create` and `POST /api/rest/2.0/customization/custom-actions/{custom_action_identifier}/update` API endpoints now support `group_identifiers` for access control. This allows restricting custom action visibility to specific user groups. + +== Version 26.6.0.cl, June 2026 + +=== Spotter AI APIs + +Answer Export API [earlyAccess eaBackground]#Early Access#:: +ThoughtSpot introduces the `POST /api/rest/2.0/report/answer` endpoint for exporting Answer data in CSV, XLSX, PDF, or PNG format. Requires the `isAnswerExportV2Enabled` feature flag to be enabled on the instance. + +For more information, see xref:data-report-v2-api.adoc#answer-report[Answer Report API]. + +Stop Spotter response:: +The `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response` API endpoint stops an in-progress Spotter agent response for a given conversation session. The conversation session remains active after the response stops. + +=== Connections + +Connection configurations:: +ThoughtSpot introduces the following new API endpoints for managing Embrace connection configurations: + +* `POST /api/rest/2.0/connection/configuration/create` + +Creates a connection configuration for an Embrace connection. +* `GET /api/rest/2.0/connection/configuration/{configuration_identifier}` + +Retrieves an existing connection configuration. +* `PUT /api/rest/2.0/connection/configuration/{configuration_identifier}/update` + +Updates an existing connection configuration. +* `DELETE /api/rest/2.0/connection/configuration/{configuration_identifier}/delete` + +Deletes a connection configuration. +* `POST /api/rest/2.0/connection/configuration/search` + +Returns a list of connection configurations matching the specified filter criteria. + +For more information, see xref:embrace-connection-configuration.adoc[Connection configurations]. + +=== REST API Python SDK + +ThoughtSpot provides the REST API Python SDK (`thoughtspot-rest-api-sdk`) to help Python developers interact programmatically with ThoughtSpot REST API v2 endpoints. The SDK is available on link:https://pypi.org/project/thoughtspot-rest-api-sdk/[PyPI, window=_blank]. + +For information about how to install and use the SDK, see xref:rest-api-sdk-python.adoc[Python SDK for REST APIs]. + +== Version 26.5.0.cl, May 2026 + +=== Spotter AI APIs + +The following API endpoints are deprecated in 26.5.0.cl: + +* `POST /api/rest/2.0/ai/agent/converse/sse` — Use `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream` instead. +* `POST /api/rest/2.0/ai/agent/{conversation_identifier}/converse` — Use `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send` instead. + +New API endpoints:: + +* `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send` + +Sends natural language messages to an existing Spotter agent conversation and returns the complete response synchronously. + +* `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream` + +Sends natural language messages to an existing Spotter agent conversation and returns the response as a real-time Server-Sent Events (SSE) stream. + +Breaking changes in `POST /api/rest/2.0/ai/agent/conversation/create`:: +The `metadata_context` object now requires `type` to be one of `AUTO_MODE` or `DATA_SOURCE`. The legacy `data_source` option is deprecated. + +=== REST API TypeScript SDK + +ThoughtSpot provides the REST API TypeScript SDK (`@thoughtspot/rest-api-sdk`) to help developers interact programmatically with ThoughtSpot REST API v2 endpoints. The SDK is available on link:https://www.npmjs.com/package/@thoughtspot/rest-api-sdk[npm, window=_blank]. + +For information about how to install and use the SDK, see xref:rest-api-sdk-typescript.adoc[TypeScript SDK for REST APIs]. From 190dd381acd311ad5a1b9b7c7a21539e4851780d Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 17 Aug 2026 10:26:58 +0530 Subject: [PATCH 16/32] =?UTF-8?q?docs:=20add=20Visual=20Embed=20SDK=201.52?= =?UTF-8?q?.x=20changelog=20=E2=80=94=20overrideHistoryState,=20HomeLeftNa?= =?UTF-8?q?vItem.Collections=20(SCAL-317516,=20SCAL-314461)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- modules/ROOT/pages/api-changelog.adoc | 281 +++++++++++++++++++++++++- 1 file changed, 280 insertions(+), 1 deletion(-) diff --git a/modules/ROOT/pages/api-changelog.adoc b/modules/ROOT/pages/api-changelog.adoc index ec6077f68..44d9a9a16 100644 --- a/modules/ROOT/pages/api-changelog.adoc +++ b/modules/ROOT/pages/api-changelog.adoc @@ -1 +1,280 @@ -Unknown tool: github_get_file \ No newline at end of file += Visual Embed SDK changelog +:toc: true +:toclevels: 2 + +:page-title: Visual Embed SDK changelog +:page-pageid: embed-sdk-changelog +:page-description: Changelog for the Visual Embed SDK + +This page documents the changes introduced in each release of the Visual Embed SDK. For information about the REST API v2.0 changes, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. + +== Version 1.52.x, September 2026 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| + +[discrete] +===== Browser history management in full application embedding + +// SOURCE: SCAL-317516 +// SOURCE: thoughtspot/visual-embed-sdk/src/types.ts (master) + +ThoughtSpot 26.9.0.cl introduces the `overrideHistoryState` configuration parameter for `AppEmbed`. When embedding ThoughtSpot in a host application, every internal ThoughtSpot navigation event (for example, switching between Liveboards or Answers) pushes a new entry onto the browser's history stack. This causes the browser *Back* button to step through ThoughtSpot's internal navigation before returning to the host application's prior page. + +Setting `overrideHistoryState: true` converts all ThoughtSpot internal `pushState` calls to `replaceState`, preventing ThoughtSpot navigation from polluting the host application's browser history stack. + +[source,JavaScript] +---- +import { AppEmbed, init, AuthType } from '@thoughtspot/visual-embed-sdk'; + +init({ + thoughtSpotHost: 'https://.thoughtspot.cloud', + authType: AuthType.TrustedAuthToken, + getAuthToken: () => fetch('/ts-token').then(r => r.json()).then(d => d.token), +}); + +const embed = new AppEmbed('#embed-container', { + frameParams: { width: '100%', height: '100%' }, + overrideHistoryState: true, // <1> +}); + +embed.render(); +---- +<1> When set to `true`, ThoughtSpot replaces rather than pushes browser history entries during internal navigation. + +[NOTE] +==== +`overrideHistoryState` is available on `AppEmbed` only. It is not supported on `LiveboardEmbed`, `SearchEmbed`, or `SpotterEmbed`. Validate behavior across Chrome, Firefox, and Safari before enabling in production. +==== + +For more information, see xref:full-app-embed.adoc[Full application embedding]. + +|[tag greenBackground]#NEW FEATURE# a| + +[discrete] +===== Collections in left navigation panel + +// SOURCE: SCAL-314461 + +The `HomeLeftNavItem.Collections` enum value is now available in the Visual Embed SDK. Embed developers can include *Collections* as a selectable navigation option in the embedded left navigation panel for full application embeds. When enabled, end users of the embedded application can navigate to *Collections* from the left navigation panel. + +[source,JavaScript] +---- +import { AppEmbed, HomeLeftNavItem, init, AuthType } from '@thoughtspot/visual-embed-sdk'; + +init({ + thoughtSpotHost: 'https://.thoughtspot.cloud', + authType: AuthType.TrustedAuthToken, + getAuthToken: () => fetch('/ts-token').then(r => r.json()).then(d => d.token), +}); + +const embed = new AppEmbed('#embed-container', { + frameParams: { width: '100%', height: '100%' }, + leftNavOrder: [ + HomeLeftNavItem.Home, + HomeLeftNavItem.Liveboards, + HomeLeftNavItem.Answers, + HomeLeftNavItem.Collections, // <1> + ], +}); + +embed.render(); +---- +<1> Include `HomeLeftNavItem.Collections` in the `leftNavOrder` array to show Collections in the embedded left navigation panel. + +For more information, see xref:full-app-customize.adoc[Customize full application embedding]. + +|==== + +== Version 1.51.x, August 2026 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| + +[discrete] +===== Spotter embedding + +Spotter Analysts:: +The Visual Embed SDK introduces controls for the Spotter Analysts feature in embedded applications. The Analysts section in the Spotter sidebar is disabled by default in the embed mode. For more information, see xref:customize-spotter-embed.adoc#_spotter_analysts[Spotter Analysts in embed view]. + +Starter prompts:: +If quick starter prompts are enabled and configured for data models on a ThoughtSpot instance, you can display these prompts in the embed using the `enableStarterPrompts` parameter. For more information, see xref:customize-spotter-embed.adoc#_spotter_starter_prompts[Spotter quick starter prompts]. + +|[tag greenBackground]#MODIFIED# a| + +[discrete] +===== Liveboard embedding +The following Liveboard embedding settings are set to `true` by default on all ThoughtSpot embedded instances: + +* `hideIrrelevantChipsInLiveboardTabs` + +Hides filters that are not relevant to the displayed visualization. +* `isLiveboardCompactHeaderEnabled` + +Enables compact header layout in embedded Liveboards. +* `coverAndFilterOptionInPDF` + +Enables the *Include cover page* and *Include filter page(s)* checkboxes in the Liveboard download modal. +* `isLiveboardMasterpiecesEnabled` + +Enables the xref:embed-pinboard.adoc#_liveboard_grouping_and_styling[Liveboard styling and grouping] feature. +* `isEnhancedFilterInteractivityEnabled` + +Enables interactive filter chips that allow users to add, update, or remove filters in an embedded Liveboard. + +For more information, see xref:embed-pinboard.adoc#common-customizations[Common customization options in Liveboard embedding]. + +|[tag greenBackground]#NEW FEATURE# a| + +[discrete] +===== Object format support in HostEvent.Navigate +The `HostEvent.Navigate` event now supports an object format in addition to the existing string path format. Use the object format to replace the current browser history entry instead of pushing a new entry. + +//// +[source,JavaScript] +---- +// String format — push new history entry (existing behavior, unchanged) +appEmbed.trigger(HostEvent.Navigate, 'home'); +---- + +[source,JavaScript] +---- +// Object format — replace current history entry (new in SDK 1.51.0) +appEmbed.trigger(HostEvent.Navigate, { path: 'home', replace: true }); +---- +Supported embed types: `AppEmbed`. +//// + +|==== + +== Version 1.50.x, July 2026 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| + +[discrete] +===== SpotterViz embed customization +The Visual Embed SDK 1.50.0 introduces the `SpotterVizConfig` interface and `SpotterVizStarterPrompt` interface to allow embed developers to customize the SpotterViz panel on embedded Liveboards and full-application embeds. + +A new `SpotterVizConfig` interface is available on `LiveboardViewConfig` and `AppViewConfig` for the `spotterViz` object. This object provides branding customization controls for customizing the SpotterViz panel experience. For more information, see xref:embed-spotterViz.adoc[SpotterViz in embedded Liveboards]. + +|[tag greenBackground]#NEW FEATURE# a| + +[discrete] +===== Home page customization in full application embedding +For full application embedding, ThoughtSpot provides a focused and streamlined home page experience. To enable this feature, use the `HomePage.Focused` option with the `homePage` attribute in the `discoveryExperience` object. + +For more information, see xref:full-app-customize.adoc[Customize full application embedding]. +|==== + +== Version 1.49.x, June 2026 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| +[discrete] +===== Visual overrides for charts and tables +The SDK introduces the `visualOverrides` object in `SearchViewConfig` and +`AppViewConfig`, enabling embed developers to apply chart and table display +customizations to the new answers from an embedded Search data interface at initialization time. + +The `visualOverrides` object provides the following customization controls to modify the chart and table display: + +* `legend` to control legend visibility, position, and color palette of charts. +* `dataLabel` attribute for data labels and per-column label filters. +* `display` attributes such as regression line overlay and grid line visibility in charts, and table themes and content density in tables. +* `axis` property for axis name and label visibility and fixed y-axis range. +* `columns` property for per-column series color and conditional formatting rules in charts, and column visibility, text wrapping, conditional formatting, and column summary in tables. +* `updateMaskPaths` property for partial updates. + +For more information, see xref:viz-overrides.adoc[Visualization overrides]. +|[tag greenBackground]#NEW FEATURE# a| + +[discrete] +===== Liveboard browser cache refresh +For embedded Liveboards, the SDK provides `enableLiveboardDataCache` to clear browser cache and fetch new data for the visualizations on the Liveboard. + +The SDK also provides the following events and action ID to programmatically trigger cache refresh and control the visibility of the **Refresh** button. + +* `EmbedEvent.RefreshLiveboardBrowserCache` + +Emitted when the Liveboard browser cache is refreshed. +* `HostEvent.RefreshLiveboardBrowserCache` + +Trigger a manual cache refresh from the host application. +* `Action.RefreshLiveboardBrowserCache` + +Action ID to show or hide the cache refresh button. + +For more information, see xref:embed-pinboard.adoc#liveboard-data-cache[Enable Liveboard refresh]. + +|[tag greenBackground]#NEW FEATURE# a| +[discrete] +===== Spotter file upload +The SDK introduces the following configuration parameters in `SpotterChatConfig` object to enable and control file uploads in the embedded Spotter chat interface. + +* `spotterFileUploadEnabled` + +When set to `true`, enables the file upload feature in the Spotter chat panel. + +* `spotterFileUploadFileTypes` + +Restricts the file types allowed for upload in the Spotter chat panel. + +For more information, see xref:embed-spotter.adoc#fileUpload[Allowing file uploads in Spotter chats]. + +|==== + +== Version 1.48.x, May 2026 +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| +[discrete] +===== Liveboard embedding +The SDK includes the following new features and enhancements in Liveboard embedding. + +Continuous Liveboard layout in PDF downloads [beta betaBackground]^Beta^:: + +When set to `true`, the `isContinuousLiveboardPDFEnabled` enables the Liveboard tab to render on a single page that matches the exact UI layout you see in ThoughtSpot. This update addresses the issue where visualizations for PDF downloads were split across multiple A4 pages regardless of how they appear on screen. This feature is in beta and can be enabled by setting `isContinuousLiveboardPDFEnabled` to `true`. + +New events and action IDs;; + +* `EmbedEvent.DownloadLiveboardAsContinuousPDF` + +Emits when the download action is triggered. +* `HostEvent.DownloadLiveboardAsContinuousPDF` + +Triggers a download of the Liveboard as a continuous PDF. +* `Action.DownloadLiveboardAsContinuousPDF` + +Action ID to show or hide the continuous PDF download option. + +Org-level Liveboard filter settings;; +Administrators can configure Liveboard filter settings for all users in an Org using the new org-level filter configuration option. For more information, see xref:embed-pinboard.adoc#org-filter-config[Configure Liveboard filter settings for an Org]. + +|[tag greenBackground]#NEW FEATURE# a| +[discrete] +===== Search embedding +* The `SearchEmbed` now supports the `dataPanelCustomGroupsAccordionInitialState` attribute to control the initial expanded or collapsed state of custom groups in the data panel. +* New action IDs to show or hide Edit and Delete buttons for saved Answers in the Search interface: +** `Action.EditAnswer` +** `Action.DeleteAnswer` + +|[tag greenBackground]#NEW FEATURE# a| +[discrete] +===== Full application embedding +The `AppEmbed` configuration now supports `disableMultipleOrgsGlobalSearch` to disable the global search scope across multiple Orgs in embedded full application mode. + +|==== + +== Version 1.47.x, April 2026 +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| +[discrete] +===== Spotter embedding +* The `SpotterEmbed` now includes the `isSpotterFullPageEnabled` parameter. When set to `true`, the Spotter interface occupies the full available height of the embed container. +* The `enableSpotterFileUpload` parameter enables file upload capability directly in embedded Spotter. + +|[tag greenBackground]#NEW FEATURE# a| +[discrete] +===== Liveboard embedding +* New action ID `Action.CopyToClipboard` to show or hide the *Copy to clipboard* option for Liveboard visualizations. +* The `LiveboardEmbed` now supports the `isFilterPanelOpen` attribute to set the initial open or closed state of the filter panel. + +|[tag greenBackground]#NEW FEATURE# a| +[discrete] +===== Full application embedding +The `AppEmbed` configuration now supports `hideApplicationSwitcher` to hide the application switcher control from the embedded ThoughtSpot navigation bar. + +|==== From 6daae0a0c5e123e4559faf78ef89ff10e892a5f9 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 17 Aug 2026 10:28:21 +0530 Subject: [PATCH 17/32] =?UTF-8?q?docs:=20add=20Answer=20Report=20API=20GA?= =?UTF-8?q?=20section=20to=20data-report-v2-api.adoc=20=E2=80=94=20pinned?= =?UTF-8?q?=20Answer,=20Spotter=20Answer,=20PNG=20dimensions=20(SCAL-30606?= =?UTF-8?q?9)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- modules/ROOT/pages/data-report-v2-api.adoc | 377 ++++++++++++++++++++- 1 file changed, 376 insertions(+), 1 deletion(-) diff --git a/modules/ROOT/pages/data-report-v2-api.adoc b/modules/ROOT/pages/data-report-v2-api.adoc index ec6077f68..648618486 100644 --- a/modules/ROOT/pages/data-report-v2-api.adoc +++ b/modules/ROOT/pages/data-report-v2-api.adoc @@ -1 +1,376 @@ -Unknown tool: github_get_file \ No newline at end of file += Data and Report APIs +:toc: true +:toclevels: 3 + +:page-title: data-apis +:page-pageid: fetch-data-and-report-apis +:page-description: Data and Report APIs + +== Data APIs +ThoughtSpot provides the following REST API v2 endpoints to fetch data: + +* xref:#_search_data_api[`POST /api/rest/2.0/searchdata`] to search data from a given data source. +* xref:#_fetch_liveboard_api[`POST /api/rest/2.0/metadata/liveboard/data`] to get data from a Liveboard. +* xref:#_fetch_answer_data_api[`POST /api/rest/2.0/metadata/answer/data`] to get data from a saved Answer. + +If Role-Based Access Control (RBAC) is enabled, the `DATADOWNLOADING` (Can download Data) privilege is required to use these APIs. Alternatively, if the granular data download RBAC privileges are enabled for your ThoughtSpot instance, the `CAN_DOWNLOAD_DETAILED_DATA` (Can download detailed data) is required. + +=== Search data API + +The `/api/rest/2.0/searchdata` endpoint requires you to specify the data source object ID and a query string for a successful API call. You can also define additional parameters such as `runtime_filter`, `runtime_sort`, and `runtime_param_override` to apply runtime overrides on the data set. + +==== Data source +To search data via API call, you require at least view access to the data source object. The data source object can be a Model, View, or Table. + +You can specify the data source object GUID in the `logical_table_identifier`. The search data endpoint doesn't support searching data from multiple Models, Views, or Tables in a single API request. + +To find the GUID of the Model, View, or Table, use one of the following methods: + +Get data object GUID via API:: + +Send an API request to the `/api/rest/2.0/metadata/search` endpoint with the following parameters in the metadata array: + + ++ +.**Example** +[source,JSON] +---- + "metadata": [ + { + "identifier": "my_model", + "type": "LOGICAL_TABLE" + } + ] +---- + ++ +If you don't know the exact name of the data source object, specify the metadata `type` as `LOGICAL_TABLE` in your API request, and then copy the GUID of the data object from the API response. + +Find the GUID of the data object via UI:: +. Log in to your ThoughtSpot application instance: +. Navigate to **Data workspace**. ++ +---- +https:///#/data/tables/ +---- ++ +. On the **Data workspace** > **Data objects** page, select the data object. For example, if the data source object is a Model, click **Models** and then open the Model. +. In the address bar of the web browser, note the GUID of the data source object. For example, in the following address string, the GUID is `9d93a6b8-ca3a-4146-a1a1-e908b71b963f`: ++ +---- +https:///#/data/tables/9d93a6b8-ca3a-4146-a1a1-e908b71b963f +---- + +. Copy the GUID. + +==== Search query + +include::{path}/search-query-string.adoc[] + +.**Example** +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/searchdata' \ + -H 'Authorization: Bearer {access-token} + -H 'Accept: application/json'\ + -H 'Content-Type: application/json' \ + --data-raw '{ + "query_string": "[sales][store]", + "logical_table_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", +}' +---- + +//// +==== Using tokens generated from Spotter APIs as raw data + +For every natural language query and follow-up question, Spotter APIs such as `/api/rest/2.0/ai/answer/create`, `/api/rest/2.0/ai/agent/converse/sse`, return tokens in the API response. You can use these tokens as raw data to generate an Answer from ThoughtSpot via search data API. + +===== Request example + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/searchdata' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "query_string": "by [city], [product], [item type] = [item type].'\''jackets'\'', [region] = [region].'\''west'\'', sort by sum [sales] descending", + "logical_table_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", + "data_format": "COMPACT", + "record_offset": 0, + "record_size": 10 +}' +---- + +===== API response + +If the API request is successful, ThoughtSpot returns the Answer data for the query string sent in the API request. +//// + +=== Fetch Liveboard Data API +To get data from a Liveboard object and its visualizations via `POST /api/rest/2.0/metadata/liveboard/data` endpoint, your user account must have at least view access to the Liveboard specified in the API request. + +The API request body must include the name or GUID of the Liveboard to fetch data. To get specific visualizations from a given Liveboard, add the names or GUIDs of the visualizations in the `visualization_identifiers` array. + +==== Example +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/metadata/liveboard/data' \ + -H 'Authorization: Bearer {access-token}'\ + -H 'Accept: application/json'\ + -H 'Content-Type: application/json' \ + --data-raw '{ + "metadata_identifier": "d084c256-e284-4fc4-b80c-111cb606449a", + "data_format": "COMPACT", + "visualization_identifiers": [ + "a9655c18-9855-4a73-9e7b-ff4fb6da334b", + "bf4c9814-82c1-4ec4-b879-57eae2134cb4", + "8c46d2b6-94c7-4ba7-a628-6e74e297f973", + "f6ef5d1f-cddb-4547-8b66-af4d5f4da5ad" + ] +}' +---- + +[#transient-lb-content] +==== Liveboard data with unsaved changes + +include::{path}/transient-lb-content.adoc[] + +.**Sample browser fetch request** + +[source,TypeScript] +---- +const embedRef = useEmbedRef(); + const handleFilterChanged: MessageCallback = () => { + embedRef.current + .trigger(HostEvent.getExportRequestForCurrentPinboard) + .then((transientPinboardContent) => { + console.log(transientPinboardContent.data); + + const payload = { + metadata_identifier: "abc", + data_format: "COMPACT", + record_offset: 0, + record_size: 10, + transient_content: JSON.stringify(transientPinboardContent.data), + }; + + fetch( + `https://{ThoughtSpot-Host}/api/rest/2.0/metadata/liveboard/data`, + { + method: "POST", + headers: { + Authorization: + "Bearer xxx", + Accept: "application/json", + "Content-Type": "application/json", + }, + body: JSON.stringify(payload), + } + ) + .then((response) => response.json()) + .then(console.log) + .catch(console.log); + }); + }; + + return ( + + ); +---- + +See also, link:https://developers.thoughtspot.com/docs/Enumeration_HostEvent#_getexportrequestforcurrentpinboard[HostEvent.getExportRequestForCurrentPinboard]. + + +=== Fetch Answer Data API + +To get data from a saved Answer object via `/api/rest/2.0/metadata/answer/data`, you need at least view access to the saved Answer. + +The API request body must include the name or GUID of the saved Answer. + +==== Example +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/metadata/answer/data' \ + -H 'Authorization: Bearer {access-token}'\ + -H 'Accept: application/json'\ + -H 'Content-Type: application/json' \ + --data-raw '{ + "metadata_identifier": "9bd202f5-d431-44bf-be0b-bb9354c7a840", + "data_format": "COMPACT", + "record_offset": 0, + "record_size": 10 +}' +---- + +== Report APIs +ThoughtSpot provides the following REST API v2 endpoints to download data as reports: + +* xref:#_liveboard_report_api[`POST /api/rest/2.0/report/liveboard`] to download a Liveboard or specific visualizations on the Liveboard as a PDF, PNG, or CSV file. +* xref:#answer-report[`POST /api/rest/2.0/report/answer`] to download Answer data as a CSV, XLSX, PDF, or PNG file. + +=== Liveboard Report API +The Liveboard Report API allows you to programmatically download a Liveboard or specific visualizations as a PDF, PNG, or CSV file via `POST /api/rest/2.0/report/liveboard`. + +To use this API endpoint, you need at least view access to the Liveboard. If Role-Based Access Control (RBAC) is enabled on your instance, you also need the `DATADOWNLOADING` privilege or one of the granular download privileges listed below. + +The following report types are available: + +PDF:: +Downloads the entire Liveboard as a PDF file. + +PNG:: +Downloads a single visualization on the Liveboard as a PNG file. Requires `visualization_identifiers` with a single visualization GUID. + +CSV:: +Downloads the data from a single visualization on the Liveboard as a CSV file. Requires `visualization_identifiers` with a single visualization GUID. + +==== Request parameters + +[width="100%" cols="2,1,4"] +[options="header"] +|===== +| Parameter | Required | Description +| `metadata_identifier` | Yes | GUID or name of the Liveboard to download. +| `file_format` | Yes | Report format. Accepted values: `PDF`, `PNG`, `CSV`, `XLSX`. +| `visualization_identifiers` | Conditional | Array of visualization GUIDs. Required when `file_format` is `PNG` or `CSV`. For PDF, optional — if not specified, all visualizations are included. +| `runtime_filter` | No | Runtime filter overrides to apply. +| `runtime_sort` | No | Runtime sort overrides to apply. +| `runtime_param_override` | No | Runtime parameter overrides to apply. +| `transient_content` | No | Liveboard data with unsaved changes. +| `pdf_options` | No | PDF-specific options: `orientation` (`PORTRAIT` or `LANDSCAPE`), `truncate_tables` (boolean), `include_logo`, `footer_text`, `include_page_number`, `cover_page`, `filter_page`. +|===== + +==== Example +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/liveboard' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/octet-stream' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "metadata_identifier": "d084c256-e284-4fc4-b80c-111cb606449a", + "file_format": "PDF", + "pdf_options": { + "orientation": "LANDSCAPE", + "include_logo": true, + "include_page_number": true + } +}' \ + --output liveboard.pdf +---- + +[#answer-report] +=== Answer Report API + +// SOURCE: SCAL-306069 + +The `POST /api/rest/2.0/report/answer` endpoint is generally available from 26.9.0.cl. Use this endpoint to export Answer data in CSV, XLSX, PDF, or PNG format. The endpoint supports saved Answers, pinned Answers (visualizations on a Liveboard), and Spotter-generated (ad hoc) Answers. + +==== Prerequisites + +To download Answer data, the user must have at least *View* access to the Answer or Liveboard. If RBAC is enabled: + +* `DATADOWNLOADING` (Can download Data) — required for all export formats. +* `CAN_DOWNLOAD_DETAILED_DATA` (Can download detailed data) — required for CSV and XLSX. +* `CAN_DOWNLOAD_VISUALS` (Can download visuals) — required for PNG. + +==== Request parameters + +[width="100%" cols="2,1,4"] +[options="header"] +|===== +| Parameter | Required | Description +| `metadata_identifier` | Conditional | GUID or name of the saved Answer. For pinned Answer exports, use the parent Liveboard GUID or name and pass `viz_guid` separately. +| `file_format` | Yes | Export format. Accepted values: `CSV`, `XLSX`, `PDF`, `PNG`. +| `viz_guid` | No | GUID of a pinned visualization on a Liveboard. When specified, `metadata_identifier` must identify the parent Liveboard. +| `personalised_view_identifier` | No | GUID or name of a Personalized View. When specified, the export uses data from that view. +| `runtime_filter` | No | Runtime filter overrides to apply to the export. +| `runtime_sort` | No | Runtime sort overrides to apply to the export. +| `runtime_param_override` | No | Runtime parameter overrides to apply to the export. +| `x_resolution` | No | Width of the PNG export in pixels. Range: 600–3840. Applies only when `file_format` is `PNG`. Default: 2254. +| `y_resolution` | No | Height of the PNG export in pixels. Range: 600–3840. Applies only when `file_format` is `PNG`. Default: 1588. +| `scaling_factor` | No | Scaling percentage for chart elements in PNG exports. Range: 80–400. Does not crop the image. Applies only when `file_format` is `PNG`. +|===== + +==== Export a saved Answer + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/octet-stream' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "metadata_identifier": "my-saved-answer", + "file_format": "CSV" +}' \ + --output answer.csv +---- + +==== Export a pinned Answer + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/octet-stream' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "metadata_identifier": "", + "viz_guid": "", + "file_format": "PDF" +}' \ + --output pinned-answer.pdf +---- + +==== Export a Spotter Answer + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/octet-stream' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "metadata_identifier": "", + "file_format": "XLSX" +}' \ + --output spotter-answer.xlsx +---- + +[NOTE] +==== +Pass the answer ID from the Spotter API response as `metadata_identifier`. XLSX and PDF formats are supported for Spotter Answers from 26.9.0.cl. +==== + +==== Export a PNG with custom dimensions + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/octet-stream' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "metadata_identifier": "my-saved-answer", + "file_format": "PNG", + "x_resolution": 3840, + "y_resolution": 2160, + "scaling_factor": 150 +}' \ + --output answer-4k.png +---- From e9748595b30c2536fba56428584e7187de233ae1 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 17 Aug 2026 10:30:50 +0530 Subject: [PATCH 18/32] =?UTF-8?q?docs:=20add=20conversation=20sharing=20AP?= =?UTF-8?q?Is=20to=20spotter-agent-apis.adoc=20=E2=80=94=20share,=20get-sh?= =?UTF-8?q?ared-content,=20get-share-info=20(SCAL-306173,=20aug.26.mt)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- modules/ROOT/pages/spotter-agent-apis.adoc | 1448 +++++++++++++++++++- 1 file changed, 1447 insertions(+), 1 deletion(-) diff --git a/modules/ROOT/pages/spotter-agent-apis.adoc b/modules/ROOT/pages/spotter-agent-apis.adoc index ec6077f68..b9a909ee3 100644 --- a/modules/ROOT/pages/spotter-agent-apis.adoc +++ b/modules/ROOT/pages/spotter-agent-apis.adoc @@ -1 +1,1447 @@ -Unknown tool: github_get_file \ No newline at end of file += Spotter Agent APIs +:toc: true +:toclevels: 2 + +:page-title: Spotter Agent APIs +:page-pageid: spotter-agent-apis +:page-description: You can use Spotter REST APIs to receive Answers for your analytical queries sent through the conversational experience with ThoughtSpot. + +ThoughtSpot's Spotter Agent APIs allow users to start a conversation session with Spotter Agent and send queries to explore data and receive responses synchronously or as a real-time Server-Sent Events (SSE) stream. + +== Overview +Spotter Agent APIs support conversation sessions with natural language query strings, provide context-aware and guided data analysis, and allow integration with other agentic systems. + +The key capabilities of the Spotter APIs include the following: + +* Initiating and managing conversational sessions +* Processing natural-language queries +* Generating analytical responses, insights, and visualizations +* Recommending relevant datasets or data sources +* Decomposing complex user queries + +== API endpoints + +The AI REST API endpoints listed in the following table provide all the functionality necessary to implement a Spotter 3 conversational experience in your application, from data source discovery through to streaming query responses. +The API endpoints introduced for Spotter 2 also support Spotter 3 capabilities as of version 26.2.0.cl. Some of these API endpoints are deprecated in 26.5.0.cl; ThoughtSpot recommends using the new API endpoints instead. + +Initialize session:: +Call the create agent conversation API (`/api/rest/2.0/ai/agent/conversation/create`) with a data source ID to establish the session context. When auto mode is enabled, and no data source ID is specified in the API request, Spotter will automatically identify the appropriate data source. + +Execute queries:: +To execute queries and generate a standard response synchronously, use the Send agent conversation message API (`/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send`). The send agent message API (`/api/rest/2.0/ai/agent/{conversation_identifier}/converse`) is deprecated in 26.5.0.cl and later versions. + +Real-time output (streaming):: +To stream responses to the application UI in real-time, use the `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream`. The legacy streaming API (`/api/rest/2.0/ai/agent/converse/sse`) is deprecated in 26.5.0.cl and later versions. + +=== Supported API endpoints + +[width="100%" cols="1"] +|===== +a|`POST /api/rest/2.0/ai/agent/conversation/create` + +xref:spotter-agent-apis.adoc#_create_a_conversation_session_with_spotter_agent[Creates a conversation session with the Spotter agent] to generate Answers for the specified data context. +__Available on ThoughtSpot Cloud instances from 10.13.0.cl onwards. Breaking changes introduced in 26.5.0.cl.__ + +a| `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send` [.version-badge.new]#New# + +xref:spotter-agent-apis.adoc#_send_queries_to_a_conversation_session[Sends natural language messages] to an existing Spotter agent conversation and returns the complete response synchronously. +__Replaces /api/rest/2.0/ai/agent/{conversation_identifier}/converse__. + +a|`POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream` [.version-badge.new]#New# + +xref:spotter-agent-apis.adoc#_send_a_query_to_agent_and_get_streaming_responses[Sends one or more natural language messages] to an existing Spotter agent conversation and returns the response as a real-time Server-Sent Events (SSE) stream. +__Replaces /api/rest/2.0/ai/agent/converse/sse__. + +a|`POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response` [.version-badge.new]#New# + +xref:spotter-agent-apis.adoc#_stop_an_in_progress_agent_response[Stops an in-progress Spotter agent response] for a given conversation session. The conversation session remains active after the response stops. + +__Available on ThoughtSpot Cloud instances from 26.6.0.cl onwards.__ + +a| `POST /api/rest/2.0/ai/data-source-suggestions` [beta betaBackground]^Beta^ + +xref:spotter-agent-apis.adoc#_get_data_source_suggestions[Returns a list of relevant data sources], such as Models, based on a query and thus helping users and agents choose the most appropriate data source for analytics. + +__Available on ThoughtSpot Cloud instances from 10.15.0.cl onwards__. + +a| `POST /api/rest/2.0/ai/relevant-questions/` [beta betaBackground]^Beta^ + +xref:spotter-agent-apis.adoc#_get_relevant_questions[Decomposes a user query] into relevant sub-questions. Guides users to explore data more deeply for a comprehensive analysis. + +__Available on ThoughtSpot Cloud instances from 10.13.0.cl onwards__. + + + a| `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` [.version-badge.new]#New# + + xref:spotter-agent-apis.adoc#_share_a_conversation[Shares a saved Spotter conversation] with one or more users or groups. Use `grant` and `revoke` arrays to manage access. Shared conversations are `READ_ONLY`. + + __Available on ThoughtSpot Cloud instances from 26.9.0.cl onwards.__ + + a| `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content` [.version-badge.new]#New# + + xref:spotter-agent-apis.adoc#_get_shared_content[Returns the shared content] of a Spotter conversation, including messages and associated answers. + + __Available on ThoughtSpot Cloud instances from 26.9.0.cl onwards.__ + + a| `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info` [.version-badge.new]#New# + + xref:spotter-agent-apis.adoc#_get_share_information[Returns sharing metadata] for a Spotter conversation — the list of principals it is shared with and whether the shared content is outdated. + + __Available on ThoughtSpot Cloud instances from 26.9.0.cl onwards.__ + + a| `POST /api/rest/2.0/ai/agent/converse/sse` [.version-badge.deprecated]#Deprecated# + +Legacy API endpoint for streaming responses, including tokens and visualizations, for a specific conversation context. +__Deprecated in 26.5.0.cl__. + +a| `POST /api/rest/2.0/ai/agent/{conversation_identifier}/converse` [.version-badge.deprecated]#Deprecated# + +Legacy API endpoint to send natural language queries to a conversation session with Spotter agent. + +__Deprecated in 26.5.0.cl__. +|===== + +== Create a conversation session with Spotter Agent + +The `/api/rest/2.0/ai/agent/conversation/create` API endpoint creates a new conversation session with Spotter Agent for a specific or multi-data context and returns a conversation ID. + +=== Request parameters +The request body must include the `metadata_context`. REST API clients must have at least view access to the data source objects specified in the API request to create a conversation session and use it for subsequent queries. + +[width="100%" cols="2,4"] +[options='header'] +|===== +|Form parameter| Description +|`metadata_context` a| Defines the data context for the conversation. + +* `type` + +Metadata context type. The context type is mandatory. Select one of the following values: + +** `AUTO_MODE` to allow Spotter Agent to automatically discover and select the most relevant datasets for users' queries. +** `DATA_SOURCE` to set a specific data source as the data context. You must specify `data_source_context` and data source IDs. + +To set a specific data source object, use `data_source_identifier`. + +To set multi-data context, use `data_source_identifiers`. +** `data_source` [.version-badge.deprecated]#Deprecated# + +This option is deprecated in 26.5.0.cl. ThoughtSpot recommends using the `DATA_SOURCE` with `data_source_context` and data source IDs instead. + +|`conversation_settings` a|__Optional__. Defines additional parameters for the conversation context. You can set any of the following attributes as needed: + +* `enable_contextual_change_analysis` + +__Boolean__. When enabled, Spotter analyzes how context changes over time, that is, comparing results from different queries. Enabled by default in 26.2.0.cl and later versions. +* `enable_natural_language_answer_generation` + +__Boolean__. Allows sending natural language queries to the conversation session. Enabled by default in 26.2.0.cl and later versions. +* `enable_reasoning` + +__Boolean__. Allows Spotter to use reasoning for deep analysis and precise responses. Enabled by default in 26.2.0.cl and later versions. +* `enable_save_chat` + +When set to `true`, adds the conversation to chat history. +|===== + +=== Example request + +With AUTO_MODE for metadata context:: + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/create' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "metadata_context": { + "type": "AUTO_MODE" + }, + "conversation_settings": { + "enable_save_chat": true + } +}' +---- + +For a single data source as the data context:: + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/create' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "metadata_context": { + "type": "DATA_SOURCE", + "data_source_context": { + "data_source_identifier": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + } + }, + "conversation_settings": {} +}' +---- + +For multi-data source context:: + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/create' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "metadata_context": { + "type": "DATA_SOURCE", + "data_source_context": { + "data_source_identifiers": [ + "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "b2c3d4e5-f6a7-8901-bcde-f12345678901" + ] + } + }, + "conversation_settings": { + "enable_save_chat": true + } +}' +---- + +=== API response + +If the API request is successful, the API returns the conversation ID and identifier in the response body. + +[source,JSON] +---- +{ + "conversation_id": "wwHQ5j8O8dQC", + "conversation_identifier": "wwHQ5j8O8dQC" +} +---- + +* `conversation_identifier` + +Use this for all subsequent message calls. +* `conversation_id` [.version-badge.deprecated]#Deprecated# + +Returns the same value as `conversation_identifier`. + +== Send queries to a conversation session + +To send queries to an ongoing conversation session with the Spotter agent and receive a response synchronously, use the `/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send` API endpoint. + +This API operation requires the conversation ID obtained from the conversation creation API endpoint (`/api/rest/2.0/ai/agent/conversation/create`). The user making the API request must have access to the conversation session. The API request body must include at least one message in natural language format. + +=== Request parameters + +[width="100%" cols="2,2,4"] +[options='header'] +|===== +|Parameter|Type| Description +|`conversation_identifier`|Path parameter|__String__. Required. Specify the conversation ID received from the xref:spotter-agent-apis.adoc#_create_a_conversation_session_with_spotter_agent[POST /api/rest/2.0/ai/agent/conversation/create] API call. +|`messages`|Form parameter|_Array of strings_. Required. Specify at least one query in natural language. For example, `total sales of jackets last month`. +|===== + + +//// +|`settings` |__Optional__. Defines additional parameters for the conversation context. You can set any of the following attributes as needed: + +* `enable_contextual_change_analysis` + +__Boolean__. When enabled, Spotter analyzes how the context changes over time, that is comparing results from different queries. +* `enable_natural_language_answer_generation` + +__Boolean__. Allows sending natural language queries to the conversation session. +* `enable_reasoning` + +__Boolean__. Allows Spotter to use reasoning for deep analysis and precise responses. +//// + +=== Request and response examples + +The following example sends a data comparison query to a conversation session. The conversation ID is specified in the request URL as a path parameter. + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "messages": [ + "Sales in 2025 vs 2024" + ] +}' +---- + +If the request is successful, the API returns an array of objects in the response. The messages in the API response include the following parts: + +[source,JSON] +---- +[ + { + "type": "text", + "text": "\n\nI'll compare sales between 2025 and 2024. First, let me get the dataset context.", + "metadata": {}, + "internal": {}, + "agent_context": "" + }, + { + "type": "text", + "text": "```json\n{\"dataset_name\":\"(Sample) Retail - Apparel\",\"columns\":[{\"name\":\"sales\",\"type\":\"MEASURE\"},{\"name\":\"date\",\"type\":\"ATTRIBUTE\"}]}\n```", + "metadata": {}, + "internal": {}, + "agent_context": "" + }, + { + "type": "answer", + "title": "Compare total sales for 2025 vs 2024", + "description": "", + "session_id": "842bb67a-e08e-4861-97e8-8db9538db51d", + "gen_no": 2, + "sage_query": "[sales] [date] = '2025' vs [date] = '2024'", + "tml_tokens": ["[sales]", "[date] = '2025' vs [date] = '2024'"], + "formulas": [], + "parameters": [], + "subqueries": [], + "viz_suggestion": "CAEQIBomEiQ2NjE5NzI0Yy1kMjVlLTU4MDItOWNjOC1jNDA3MWY3OWY5MzAoATIA", + "metadata": { + "output": "", + "worksheet_id": "cd252e5c-b552-49a8-821d-3eadaa049cca", + "chart_type": "KPI", + "interrupted": false, + "data_awareness_enabled": true + }, + "internal": {} + }, + { + "type": "text", + "text": "\n\nThe visualization shows year-over-year comparison. You can identify growth or decline trends.", + "metadata": {}, + "internal": {}, + "agent_context": "" + } +] +---- + +The following example sends a follow-up question to the same conversation session. + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "messages": [ + "Now break that down by product category" + ] +}' +---- + +If the request is successful, the agent returns the response for the follow-up question: + +[source,JSON] +---- +[{ + "type": "text", + "text": "I'll add product category to the comparison.", + "metadata": {}, + "internal": {}, + "agent_context": "" + }, + { + "type": "answer", + "title": "Sales by Product Category: 2025 vs 2024", + "session_id": "9abc1234-0000-0000-0000-000000000005", + "gen_no": 3, + "sage_query": "[sales] [product category] [date] = '2025' vs [date] = '2024'", + "tml_tokens": ["[sales]", "[product category]", "[date] = '2025' vs [date] = '2024'"], + "formulas": [], + "parameters": [], + "subqueries": [], + "viz_suggestion": "", + "metadata": { + "chart_type": "BAR", + "worksheet_id": "cd252e5c-b552-49a8-821d-3eadaa049cca" + }, + "internal": {} + }] +---- + +In each response, the agent returns the following information: + +* `type` + +Type of the message, such as text, answer, or error. +* `text` + +Response message generated for the query. +* `metadata` + +Additional information based on the message type. For example, answer metadata, chart type, or the data source ID. +* `tml_tokens` + +Query string broken down as TML tokens. + +In case of errors, the response returns the error details: + +[source,JSON] +---- +[{ + "type": "error", + "message": "The conversation session has expired. Please create a new conversation.", + "code": "SESSION_EXPIRED" +}] +---- + + + +//// +The following example shows the response text contents for the `answer` message type. + +[source,JSON] +---- +[ + { + "id": "r24X7D99SROD", + "type": "answer", + "group_id": "o8dQ9SAWdtrL", + "metadata": { + "sage_query": "[sales] [item type] = [item type].'jackets'", + "session_id": "b321b404-cbf1-4905-9b0c-b93ad4eedf89", + "gen_no": 1, + "transaction_id": "6874259d-13b1-478c-83cb-b3ed52628850", + "generation_number": 1, + "warning_details": null, + "ambiguous_phrases": null, + "query_intent": null, + "assumptions": "You want to see the total sales amount for jackets item type.", + "tml_phrases": [ + "[sales]", + "[item type] = [item type].'jackets'" + ], + "cached": false, + "sub_queries": null, + "title": "Net sales of Jackets", + "worksheet_id": "cd252e5c-b552-49a8-821d-3eadaa049cca" + }, + "title": "Net sales of Jackets" + } +] +---- + +The session ID and generation number serve as the data context for the Answer. You can use this information to create a new conversation session using `/api/rest/2.0/ai/agent/conversation/create`, or download the answer via the `/api/rest/2.0/report/answer` API endpoint. + + +* The tokens and TML phrases returned in the response can be used as inputs for the search data API call to get an Answer. +//// + +== Send a query to agent and get streaming responses + +To send queries to an ongoing conversation session with Spotter agent and receive streaming responses, use the `/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream` API endpoint. This API endpoint uses the SSE protocol to deliver data incrementally in real time, rather than waiting for the entire response to be generated before sending it to the client. + +The `/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream` API can be used as an integrated tool for real-time streaming of conversational interactions between agents and the ThoughtSpot backend. + +=== Request parameters + +[width="100%" cols="2,4"] +[options='header'] +|===== +|Parameter| Description +|`conversation_identifier` |__String__. Specify the conversation ID received from the xref:spotter-agent-apis.adoc#_create_a_conversation_session_with_spotter_agent[POST /api/rest/2.0/ai/agent/conversation/create] API call. +|`messages`|_Array of strings_. Include at least one natural language query. For example, `Sales data for Jackets`, `Top performing products in the west coast`. +|===== + +=== Example request + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "conversation_identifier": "h2I_pTGaRQof", + "messages": [ + "Net sales of Jackets" + ] +}' +---- + +=== API response + +If the API request is successful, the response includes a stream of events, each containing a partial or complete message from the AI agent, rather than a single JSON object. + +Each event is a simple text-based message in a specific format, `data: \n\n`; `\n\n` means that each message sent from the server to the client is prefixed with the `data:` keyword, followed by the actual payload (``), and ends with two newline characters (`\n\n`). + +The API uses this format so that the clients can reconstruct the AI-generated response as it streams in, chunk by chunk, and show the responses in real-time. In agentic workflows, the receiving client or agent listens to the SSE stream, parses each event, and assembles the full response for its users. + +==== Example response +If the request is valid, the API returns SSE streams. Each line has the form `data: [{"type": "...", ...}]`, a JSON array of event objects. + +[source,JSON] +---- +data: [{"type":"ack","node_id":"aGxzcFVrtom8"}] + +data: [{"type":"conv_title","title":"Sales 2025 vs 2024","conv_id":"-XIi04l5rrof"}] + +data: [{"type":"notification","group_id":"cDEsAQbSnd3J","metadata":{"type":"thinking","tool_title":"Analyzing Sales Performance: 2025 vs 2024"},"code":"TOOL_CALL_NOTIFICATION"}] + +data: [{"id":"mNAdvy-NK2l6","type":"text-chunk","group_id":"cDEsAQbSnd3J","metadata":{"format":"markdown","type":"thinking"},"content":"\n\nI need to compare sales performance between 2025 and 2024."}] + +data: [{"type":"notification","group_id":"m1MTvttEUa7o","code":"nls_start"}] + +data: [{"id":"hxWMDP-pgR3B","type":"answer","group_id":"m1MTvttEUa7o","metadata":{"sage_query":"[sales] [date] = '2025' vs [date] = '2024'","session_id":"431adcf9-1328-4d8c-81a1-0faa7fa37ba6","title":"Compare sales for 2025 vs 2024"},"title":"Compare sales for 2025 vs 2024"}] + +data: [{"type":"notification","code":"FINAL_RESPONSE_NOTIFICATION"}] +---- +For the complete response in one payload, use the xref:spotter-agent-apis.adoc#_send_queries_to_a_conversation_session[`/send` endpoint] instead. + +//// +[source,] +---- +data: [{"type": "ack", "node_id": "BRxCtJ-aGt8l"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": "I"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " understand"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " you're"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " interested"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " in"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " the"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " net"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " sales"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " of"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " Jackets"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": "."}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " I'll"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " retrieve"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " the"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " relevant"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " data"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " for"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " you"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": "."}] + +data: [{"type": "notification", "group_id": "o8dQ9SAWdtrL", "metadata": {"title": "Net sales of Jackets"}, "code": "nls_start"}] + +data: [{"type": "notification", "group_id": "o8dQ9SAWdtrL", "code": "QH", "message": "Fetching Worksheet Data"}] + +data: [{"type": "notification", "group_id": "o8dQ9SAWdtrL", "code": "TML_GEN", "message": "Translating your query with the Reasoning Engine"}] + +data: [{"type": "notification", "group_id": "o8dQ9SAWdtrL", "code": "ANSWER_GEN", "message": "Verifying results with the Trust Layer"}] + +data: [{"id": "r24X7D99SROD", "type": "answer", "group_id": "o8dQ9SAWdtrL", "metadata": {"sage_query": "[sales] [item type] = [item type].'jackets'", "session_id": "b321b404-cbf1-4905-9b0c-b93ad4eedf89", "gen_no": 1, "transaction_id": "6874259d-13b1-478c-83cb-b3ed52628850", "generation_number": 1, "warning_details": null, "ambiguous_phrases": null, "query_intent": null, "assumptions": "You want to see the total sales amount for jackets item type.", "tml_phrases": ["[sales]", "[item type] = [item type].'jackets'"], "cached": false, "sub_queries": null, "title": "Net sales of Jackets", "worksheet_id": "cd252e5c-b552-49a8-821d-3eadaa049cca"}, "title": "Net sales of Jackets"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "The"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " net"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " sales"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " for"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " Jackets"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " have"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " been"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " visual"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "ized"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " for"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " you"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "."}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " This"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " analysis"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " specifically"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " filtered"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " for"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " the"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " item"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " type"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "jackets"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "\""}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " and"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " calculated"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " the"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " total"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " sales"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " amount"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " associated"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " with"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " those"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " products"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ".\n\n"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "**"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "Summary"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " &"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " Insights"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ":"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "**\n"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "-"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " The"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " visualization"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " shows"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " the"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " total"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " net"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " sales"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " for"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " all"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " jacket"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " transactions"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " in"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " your"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " apparel"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " dataset"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ".\n"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "-"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " The"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " calculation"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " uses"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " only"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " sales"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " amounts"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " where"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " the"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " item"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " type"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " is"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " \""}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "J"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "ackets"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ".\"\n"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "-"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " This"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " information"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " is"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " useful"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " for"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " understanding"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " the"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " revenue"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " contribution"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " of"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " jackets"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " within"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " your"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " product"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " mix"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ".\n\n"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "If"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " you'd"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " like"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " to"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " see"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " a"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " breakdown"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " by"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " region"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ","}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " state"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ","}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " time"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " period"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ","}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " or"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " compare"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " jacket"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " sales"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " to"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " other"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " product"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " types"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ","}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " please"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " let"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " me"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " know"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "!"}] +---- +//// + +==== SSE event types +The SSE event types streamed in the API response include: + +* `ack` + +Confirms receipt of the request. For example, the type in the first message `data: [{"type": "ack", "node_id": "BRxCtJ-aGt8l"}]`, which indicates that the server has received the client's request and is acknowledging it. +* `conv_title` + +A conversation title (`title`, `conv_id`). +* `notification` + +Progress or status update (`group_id`, `metadata`, `code`). For example, `TOOL_CALL_NOTIFICATION`, `nls_start`, `FINAL_RESPONSE_NOTIFICATION`. +* `type` + +Type can be `thinking`, `text`. +* `text` + +Complete text block in markdown format. +* `text-chunk` + +Text fragments in incremental streaming, often in markdown (`id`, `group_id`, `metadata` with `format`) +* `content` + +The actual text content sent incrementally. For example, `"I"`, `"understand"`, `"you're"`, `"interested"`, `"in"`, `"the"`, `"net"`, `"sales"`, and so on. +* `text` + +Full text block with same structure as text-chunk. +* `answer` + +Structured answer with metadata (`id`, `group_id`, `metadata` with `sage_query`, `session_id`, `title` and more) +* `error` + +In case of failures. +* `*-interrupt` + +If the generation was stopped mid-stream. +* `group_id` + +Groups related chunks together. + +For more information and examples, see xref:spotter-agent-apis.adoc#_sse_event_payload_reference[SSE event payload reference]. + +=== Thinking versus output events +Spotter responses have two phases: + +* A *thinking phase*, where the AI reasons through the query and calls internal tools, followed by an *output phase* containing the final response delivered to the user. + + +Events in the thinking phase carry `"metadata": { "type": "thinking" }`. All other events are final output. + +Every event includes a `group_id`. Events sharing the same `group_id` belong together. During the thinking phase, each tool call gets its own `group_id`. A `FINAL_RESPONSE_NOTIFICATION` notification marks the boundary between the thinking and output phases. + +[listing] +---- +THINKING PHASE +─────────────────────────────────────────────────────────── +ack + +┌─ group_id: g1 ── Tool Call 1 ("Searching data") ─────────┐ +│ notification (thinking, TOOL_CALL_NOTIFICATION) │ +│ text-chunk (thinking) │ +│ answer (thinking) │ +└──────────────────────────────────────────────────────────┘ + +┌─ group_id: g2 ── Tool Call 2 ("Running code") ───────────┐ +│ notification (thinking, TOOL_CALL_NOTIFICATION) │ +│ text-chunk (thinking) │ +│ text-chunk (thinking) │ +└──────────────────────────────────────────────────────────┘ + +notification (FINAL_RESPONSE_NOTIFICATION) ←── boundary +──────────────────────────────────────────────────────────── + +OUTPUT PHASE +──────────────────────────────────────────────────────────── +┌─ group_id: g3 ────────────────────────────────────────────┐ +│ text "Here are the results:" │ +│ answer (final visualization) │ +└───────────────────────────────────────────────────────────┘ +[stream closes] +---- + +==== Notification codes reference + +[width="100%" cols="2,4"] +[options='header'] +|===== +|Code| When it appears +|`QH`|Query handling started +|`TML_GEN` / `TML_GEN_RETRY`|Generating or retrying TML +|`ANSWER_GEN`|Generating an answer +|`IDENTIFYING_ATTRIBUTES`|Identifying data attributes +|`PERFORMING_CHANGE_ANALYSIS`|Running change analysis +|`PERFORMING_FORECASTING_ANALYSIS`|Running forecasting +|`SUMMARIZING_RESULTS`|Summarizing results +|`TOOL_CALL_NOTIFICATION`|Tool invocation (during thinking phase) +|`FINAL_RESPONSE_NOTIFICATION`|Marks the transition from thinking to output +|`search_datasets_start` / `search_datasets_end`|Data source discovery in progress or complete +|`approval_required`|An external tool requires user permission before proceeding +|===== + +=== SSE event payload reference + +==== ack + +[source,JSON] +---- +data: { + "type": "ack", + "group_id": "a1b2c3", + "id": "evt-001", + "node_id": "resp-node-abc" +} +---- + +==== notification (thinking — tool call) + +[source,JSON] +---- +data: { + "type": "notification", + "group_id": "g1", + "id": "evt-002", + "code": "TOOL_CALL_NOTIFICATION", + "message": "Searching for relevant data", + "metadata": { + "type": "thinking", + "tool_title": "Searching sales data", + "tool_code": "RUNNING_CODE_EXECUTION", + "tool_name": "code_interpreter" + } +} +---- + +==== notification (thinking - external tool with MCP integration) + +[source,JSON] +---- +data: { + "type": "notification", + "group_id": "g2", + "id": "evt-003", + "code": "TOOL_CALL_NOTIFICATION", + "message": "Querying Salesforce", + "metadata": { + "type": "thinking", + "tool_title": "Salesforce: Get Opportunities", + "tool_name": "get_opportunities", + "integration_id": "int-sf-123", + "integration_name": "Salesforce" + } +} +---- + +==== notification (approval required) +Sent when an external MCP tool requires explicit user permission before proceeding. Your application should prompt the user to approve or deny the action before continuing. + +[source,JSON] +---- +data: { + "type": "notification", + "group_id": "g2", + "id": "evt-005", + "code": "approval_required", + "metadata": { + "request_id": "perm-req-789", + "integration_id": "int-sf-123", + "integration_name": "Salesforce", + "tool_name": "get_opportunities", + "annotated_title": "Access Salesforce Opportunities" + } +} +---- + +==== notification (FINAL_RESPONSE_NOTIFICATION) + +[source,JSON] +---- +data: { + "type": "notification", + "group_id": "g1", + "id": "evt-004", + "code": "FINAL_RESPONSE_NOTIFICATION", + "message": "" +} +---- + +==== text + +[source,JSON] +---- +data: { + "type": "text", + "group_id": "g3", + "id": "evt-007", + "content": "Here is the total revenue breakdown by region for Q4 2025:\n\n- **North America:** $4.2M\n- **EMEA:** $2.8M\n- **APAC:** $1.5M" +} +---- + +==== text-chunk +Multiple chunks sharing the same `id` should be appended together to reconstruct the full text item. + +[source,JSON] +---- +data: { "type": "text-chunk", "group_id": "g3", "id": "evt-009", "content": "Based on the analysis, " } +data: { "type": "text-chunk", "group_id": "g3", "id": "evt-009", "content": "revenue grew 12% quarter-over-quarter." } +---- + +==== answer +When an `answer` event is received, the `session_id` and `gen_no` fields are returned. You can export the visualization data using the Export Answer Report API to process the results. This allows users to download the answer as a PDF, PNG, CSV, or XLSX file. + +[source,JSON] +---- +data: { + "type": "answer", + "group_id": "g3", + "id": "evt-010", + "title": "Revenue by Region Q4 2025", + "metadata": { + "session_id": "sess-abc-123", + "gen_no": 1, + "transaction_id": "txn-456", + "worksheet_id": "ws-def-789", + "cached": false, + "is_hidden": false + } +} +---- + +==== search_datasets +Emitted as a start/end pair during Auto mode data source discovery. + + +[source,JSON] +---- +data: { "type": "search_datasets", "group_id": "g0", "id": "evt-012", "code": "search_datasets_start", "metadata": {} } + +data: { + "type": "search_datasets", + "group_id": "g0", + "id": "evt-013", + "code": "search_datasets_end", + "metadata": { + "data_sources": [ + { "worksheet_id": "ws-1", "worksheet_name": "Sales Data", "confidence": "high", "reasoning": "Contains revenue columns" }, + { "worksheet_id": "ws-2", "worksheet_name": "Marketing Data", "confidence": "low", "reasoning": "No revenue columns" } + ], + "auto_selected": { "worksheet_id": "ws-1", "worksheet_name": "Sales Data", "confidence": "high", "reasoning": "Best match" } + } +} +---- +==== file + +[source,JSON] +---- +data: { + "type": "file", + "group_id": "g3", + "id": "evt-014", + "files": [ + { "ts_file_id": "file-abc-001", "display_name": "quarterly_report.csv", "file_type": "csv", "created_at": "2025-11-15T10:30:00Z" }, + { "ts_file_id": "file-abc-002", "display_name": "chart.png", "file_type": "png", "created_at": "2025-11-15T10:30:01Z" } + ], + "metadata": { "conv_id": "conv-123" } +} +---- +==== conv_title + +[source,JSON] +---- +data: { + "type": "conv_title", + "group_id": "g0", + "id": "evt-015", + "title": "Revenue Analysis Q4 2025", + "conv_id": "conv-123" +} +---- + +==== error + +[source,JSON] +---- +data: { + "type": "error", + "group_id": "g3", + "id": "evt-016", + "code": "RATE_LIMIT_EXCEEDED", + "message": "Too many requests", + "display_message": "You've exceeded the rate limit. Please try again in a few minutes." +} +---- +==== agent-interrupt + +[source,JSON] +---- +Sent when generation is stopped mid-stream. +data: { + "type": "notification", + "group_id": "g3", + "id": "evt-017", + "code": "agent-interrupt", + "message": "Generation stopped" +} +---- + +[#_stop_an_in_progress_agent_response] +== Stop an in-progress agent response + +The `/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response` API endpoint stops a Spotter agent response that is currently in progress for a given conversation session. + +Use this endpoint when you want to cancel a long-running Spotter response before it completes. The conversation session remains active after you stop a response, so you can send a new query to the same session immediately. + +=== Request parameters + +[width="100%", cols="2,2,4"] +[options='header'] +|===== +|Parameter|Type| Description +|`conversation_identifier`|Path parameter|__String__. Required. The identifier of the active conversation session. Use the value returned by the xref:spotter-agent-apis.adoc#_create_a_conversation_session_with_spotter_agent[create conversation] API endpoint. +|===== + +This endpoint does not require a request body. + +=== Example request + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' +---- + +=== Example response + +If the API request is successful, ThoughtSpot stops the in-progress response and returns a 204 response code. + +If the conversation session is not found or has expired, the API returns an error: + +[source,JSON] +---- +{ + "error_code": "CONVERSATION_NOT_FOUND", + "message": "The specified conversation session does not exist or has expired." +} +---- + +[#process_results] +== Process results generated from a conversation session +To export or download the Answer data generated by the Spotter APIs, use the xref:data-report-v2-api.adoc#exportSpotterData[Answer report] API. + +The `session_id` and `gen_no` values from the `answer` event metadata are required to identify the answer to export. + +NOTE: Requires at least view access to the Answer. + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \ + -H 'Authorization: Bearer {Bearer_token}' \ + -H 'Accept: application/octet-stream' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "session_identifier": "sess-abc-123", + "generation_number": 1, + "file_format": "CSV" +}' +---- +The `file_format` parameter accepts `PDF`, `PNG`, `CSV`, or `XLSX`. + +[NOTE] +==== +Using tokens generated by the Spotter API in a xref:data-report-v2-api.adoc#_search_data_api[Search Data API] request can return invalid column errors, because these tokens may reference formulas or columns not present in the data model. Instead, use the xref:data-report-v2-api.adoc#exportSpotterData[Answer report] API and include the session ID and generation number obtained from the Spotter API in your API request to retrieve the data. +==== + + +== Data literacy and query assistance +The query assistance APIs help users find the appropriate dataset for a given query string, suggest what questions can be asked, and return example questions. These APIs are specifically designed to improve data literacy for users who may not be familiar with the underlying data, making it easier for them to explore and analyze data effectively. + +=== Get data source suggestions + +The `POST /api/rest/2.0/ai/data-source-suggestions` API provides relevant data source recommendations for a user-submitted natural language query. To use this API, you must have at least view access to the underlying metadata object referenced in the response. + +==== Request parameters + +[width="100%" cols="2,4"] +[options='header'] +|==== +|Parameter| Description +|`metadata_context` a| Required. Specify one of the following attributes to set the metadata context: + +* `data_source_identifiers` + +__Array of strings__. IDs of the data source object such as Models. +* `answer_identifiers` + +__Array of strings__. GUIDs of the Answer objects that you want to use as metadata. +* `conversation_identifier` + +__String__. ID of the conversation session. +* `liveboard_identifiers` + +__Array of strings__. GUIDs of the Liveboards that you want to use as metadata. + +| `query` |__String__. Required parameter. Specify the query string that needs to be decomposed into smaller, analytical sub-questions. +|`limit_relevant_questions` + +__Optional__ | __Integer__. Sets a limit on the number of sub-questions to return in the response. Default is 5. +|`bypass_cache` + +__Optional__| __Boolean__. When set to `true`, disables cache and forces fresh computation. +|`ai_context` + +__Optional__. a| Additional context to guide the response. Define the following attributes as needed: +|==== + +==== Example request + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/data-source-suggestions' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "metadata_context": { + "data_source_identifiers": [ + "cd252e5c-b552-49a8-821d-3eadaa049cca" + ] + }, + "query": "Net sales of Jackets in west coast", + "limit_relevant_questions": 3 +}' +---- + +==== API response +If the API request is successful, ThoughtSpot returns a ranked list of data sources, each annotated with relevant reasoning. + +[source,JSON] +---- +{ + "relevant_questions": [ + { + "query": "What is the trend of sales by type over time?", + "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", + "data_source_name": "(Sample) Retail - Apparel" + }, + { + "query": "Sales by item", + "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", + "data_source_name": "(Sample) Retail - Apparel" + }, + { + "query": "Sales across regions", + "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", + "data_source_name": "(Sample) Retail - Apparel" + } + ] +} +---- + +The returned results include metadata such as: + +* `confidence` + +A float indicating the Model's confidence in the relevance of each recommendation. +* `details` + +The data source ID, name, and description for each recommended data source. +* `reasoning` + +Reason provided by the LLM to explain why each data source was recommended. + +=== Get relevant questions + +The `/api/rest/2.0/ai/relevant-questions/` API endpoint breaks down a user-submitted query into relevant sub-questions. It accepts the original query and optional additional context, then generates a set of related questions to help users explore their data comprehensively. + +During agentic interactions, this API can be used as an integrated tool to decompose user queries and suggest relevant questions for a specific data context. REST clients can also call this API directly to fetch relevant questions via a `POST` request. + +==== Request parameters + +[width="100%" cols="2,4"] +[options='header'] +|===== +|Parameter| Description +|`metadata_context` a| Required. Specify one of the following attributes to set the metadata context: + +* `data_source_identifiers` + +__Array of strings__. IDs of the data source object such as Models. +* `answer_identifiers` + +__Array of strings__. GUIDs of the Answer objects that you want to use as metadata. +* `conversation_identifier` + +__String__. ID of the conversation session. +* `liveboard_identifiers` + +__Array of strings__. GUIDs of the Liveboards that you want to use as metadata. + +| `query` |__String__. Required parameter. Specify the query string that needs to be decomposed into smaller, analytical sub-questions. +|`limit_relevant_questions` + +__Optional__ | __Integer__. Sets a limit on the number of sub-questions to return in the response. Default is 5. +|`bypass_cache` + +__Optional__| __Boolean__. When set to `true`, disables cache and forces fresh computation. +|`ai_context` + +__Optional__. a| Additional context to guide the response. Define the following attributes as needed: + +* `instructions` + +__Array of strings__. Custom user instructions to influence how the AI interprets and processes the query. +* `content` + +__Array of strings__. Additional input such as raw text or CSV-formatted data to enhance context and answer quality. +|===== + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/relevant-questions/' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "metadata_context": { + "data_source_identifiers": [ + "cd252e5c-b552-49a8-821d-3eadaa049cca" + ] + }, + "query": "Net sales of Jackets in west coast", + "limit_relevant_questions": 3 +}' +---- + +==== Example response +If the request is successful, the API returns a set of questions related to the query and metadata context in the `relevant_questions` array. Each object in the `relevant_questions` array contains the following fields: + +* `query` + +A string containing the natural language (NL) sub-question. +* `data_source_identifier` + +GUID of the data source object. +* `data_source_name` + +Name of the associated data source object. + +[source,JSON] +---- +{ + "relevant_questions": [ + { + "query": "What is the trend of sales by type over time?", + "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", + "data_source_name": "(Sample) Retail - Apparel" + }, + { + "query": "Sales by item", + "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", + "data_source_name": "(Sample) Retail - Apparel" + }, + { + "query": "Sales across regions", + "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", + "data_source_name": "(Sample) Retail - Apparel" + } + ] +} +---- + +== Additional resources + +* Visit the +++REST API v2.0 Playground+++ to view the API endpoints and verify the request and response workflows. +* For information about MCP tools, see xref:mcp-integration.adoc[MCP server integration]. + + [#_sharing_spotter_conversations] + == Sharing Spotter conversations + + // SOURCE: SCAL-306173 (aug.26.mt) + // SOURCE: prism/src/public-apis/nl-to-answer.graphql (master) + + ThoughtSpot provides REST API v2.0 endpoints to share saved Spotter agent conversations with other users or groups. Shared conversations are always `READ_ONLY` — recipients can view conversation messages and associated answers but cannot send new queries or modify the conversation. + + === Supported endpoints + + [width="100%" cols="1"] + |===== + a| `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` [.version-badge.new]#New# + + xref:spotter-agent-apis.adoc#_share_a_conversation[Shares a saved Spotter conversation] with one or more users or groups. + + __Available on ThoughtSpot Cloud instances from 26.9.0.cl onwards.__ + + a| `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content` [.version-badge.new]#New# + + xref:spotter-agent-apis.adoc#_get_shared_content[Returns the shared content] of a Spotter conversation, including messages and associated answers. + + __Available on ThoughtSpot Cloud instances from 26.9.0.cl onwards.__ + + a| `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info` [.version-badge.new]#New# + + xref:spotter-agent-apis.adoc#_get_share_information[Returns sharing metadata] for a Spotter conversation — the list of principals it is shared with. + + __Available on ThoughtSpot Cloud instances from 26.9.0.cl onwards.__ + |===== + + [#_share_a_conversation] + === Share a conversation + + Use `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` to share a saved Spotter conversation with one or more principals. + + ==== Path parameters + + [width="100%" cols="2,4"] + [options="header"] + |===== + | Parameter | Description + | `conversation_identifier` | The GUID of the saved Spotter conversation to share. + |===== + + ==== Request body parameters + + [width="100%" cols="2,1,4"] + [options="header"] + |===== + | Parameter | Required | Description + | `grant` | No | Array of principal identifiers to grant access. Each entry is a `user_identifier` (username or GUID) or `group_identifier` (group name or GUID). All shared access is `READ_ONLY`. + | `revoke` | No | Array of principal identifiers to revoke access from. + | `refresh_shared_content` | No | Boolean. When `true`, regenerates the shared content snapshot. Default: `false`. + | `notify_on_share` | No | Boolean. When `true`, sends an in-app notification to principals receiving access. Default: `true`. Available from 26.10.0.cl. + |===== + + ==== Example request + + [source,cURL] + ---- + curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "grant": [ + {"user_identifier": "user@example.com"}, + {"group_identifier": "analysts-group"} + ], + "revoke": [], + "refresh_shared_content": false + }' + ---- + + [#_get_shared_content] + === Get shared content + + Use `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content` to retrieve the content of a shared Spotter conversation. + + ==== Path parameters + + [width="100%" cols="2,4"] + [options="header"] + |===== + | Parameter | Description + | `conversation_identifier` | The GUID of the shared Spotter conversation. + |===== + + ==== Response fields + + [width="100%" cols="2,4"] + [options="header"] + |===== + | Field | Description + | `conversation_id` | GUID of the original conversation. + | `shared_conversation_id` | GUID of the shared conversation snapshot. + | `messages` | Array of conversation messages included in the shared snapshot. + | `data_sources` | Array of data source identifiers used in the conversation. + | `code_execution_files` | Array of files generated by code execution steps, if any. + |===== + + ==== Example request + + [source,cURL] + ---- + curl -X GET \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/json' + ---- + + [#_get_share_information] + === Get share information + + Use `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info` to retrieve sharing metadata for a Spotter conversation. + + ==== Path parameters + + [width="100%" cols="2,4"] + [options="header"] + |===== + | Parameter | Description + | `conversation_identifier` | The GUID of the Spotter conversation. + |===== + + ==== Response fields + + [width="100%" cols="2,4"] + [options="header"] + |===== + | Field | Description + | `is_shared_content_outdated` | Boolean. `true` if the shared content snapshot is stale. Use the share endpoint with `refresh_shared_content: true` to regenerate. + | `principals` | Array of principal objects the conversation is shared with. Each entry includes the principal identifier and their access level (always `READ_ONLY`). + |===== + + ==== Example request + + [source,cURL] + ---- + curl -X GET \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/json' + ---- + \ No newline at end of file From 02a807bee3496fcd38d691fc52a5b3cc2f788a43 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 17 Aug 2026 10:30:51 +0530 Subject: [PATCH 19/32] =?UTF-8?q?docs:=20add=20conversation=20sharing=20AP?= =?UTF-8?q?Is=20to=20spotter-agent-apis.adoc=20=E2=80=94=20share,=20get-sh?= =?UTF-8?q?ared-content,=20get-share-info=20(SCAL-306173,=20aug.26.mt)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit From 885e4574b88e7344d2d70e2a00ae7ed08b0df4b0 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 17 Aug 2026 10:34:23 +0530 Subject: [PATCH 20/32] docs: add 26.9.0.cl REST API changelog section (SCAL-306069, SCAL-309867, SCAL-306173, SCAL-320899, SCAL-317550, SCAL-307284, SCAL-312738, SCAL-277656) --- modules/ROOT/pages/rest-apiv2-changelog.adoc | 1389 ++++++++++++++++-- 1 file changed, 1271 insertions(+), 118 deletions(-) diff --git a/modules/ROOT/pages/rest-apiv2-changelog.adoc b/modules/ROOT/pages/rest-apiv2-changelog.adoc index 91c73b2c1..b5325b191 100644 --- a/modules/ROOT/pages/rest-apiv2-changelog.adoc +++ b/modules/ROOT/pages/rest-apiv2-changelog.adoc @@ -10,124 +10,125 @@ This changelog lists the features and enhancements introduced in REST API v2.0. == Version 26.9.0.cl, September 2026 -=== Answer Export API enhancements — General Availability + === Answer Export API enhancements — General Availability -// SOURCE: SCAL-306069 + // SOURCE: SCAL-306069 -The `POST /api/rest/2.0/report/answer` endpoint is generally available from 26.9.0.cl. The `isAnswerExportV2Enabled` flag is enabled by default on all ThoughtSpot Cloud instances. The following enhancements are included in this release: + The `POST /api/rest/2.0/report/answer` endpoint is generally available from 26.9.0.cl. The `isAnswerExportV2Enabled` flag is enabled by default on all ThoughtSpot Cloud instances. The following enhancements are included in this release: -Pinned Answer export:: -Pass `viz_guid` to export a pinned Answer (a visualization on a Liveboard) directly. Liveboard-level filters and runtime overrides are applied automatically. The `metadata_identifier` must be the parent Liveboard GUID or name. + Pinned Answer export:: + Pass `viz_guid` to export a pinned Answer (a visualization on a Liveboard) directly. Liveboard-level filters and runtime overrides are applied automatically. The `metadata_identifier` must be the parent Liveboard GUID or name. -Personalized View support:: -Pass `personalised_view_identifier` to export data from a specific Personalized View of a Liveboard. + Personalized View support:: + Pass `personalised_view_identifier` to export data from a specific Personalized View of a Liveboard. -Spotter Answer export:: -XLSX and PDF export formats are now supported for Spotter-generated (ad hoc) Answers, in addition to CSV and PNG. + Spotter Answer export:: + XLSX and PDF export formats are now supported for Spotter-generated (ad hoc) Answers, in addition to CSV and PNG. -Custom PNG dimensions:: -Use `x_resolution` and `y_resolution` parameters to specify custom pixel dimensions for PNG exports. Accepted range: 600–3840 px per axis. Default: 2254 × 1588. + Custom PNG dimensions:: + Use `x_resolution` and `y_resolution` parameters to specify custom pixel dimensions for PNG exports. Accepted range: 600–3840 px per axis. Default: 2254 × 1588. -Display scaling:: -Use `scaling_factor` (range: 80–400) to adjust the relative size of chart elements in a PNG export without cropping the image. + Display scaling:: + Use `scaling_factor` (range: 80–400) to adjust the relative size of chart elements in a PNG export without cropping the image. -Dynamic file naming:: -Exported files are automatically named based on the Answer title with the correct file extension (`.png`, `.pdf`, `.csv`, `.xlsx`) appended. + Dynamic file naming:: + Exported files are automatically named based on the Answer title with the correct file extension (`.png`, `.pdf`, `.csv`, `.xlsx`) appended. -For more information, see xref:data-report-v2-api.adoc#answer-report[Answer Report API]. + For more information, see xref:data-report-v2-api.adoc#answer-report[Answer Report API]. -=== Snowflake Semantic View integration APIs + === Snowflake Semantic View integration APIs -// SOURCE: SCAL-309867 + // SOURCE: SCAL-309867 -ThoughtSpot 26.9.0.cl introduces REST API v2.0 endpoints for managing Snowflake Semantic View integrations programmatically. These APIs allow administrators and data managers to create, search, import, and delete semantic integration configurations without using the ThoughtSpot UI. + ThoughtSpot 26.9.0.cl introduces REST API v2.0 endpoints for managing Snowflake Semantic View integrations programmatically. These APIs allow administrators and data managers to create, search, import, and delete semantic integration configurations without using the ThoughtSpot UI. -[width="100%"] -[options="header"] -|===== -| Method | Endpoint | Description -| `POST` | `/api/rest/2.0/semantic-integrations/create` | Creates a new semantic integration by reading a Snowflake Semantic View and generating a ThoughtSpot data model. -| `POST` | `/api/rest/2.0/semantic-integrations/search` | Returns a list of semantic integrations matching the specified filter criteria. -| `POST` | `/api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/import` | Re-imports semantic updates from Snowflake and refreshes the associated ThoughtSpot data model. -| `POST` | `/api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/delete` | Deletes a semantic integration and its generated ThoughtSpot data model. -|===== + [width="100%"] + [options="header"] + |===== + | Method | Endpoint | Description + | `POST` | `/api/rest/2.0/semantic-integrations/create` | Creates a new semantic integration by reading a Snowflake Semantic View and generating a ThoughtSpot data model. + | `POST` | `/api/rest/2.0/semantic-integrations/search` | Returns a list of semantic integrations matching the specified filter criteria. + | `POST` | `/api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/import` | Re-imports semantic updates from Snowflake and refreshes the associated ThoughtSpot data model. + | `POST` | `/api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/delete` | Deletes a semantic integration and its generated ThoughtSpot data model. + |===== -Required privilege: `ADMINISTRATION` or `DATAMANAGEMENT`. If RBAC is enabled, the user also requires the `CAN_CREATE_OR_EDIT_CONNECTIONS` privilege and permission to manage data models. + Required privilege: `ADMINISTRATION` or `DATAMANAGEMENT`. If RBAC is enabled, the user also requires the `CAN_CREATE_OR_EDIT_CONNECTIONS` privilege and permission to manage data models. -For more information, see xref:semantic-integrations-api.adoc[Snowflake Semantic View integration APIs]. + For more information, see xref:semantic-integrations-api.adoc[Snowflake Semantic View integration APIs]. -=== Spotter Memory — General Availability + === Spotter Memory — General Availability -// SOURCE: SCAL-306173 + // SOURCE: SCAL-306173 -The Spotter Memory feature is generally available from 26.9.0.cl. The memory APIs introduced in 26.8.0.cl (`POST /api/rest/2.0/ai/memory/import` and `POST /api/rest/2.0/ai/memory/export`) are enabled by default on all ThoughtSpot Cloud instances. Administrators can manage and audit Spotter training data programmatically without enabling a feature flag. + The Spotter Memory feature is generally available from 26.9.0.cl. The memory APIs introduced in 26.8.0.cl (`POST /api/rest/2.0/ai/memory/import` and `POST /api/rest/2.0/ai/memory/export`) are enabled by default on all ThoughtSpot Cloud instances. Administrators can manage and audit Spotter training data programmatically without enabling a feature flag. -For more information, see xref:spotter-ai-memory-api.adoc[Spotter memory APIs]. + For more information, see xref:spotter-ai-memory-api.adoc[Spotter memory APIs]. -=== Spotter Agent — Conversation sharing APIs + === Spotter Agent — Conversation sharing APIs -// SOURCE: SCAL-306173 (aug.26.mt) + // SOURCE: SCAL-306173 (aug.26.mt) -ThoughtSpot 26.9.0.cl introduces REST API v2.0 endpoints for sharing saved Spotter agent conversations with other users or groups. Shared conversations are always `READ_ONLY`. + ThoughtSpot 26.9.0.cl introduces REST API v2.0 endpoints for sharing saved Spotter agent conversations with other users or groups. Shared conversations are always `READ_ONLY`. -[width="100%"] -[options="header"] -|===== -| Method | Endpoint | Description -| `POST` | `/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` | Shares a saved Spotter conversation with specified principals. Use `grant` and `revoke` arrays to manage access. -| `GET` | `/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content` | Returns the content of a shared Spotter conversation — messages, data sources, and answer details. -| `GET` | `/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info` | Returns sharing metadata — the list of principals the conversation is shared with and their access levels. The `is_shared_content_outdated` flag indicates if the shared snapshot is stale. -|===== + [width="100%"] + [options="header"] + |===== + | Method | Endpoint | Description + | `POST` | `/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` | Shares a saved Spotter conversation with specified principals. Use `grant` and `revoke` arrays to manage access. + | `GET` | `/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content` | Returns the content of a shared Spotter conversation — messages, data sources, and answer details. + | `GET` | `/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info` | Returns sharing metadata — the list of principals the conversation is shared with and their access levels. The `is_shared_content_outdated` flag indicates if the shared snapshot is stale. + |===== -For more information, see xref:spotter-agent-apis.adoc#_sharing_spotter_conversations[Sharing Spotter conversations]. + For more information, see xref:spotter-agent-apis.adoc#_sharing_spotter_conversations[Sharing Spotter conversations]. -=== KPI Sparkline setting in metadata search response + === KPI Sparkline setting in metadata search response -// SOURCE: SCAL-320899 + // SOURCE: SCAL-320899 -The `POST /api/rest/2.0/metadata/search` API response now includes the `isSparklineEnabled` field in the `AnswerSpecHeader` object for KPI chart type answers. This boolean field indicates whether the sparkline trend line is enabled for the KPI visualization. + The `POST /api/rest/2.0/metadata/search` API response now includes the `isSparklineEnabled` field in the `AnswerSpecHeader` object for KPI chart type answers. This boolean field indicates whether the sparkline trend line is enabled for the KPI visualization. -* `true` — the sparkline trend line is enabled. -* `false` — the sparkline is disabled. -* Absent — the answer was saved before this release and has not been re-saved. Treat an absent field as unknown, not as `false`. + * `true` — the sparkline trend line is enabled. + * `false` — the sparkline is disabled. + * Absent — the answer was saved before this release and has not been re-saved. Treat an absent field as unknown, not as `false`. -=== Outline Encoding — BYOC Muze + === Outline Encoding — BYOC Muze -// SOURCE: SCAL-317550 + // SOURCE: SCAL-317550 -ThoughtSpot 26.9.0.cl promotes mark outline color to a first-class data-driven encoding channel in the Muze charting library (BYOC). Developers building custom charts with Muze can now bind a data field to `encoding.outline` to produce ordinal color palettes (for categorical fields) or continuous gradient ramps (for measures), with full legend rendering and legend-to-mark interaction. + ThoughtSpot 26.9.0.cl promotes mark outline color to a first-class data-driven encoding channel in the Muze charting library (BYOC). Developers building custom charts with Muze can now bind a data field to `encoding.outline` to produce ordinal color palettes (for categorical fields) or continuous gradient ramps (for measures), with full legend rendering and legend-to-mark interaction. -The static `outline` config (`{ fill, color, width, dash }`) remains fully backward compatible. Supported mark types: Point, Bar, Arc. + The static `outline` config (`{ fill, color, width, dash }`) remains fully backward compatible. Supported mark types: Point, Bar, Arc. -=== Personalized Views TML portability — General Availability + === Personalized Views TML portability — General Availability -// SOURCE: SCAL-307284 + // SOURCE: SCAL-307284 -The Personalized Views TML portability feature introduced as Early Access in 26.8.0.cl is generally available from 26.9.0.cl. + The Personalized Views TML portability feature introduced as Early Access in 26.8.0.cl is generally available from 26.9.0.cl. -* The `author` field in Personalized View TML maps to the view owner's username or email, ensuring ownership is retained when a Liveboard is promoted across clusters or orgs. -* The `obj_id` field provides a stable cross-environment identifier for Personalized Views. -* Smart merge import: when importing a Liveboard TML that contains Personalized Views, ThoughtSpot preserves views that exist only in the target environment, appends new views from the imported TML, and updates views present in both. + * The `author` field in Personalized View TML maps to the view owner's username or email, ensuring ownership is retained when a Liveboard is promoted across clusters or orgs. + * The `obj_id` field provides a stable cross-environment identifier for Personalized Views. + * Smart merge import: when importing a Liveboard TML that contains Personalized Views, ThoughtSpot preserves views that exist only in the target environment, appends new views from the imported TML, and updates views present in both. -For more information, see xref:tml.adoc#personalized-views-portability[Personalized Views portability in TML]. + For more information, see xref:tml.adoc#personalized-views-portability[Personalized Views portability in TML]. -=== Connection configuration — Scheduled Liveboards process type + === Connection configuration — Scheduled Liveboards process type -// SOURCE: SCAL-312738 + // SOURCE: SCAL-312738 -ThoughtSpot 26.9.0.cl adds `SCHEDULED_LIVEBOARDS` as a new process type for Embrace connection configurations. Administrators can assign the Scheduled Liveboards process to a connection configuration, enabling ThoughtSpot to use the associated credentials when running scheduled Liveboard delivery jobs. Configurable via: + ThoughtSpot 26.9.0.cl adds `SCHEDULED_LIVEBOARDS` as a new process type for Embrace connection configurations. Administrators can assign the Scheduled Liveboards process to a connection configuration, enabling ThoughtSpot to use the associated credentials when running scheduled Liveboard delivery jobs. Configurable via: -* `POST /api/rest/2.0/connection/configuration/create` -* `PUT /api/rest/2.0/connection/configuration/{configuration_identifier}/update` + * `POST /api/rest/2.0/connection/configuration/create` + * `PUT /api/rest/2.0/connection/configuration/{configuration_identifier}/update` -=== AI Context — Spotter Optimization tab + === AI Context — Spotter Optimization tab -// SOURCE: SCAL-277656 + // SOURCE: SCAL-277656 -The AI Context generation UI is revamped in 26.9.0.cl. A new *Spotter Optimization* tab is introduced in the data model editor for managing AI context, replacing the previous AI Context panel. The tab provides a more streamlined interface for reviewing and editing auto-generated descriptions for columns and joins. + The AI Context generation UI is revamped in 26.9.0.cl. A new *Spotter Optimization* tab is introduced in the data model editor for managing AI context, replacing the previous AI Context panel. The tab provides a more streamlined interface for reviewing and editing auto-generated descriptions for columns and joins. -No changes to the AI context REST API endpoints in this release. + No changes to the AI context REST API endpoints in this release. + == Version 26.8.0.cl, August 2026 === Spotter AI APIs @@ -251,84 +252,1236 @@ Uploads a custom font file to ThoughtSpot. Returns custom fonts uploaded to the instance. * `PUT /api/rest/2.0/customization/styles/fonts/{font_identifier}/update` + -Updates a custom font record. +Updates the display name, weight, style, or color of an existing custom font. -* `DELETE /api/rest/2.0/customization/styles/fonts/{font_identifier}/delete` + -Deletes a custom font. +* `POST /api/rest/2.0/customization/styles/fonts/delete` + +Deletes one or more custom fonts from the font library. -For more information, see xref:style-customization-api.adoc[Style customization APIs]. +Logo export:: -=== Liveboard schedules +* `POST /api/rest/2.0/customization/styles/logos/export` + +Exports the current logo files as a ZIP archive containing the default logo and the wide logo. -* The `POST /api/rest/2.0/schedules/create` API endpoint now supports the `connection_configuration_identifier` attribute. This attribute specifies a configured Embrace connection configuration when creating a scheduled Liveboard job. -* The `POST /api/rest/2.0/schedules/{schedule_identifier}/update` API endpoint now supports the `connection_configuration_identifier` attribute. +For more information, see xref:customize-style-api.adoc[Style customization APIs]. -=== Tags API +=== Manual translation APIs +The manual translation API endpoints allow you to import, export, and delete translations of terms and labels that can be presented to the user based on their locale settings. -The `POST /api/rest/2.0/tags/assign` and `POST /api/rest/2.0/tags/unassign` API endpoints now support Collections as a metadata object type. +* `POST /api/rest/2.0/localizations/manual-translation/import` + +Allows importing a CSV file containing translated terms and labels. +* `POST /api/rest/2.0/localizations/manual-translation/locales/{locale}/export` + +Retrieves all translations for a specific locale as a JSON map. +* `POST /api/rest/2.0/localizations/manual-translation/export` + +Downloads all manually translated terms and labels in the Org context as a CSV file. +* `POST /api/rest/2.0/localizations/manual-translation/delete` + +Deletes all manual translations from the Org. -=== Custom actions +For more information, see xref:manual-translation.adoc[Manual translations]. -The `POST /api/rest/2.0/customization/custom-actions/create` and `POST /api/rest/2.0/customization/custom-actions/{custom_action_identifier}/update` API endpoints now support `group_identifiers` for access control. This allows restricting custom action visibility to specific user groups. +=== REST API Python SDK +The REST API Python SDK library artifacts are now available on link:https://pypi.org/project/thoughtspot-rest-api-sdk/[PyPI, window=_blank]. For information about how to install and use the SDK, see xref:rest-api-python-sdk.adoc[Python SDK]. == Version 26.6.0.cl, June 2026 === Spotter AI APIs -Answer Export API [earlyAccess eaBackground]#Early Access#:: -ThoughtSpot introduces the `POST /api/rest/2.0/report/answer` endpoint for exporting Answer data in CSV, XLSX, PDF, or PNG format. Requires the `isAnswerExportV2Enabled` feature flag to be enabled on the instance. +Stop in-progress agent response:: -For more information, see xref:data-report-v2-api.adoc#answer-report[Answer Report API]. +* `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response` + +Stops a Spotter agent response that is currently in progress for a given conversation session. -Stop Spotter response:: -The `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response` API endpoint stops an in-progress Spotter agent response for a given conversation session. The conversation session remains active after the response stops. +For more information, see xref:spotter-agent-apis.adoc#_stop_an_in_progress_agent_response[Stop an in-progress agent response]. -=== Connections +=== Authentication +The following new endpoints allow searching for the authentication configuration at the cluster or Org level, and also allow enabling and disabling authentication. These endpoints currently support only trusted authentication. -Connection configurations:: -ThoughtSpot introduces the following new API endpoints for managing Embrace connection configurations: +* `POST /api/rest/2.0/auth/configure` + +Enables or disables authentication at cluster or Org level for the specified auth type. +* `POST /api/rest/2.0/auth/search` + +Returns the authentication configuration for the specified auth type at cluster and Org level. -* `POST /api/rest/2.0/connection/configuration/create` + -Creates a connection configuration for an Embrace connection. -* `GET /api/rest/2.0/connection/configuration/{configuration_identifier}` + -Retrieves an existing connection configuration. -* `PUT /api/rest/2.0/connection/configuration/{configuration_identifier}/update` + -Updates an existing connection configuration. -* `DELETE /api/rest/2.0/connection/configuration/{configuration_identifier}/delete` + -Deletes a connection configuration. -* `POST /api/rest/2.0/connection/configuration/search` + -Returns a list of connection configurations matching the specified filter criteria. +=== Connection deactivate and activate API [beta betaBackground]^Beta^ -For more information, see xref:embrace-connection-configuration.adoc[Connection configurations]. +// SOURCE: SCAL-294844, SCAL-294845, SCAL-278132 -=== REST API Python SDK +ThoughtSpot introduces REST API v2.0 endpoints to programmatically deactivate and activate data connections: + +* `POST /api/rest/2.0/connections/{connection_identifier}/status` + +Deactivates or activates a connection. + +=== Answer report API enhancements [earlyAccess eaBackground]#Early Access# + +The `POST /api/rest/2.0/report/answer` API endpoint introduces the following enhancements: + +Pinned Answer export:: +// SOURCE: SCAL-236681, SCAL-306548 +You can now export a pinned Answer directly from a Liveboard using the Answer report API. +To export a pinned Answer, specify the `viz_guid` parameter in your API request. +Exports from this endpoint inherently respect Liveboard-level filters, Runtime Filters, Column security rules, and JWT token context. ++ +To export a specific personalized view of a pinned Answer, include the `personalised_view_identifier` parameter. + +Spotter Answer export:: +XLSX and PDF export formats are now supported for Spotter (conversational) Answers. -ThoughtSpot provides the REST API Python SDK (`thoughtspot-rest-api-sdk`) to help Python developers interact programmatically with ThoughtSpot REST API v2 endpoints. The SDK is available on link:https://pypi.org/project/thoughtspot-rest-api-sdk/[PyPI, window=_blank]. +Custom PNG dimensions:: +PNG exports now support custom dimensions via the following new parameters: ++ +* `x_resolution`: Sets the export width in pixels. Valid range: 600–3840 px. +* `y_resolution`: Sets the export height in pixels. Valid range: 600–3840 px. + +Display scaling:: +A new `scaling` parameter allows you to adjust the relative size of visual elements in PNG exports without cropping. +Valid range: 80–500%. -For information about how to install and use the SDK, see xref:rest-api-sdk-python.adoc[Python SDK for REST APIs]. +Automatic file naming:: +The API now automatically names exported files based on the Answer title and appends the correct file extension (`.png`, `.pdf`, `.csv`, or `.xlsx`). + +Contact ThoughtSpot Support to enable these settings for PNG downloads on your ThoughtSpot instance. +For more information, see xref:data-report-v2-api.adoc#_answer_report_api[Answer report API documentation]. + +=== Share metadata API: Collections support [beta betaBackground]^Beta^ + +The `POST /api/rest/2.0/security/metadata/share` endpoint now supports sharing Collections. + +To share a Collection, set `metadata_type` to `COLLECTION` in the request body. +For more information, see xref:collections.adoc#share-collection[Share a Collection]. == Version 26.5.0.cl, May 2026 -=== Spotter AI APIs +=== Sync connection metadata attributes +You can now synchronize connection metadata attributes from your Cloud Data Warehouse (CDW) with ThoughtSpot by sending a request to the `POST /api/rest/2.0/connections/{connection_identifier}/resync-metadata` API endpoint. -The following API endpoints are deprecated in 26.5.0.cl: +=== Spotter APIs -* `POST /api/rest/2.0/ai/agent/converse/sse` — Use `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream` instead. -* `POST /api/rest/2.0/ai/agent/{conversation_identifier}/converse` — Use `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send` instead. +==== New API endpoints -New API endpoints:: +The following new endpoints allow sending messages to an active conversation +session with a Spotter agent. * `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send` + -Sends natural language messages to an existing Spotter agent conversation and returns the complete response synchronously. - +Allows sending a message to an active Spotter AI conversation and returns a synchronous response. * `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream` + -Sends natural language messages to an existing Spotter agent conversation and returns the response as a real-time Server-Sent Events (SSE) stream. +Allows sending to an active Spotter AI conversation and returns the response as a real-time Server-Sent Events (SSE) stream. + +These new endpoints replace the legacy agent conversation and SSE streaming APIs. + +==== Deprecated endpoints [.version-badge.deprecated]#Deprecated# + +* `POST /api/rest/2.0/ai/agent/{conversation_identifier}/converse` + +Replaced by `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send`. + +* `POST /api/rest/2.0/ai/agent/converse/sse` + +Replaced by `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream` + +These endpoints are deprecated and will be removed in a future release. Embedding applications and integrations using these APIs are advised to migrate to the new API endpoints for improved experience. + +==== Enhancements to conversation creation API [.version-badge.breaking]#Breaking# + +The following enhancements have been introduced for the conversation creation operation workflow with the `POST /api/rest/2.0/ai/agent/conversation/create` API endpoint: + +metadata_context:: +To define the conversation context, the API request must include the `metadata_context` parameter with one of the following values: + +* `AUTO_MODE`: Automatically discovers and selects the most relevant datasets for the user's queries. +* `DATA_SOURCE`: Sets the target context as the data source. You must specify at least one data source ID. +** To set a single data source object metadata context, specify a `data_source_identifier`. +** For multi-data source context, specify the `data_source_identifiers`. ++ +[IMPORTANT] +==== +The `data_source` and `guid` attributes are deprecated in the 26.5.0.cl release version. Integrations using these parameters in ThoughtSpot versions 26.2.0.cl through 26.4.0.cl will continue to work until further notice. However, ThoughtSpot recommends using either `AUTO_MODE` or `DATA_SOURCE` with `data_source_identifier` or `data_source_identifiers` for the metadata context. +==== + +Other context options:: +The `answer_context` and `liveboard_context` are removed and no longer supported. Any existing integration or embedding application passing `answer_context` or `liveboard_context` in the request body must update their workflows to use the `AUTO_MODE` or `DATA_SOURCE` option. + +Enable save chat:: +The `enable_save_chat` parameter, when set to `true`, saves the conversation. + +API response:: +The API response now returns the `conversation_identifier`, which is used in all +subsequent send message or SSE streaming calls. + +=== Liveboard report API enhancements [beta betaBackground]^Beta^ +The `POST /api/rest/2.0/report/liveboard` API endpoint enhances the PDF downloads by introducing the following parameters: + +* `"page_size": "CONTINUOUS"` for a seamless PDF export that matches the full length of your Liveboard. Unlike the A4 format, which introduces forced page breaks between visualizations, this continuous flow maintains your exact design and intended layout. +* `zoom_level` offers various download size options to suit the viewer's screen dimensions, thereby enhancing legibility. This can be set only when `page_size` is specified as `CONTINUOUS`. + +For more information, see xref:data-report-v2-api.adoc#_liveboard_report_api[Liveboard Report API documentation]. + +=== Metadata search API enhancements + +Personalized Views in metadata search:: +The `POST /api/rest/2.0/metadata/search` API endpoint introduces the `include_personalised_views` request parameter. + +When both `include_details: true` and `include_personalised_views: true` are specified in the request, the API returns a `personalised_views` array in the `metadata_detail` object for `LIVEBOARD` metadata type responses. + +This allows you to retrieve the full list of Personalized Views associated with a Liveboard in a single API call, without requiring a separate TML export. + +For more information, see xref:rest-api-v2-metadata-search.adoc#_include_personalised_views[Search metadata API]. + +=== TML API enhancements +The previous limit of 100 Personalized Views per Liveboard on TML import has been removed. You can now import all associated Personalized Views of a Liveboard without any views being dropped. For more information, see the xref:tml-api.adoc[TML API documentation]. + +== Version 26.4.0.cl, April 2026 + +=== Variable API endpoints +The following endpoints are introduced for bulk delete and update operations for variables: + +* `POST /api/rest/2.0/template/variables/{identifier}/update-values` + +Assigns multiple values to a variable and sets the scope for variable values in a single API request. +* `POST /api/rest/2.0/template/variables/delete` + +Deletes one or more variables in a single API request. + +These new API endpoints replace the following legacy API endpoints deprecated in 26.4.0.cl. + +* `POST /api/rest/2.0/template/variables/{identifier}/delete` +* `POST /api/rest/2.0/template/variables/update-values` + +Your existing implementation with the legacy API endpoints will continue to work until further notice. However, these endpoints will be removed from ThoughtSpot in a future release. Hence, we recommend updating your workflows to use the API endpoints at your earliest convenience. + +For more information, see xref:variables.adoc[Variable API documentation]. + +=== Metadata parameterization +You can now parameterize multiple fields in a metadata object in a single API request using the `/api/rest/2.0/metadata/parameterize-fields` API endpoint. +This endpoint replaces the legacy `/api/rest/2.0/metadata/parameterize` endpoint, which is deprecated in 26.4.0.cl. + +For more information, see xref:metadata-parameterization.adoc[Metadata parameterization API documentation]. + +=== Webhook integration +This release introduces the following features and enhancements to the webhook integration workflows: + +Custom HTTP headers in webhook requests:: +Administrators can configure custom HTTP headers to send in webhook requests triggered by ThoughtSpot, in addition to the standard HTTP and authentication headers. You can specify these headers in the `additional_headers` attribute during webhook creation (`/api/rest/2.0/webhooks/create`) and update (`/api/rest/2.0/webhooks/{webhook_identifier}/update`) via REST APIs. + +Webhook connection validation:: +You can now validate a webhook connection by sending a test payload via an API request to the `/api/rest/2.0/system/communication-channels/validate` endpoint. The API returns a response indicating the connection and authentication status for a given webhook connection. + +Webhook monitoring:: +To monitor the status of webhook jobs and scheduled events, ThoughtSpot introduces the `/api/rest/2.0/jobs/history/communication-channels/search` API endpoint. + +For more information, see xref:webhooks-comm-channel.adoc[Webhook configuration validation and monitoring]. + +=== Collections API endpoints + +The following APIs are introduced for Collections: + +* `POST /api/rest/2.0/collections/create` [beta betaBackground]^Beta^ + +Creates a new Collection. +* `POST /api/rest/2.0/collections/search` [beta betaBackground]^Beta^ + +Searches for a Collection in ThoughtSpot +* `POST /api/rest/2.0/collections/{collection_identifier}/update` [beta betaBackground]^Beta^ + +Updates an existing Collection +* `POST /api/rest/2.0/collections/delete` [beta betaBackground]^Beta^ + +Deletes a Collection + +For more information, see xref:collections.adoc[Collections]. + +=== Email customization API enhancements + +The `template_properties` parameter now has the `hide_logo_url` elements for email template customization. Set it to `true` to entirely hide the logo component in the ThoughtSpot notification emails. + +=== Spotter API enhancements +Spotter AI APIs now support the following error responses: + +* 401 Unauthorized: authentication token is missing, expired, or invalid. +* 403 Forbidden: the authenticated user does not have `CAN_USE_SPOTTER` privilege or view access to the underlying metadata sources. + +=== Pivot table .xlsx exports +The following API endpoints now support pivot tables in `.xlsx` downloads with full visual and structural parity: + +* `POST /api/rest/2.0/report/answer` +* `POST /api/rest/2.0/schedules/create` + +To enable pivot formatting on your ThoughtSpot instance, contact ThoughtSpot Support. + +== Version 26.3.0.cl, March 2026 + +=== Webhook APIs + +The Webhook API allows configuring Amazon S3 buckets as a storage destination for webhook payload delivery. + +* `POST /api/rest/2.0/webhooks/create` + +Configures storage destination for webhook delivery. +* `POST /api/rest/2.0/webhooks/{webhook_identifier}/update` + +Allows modifying storage configuration for a webhook. +* `POST /api/rest/2.0/webhooks/search` + +Retrieves storage configuration details. + +=== Object privilege APIs +Administrators and users with edit access to data models can now use `/api/rest/2.0/security/metadata/manage-object-privilege` to assign object-level permissions to users and groups and control access to Spotter data model instructions. + +To fetch object privileges for a data model, user, or group, use the `/api/rest/2.0/security/metadata/fetch-object-privileges` API endpoint. + +For more information, see xref:spotter-nl-instructions.adoc#_spotter_data_model_instructions_access[Spotter data model instructions access]. + + +=== User API enhancements + +The user APIs now support setting browser language as the default locale for ThoughtSpot users. Administrators can set the `use_browser_language` parameter as the default locale for ThoughtSpot users during the following API operations: + +* When creating a new user via `POST /api/rest/2.0/users/create` + +* When importing users via `POST /api/rest/2.0/users/import` + +* When updating user preferences via `POST /api/rest/2.0/users/{user_identifier}/update` + + +When set to `true`, a user's current locale preference is overridden and the browser's language takes precedence. + +The status of the browser language setting for a given user can also be retrieved using the following API endpoints: + +* `POST /api/rest/2.0/users/search` + +* `POST /api/rest/2.0/users/activate` + +* `GET /api/rest/2.0/auth/session/user` + + +=== Custom token generation API +Note the following changes to request parameters for the `/api/rest/2.0/auth/token/custom` API endpoint: + +* The `filter_rules` parameter on the custom token authentication (`/api/rest/2.0/auth/token/custom`) page in the REST API Playground is no longer available for new configurations. Existing implementations that use `filter_rules` continue to work. However, we strongly recommend migrating to `variable_values` and ABAC via RLS for data security. + +* The `parameter_values` property is supported in the current release but will be deprecated in an upcoming version. Using `parameter_values` for row-level security will be phased out with this deprecation. Therefore, we recommend generating JWTs that pass data security attributes through formula variable attributes instead of `filter_rules` or `parameter_values` for ABAC. + +For more information, see xref:abac-migration-guide.adoc[ABAC JWT migration guide] and xref:abac_rls-variables.adoc[ABAC via RLS]. + +== Version 26.2.0.cl, February 2026 + +=== Security settings APIs +This release introduces the following Security settings APIs: + +* `POST /api/rest/2.0/system/security-settings/configure` + +Allows configuring security settings at the Org level or for all Orgs on a ThoughtSpot instance. +* `POST /api/rest/2.0/system/security-settings/search` + +Gets a list of security settings configured on a specific Org or for all Orgs on a ThoughtSpot instance. + +For more information, see xref:security-settings.adoc[Security Settings]. + +=== Connection API +ThoughtSpot administrators can now revoke OAuth refresh tokens for users who no longer require access to a data warehouse connection via the `/api/rest/2.0/connections/{connection_identifier}/revoke-refresh-tokens` API endpoint. When a token is revoked, the affected user's session for that connection is terminated, and they must re-authenticate to regain access. + +=== Connection configuration API enhancements +You can now include `same_as_parent` and `policy_process_options` attributes in your API request to `/api/rest/2.0/connection-configurations/create` and `/api/rest/2.0/connection-configurations/{configuration_identifier}/update` endpoints. + +The `same_as_parent` parameter specifies if the configuration should inherit settings from its parent. The `policy_process_options` attribute can be used to define additional policy or processing options for the connection, to allow granular control over connection behavior. + +=== Liveboard Report API enhancements +You can now download Liveboard reports in the CSV and XLSX formats through the `POST /api/rest/2.0/report/liveboard` API endpoint. Both these options are Early Access features. + +For more information, see xref:data-report-v2-api.adoc[Data and Report APIs]. + +=== Email customization API enhancements + +The `template_properties` parameter now has two additional elements for email template customization: + +* `contact_support_url` to add a customized link for contacting customer support. +* `hide_contact_support_url` to hide the option of adding a link for customer support. + +=== System configuration API enhancements +The API response from the `/api/rest/2.0/system/config` endpoint indicates whether SAML or Okta authentication is enabled on the system. + +=== User API enhancements + +* `POST /api/rest/2.0/users/import` + +The `preferred_locale` parameter allows configuring the preferred locale for users being imported via API request. +* `POST /api/rest/2.0/users/search` + +The `include_variable_values` parameter in the API request allows including variable values in the search response. The variable values can be assigned for a user via xref:abac_rls-variables.adoc[ABAC tokens] or xref:variables.adoc#_define_values_and_scope_for_variables[variable API documentation]. + +== Version 10.15.0.cl, December 2025 + +=== Spotter APIs + +This release introduces the following Spotter APIs: + +* `POST /api/rest/2.0/ai/instructions/set` + +Allows configuring natural language (NL) instructions on a data model to define how Spotter interprets queries, handles data nuances, and improves responses. +* `POST /api/rest/2.0/ai/instructions/get` + +Gets NL instructions that are currently assigned to a model. +* `POST /api/rest/2.0/ai/data-source-suggestions` + +Retrieves a list of recommended data sources based on the specified query string. + +For more information, see xref:spotter-apis.adoc[Spotter AI APIs]. + +=== Variable APIs + +You can now create formula variables using the `/api/rest/2.0/template/variables/create` API endpoint, and assign values and scope to these variables using the `/api/rest/2.0/template/variables/update-values` API endpoint. + +For more information, see xref:variables.adoc[Configure variables]. + +=== ABAC tokens with formula variable attributes +The `/api/rest/2.0/auth/token/custom` API endpoint allows creating a token request with formula variables for ABAC via RLS implementation. + +For more information, see xref:abac-user-parameters.adoc[ABAC via tokens]. + +== Version 10.14.0.cl, November 2025 + +=== New API endpoints + + + +System:: +This release introduces the following endpoints for configuring communication channel preferences. + +* `POST /api/rest/2.0/system/preferences/communication-channels/configure` [beta betaBackground]^Beta^ + +Sets a communication channel preference for all Orgs at the cluster level or at the individual Org level. +* `POST /api/rest/2.0/system/preferences/communication-channels/search` [beta betaBackground]^Beta^ + +Gets details of the communication channel preferences configured on ThoughtSpot. ++ +For more information, see xref:webhooks-comm-channel.adoc[Configure and monitor communication channels]. + +Webhook:: +The following APIs are introduced for webhook CRUD operations: +* `POST /api/rest/2.0/webhooks/create` +Creates a webhook. +* `POST /api/rest/2.0/webhooks/{webhook_identifier}/update` +Updates the properties of a webhook. +* `POST /api/rest/2.0/webhooks/search` +Gets a list of webhooks configured in ThoughtSpot or in a specific Org. +* `POST /api/rest/2.0/webhooks/delete` +Deletes the webhook. ++ +For more information, see xref:webhooks-lb-schedule.adoc[Webhooks for Liveboard schedule events]. + +Column security rules:: + +* `POST /api/rest/2.0/security/column/rules/update` + +Updates column security rules for a given Table. + +* `POST /api/rest/2.0/security/column/rules/fetch` + +Gets details of column security rules for the tables specified in the API request. + +//// + +Spotter:: +POST /api/rest/2.0/ai/agent/{conversation_identifier}/converse +//// +=== Variable API enhancements + +The variable API enhancements are listed in the following sections. For additional details, see xref:variables.adoc[Define variables]. + +==== Variable creation API + +* The variable creation endpoint `/api/rest/2.0/template/variables/create` does not support assigning values to a variable. To assign values to a variable, use the `/api/rest/2.0/template/variables/update-values` endpoint. +* The `sensitive` parameter is renamed as `is_sensitive`. + +==== Variables update APIs [tag redBackground]#BREAKING CHANGE# + +The `/api/rest/2.0/template/variables/update` endpoint is deprecated and replaced with `/api/rest/2.0/template/variables/update-values`. + +To update the properties of a specific variable, use the `/api/rest/2.0/template/variables/{identifier}/update` endpoint and to assign values to one or several variables in a single API call, use the `POST /api/rest/2.0/template/variables/update-values` endpoint. + +==== Variables search API + +* The variables search API endpoint `/api/rest/2.0/template/variables/search` now includes the `value_scope` parameter that allows you to filter the API response by the objects to which the variable is mapped. +* Filtering API response by `EDITABLE_METADATA_AND_VALUES` is no longer supported. + + +=== User API enhancements +The following APIs now support the `variable_values` parameter. The `variable_values` property can be used for user-specific customization. + +* `POST /api/rest/2.0/users/create` +* `POST /api/rest/2.0/users/search` +* `POST /api/rest/2.0/users/activate` + +=== DBT API enhancements +The `/api/rest/2.0/dbt/generate-tml` endpoint supports the `model_tables` attribute to list models and their tables. + +//// + +=== Authentication API +Support for `variable_values` property in `/api/rest/2.0/auth/session/user` API calls. + +//// + +== Version 10.13.0.cl, October 2025 + +=== New API endpoints + +Spotter:: + +* `POST /api/rest/2.0/ai/agent/conversation/create` + +Creates a new AI-driven conversation session based on a specified data source. The resulting session sets the context for subsequent queries and responses. + + + +* `POST /api/rest/2.0/ai/relevant-questions/` + +Breaks down a user-submitted query into a series of analytical sub-questions using relevant contextual metadata. + +* `POST /api/rest/2.0/ai/agent/converse/sse` + +Allows sending a follow-up message or question to an ongoing conversation session and returns the AI agent's response, including answers, tokens, and visualization details. + + +For more information, see xref:spotter-apis.adoc[Spotter AI APIs]. + +Email customization:: +`POST /api/rest/2.0/customization/email/update` + +Updates an existing email customization. For more information, see xref:customize-email-apis.adoc[Customize email template]. + +=== API enhancements +The following APIs were modified to include new parameters: + +TML export:: +The TML export API now supports the `export_with_column_aliases` parameter in `export_options` to indicate whether to export column aliases of the model. + +Email customization:: +The `/api/rest/2.0/customization/email/update` and `/api/rest/2.0/customization/email` APIs now include `company_privacy_policy_url` and `company_website_url` properties in template variables, and a new `org_identifier` parameter in the API request. + +For more information, see xref:customize-email-apis.adoc[Customize email template]. + +=== Deprecated endpoints + +Spotter:: +The `POST /api/rest/2.0/ai/analytical-questions` Spotter AI API [beta betaBackground]^Beta^ is deprecated and replaced with the new API endpoint, `POST /api/rest/2.0/ai/relevant-questions/`. + +Email customization:: +The `POST /api/rest/2.0/customization/email/{template_identifier}/delete` email customization API is deprecated and replaced with the new API endpoint, `POST /api/rest/2.0/customization/email/delete`. + + +//// +=== Deprecated endpoints +The following Spotter AI APIs [beta betaBackground]^Beta^ are deprecated and replaced with the new xref:spotter-apis.adoc[AI APIs]. + +* `POST /api/rest/2.0/ai/conversation/create` +* `POST /api/rest/2.0/ai/analytical-questions` +* `POST /api/rest/2.0/ai/conversation/{conversation_identifier}/converse` +//// + +== Version 10.12.0.cl, September 2025 + +=== New API endpoints + +The following API endpoints are now available: + +Custom calendar:: +* `POST /api/rest/2.0/calendars/create` + +Creates a custom calendar. +* `POST /api/rest/2.0/calendars/generate-csv` + +Exports a custom calendar in the CSV format. +* `POST /api/rest/2.0/calendars/search` + +Gets custom calendars for the connection ID specified in the API request. +* `POST /api/rest/2.0/calendars/{calendar_identifier}/delete` + +Deletes a custom calendar. +* `POST /api/rest/2.0/calendars/{calendar_identifier}/update` + +Updates a custom calendar. + +Connection configuration:: +* `POST /api/rest/2.0/connection-configurations/create` + +Creates an additional configuration to an existing connection to a data warehouse. +* `POST /api/rest/2.0/connection-configurations/search` + +Gets the required connection configuration objects. +* `POST /api/rest/2.0/connection-configurations/{configuration_identifier}/update` + +Updates an existing connection configuration object. +* `POST /api/rest/2.0/connection-configurations/delete` + +Deletes the connection configuration object. + +=== Enhancements to APIs + +Export API endpoint:: + +* Answer TML: + +The `POST /api/rest/2.0/metadata/tml/export` API endpoint now allows fetching TML for Answer objects that do not have an ID or name assigned. The `session_identifier` and `generation_number` parameters allow you to define the session ID and the Answer generation number in the API request. These optional attributes can be used for unsaved Answers generated from Spotter queries. + +* Table TML: + +The `POST /api/rest/2.0/metadata/tml/export` API request allows exporting column security rules for Table TML objects. This attribute will export column security rules only if the object specified in the API request has column security applied and when `export_associated` is set to `true`. + +== Version 10.11.0.cl, July 2025 + +=== Search metadata API enhancements +The search metadata (`/api/rest/2.0/metadata/search`) API includes the following enhancements: + +* The `liveboard_reponse_version` parameter. It allows you to specify the xref:rest-api-v2-metadata-search.adoc#_response_format_for_liveboards[response format for Liveboard objects]. +* The `subtypes` attribute to specify the sub-type for the `LOGICAL_TABLE` metadata type. The `LOGICAL_TABLE` type allows you to fetch objects such as Tables, Models, and Views. The `subtypes` parameter allows you to filter API response by specifying subcategories of the object type. +* The `include_only_published_objects` attribute to specify whether the search should include xref:publish-api.adoc[published objects]. + + +=== System API +The API response generated from the `GET /api/rest/2.0/system/config-overrides` requests now returns the overrides in the `config_override_info` object. + +=== TML API +The API response for the `POST /api/rest/2.0/metadata/tml/async/import` and `POST /api/rest/2.0/metadata/tml/async/status` now includes the `author_display_name` property. This property shows the display name of user that initiated the asynchronous TML import request. + +=== REST API Java SDK + +The REST API Java SDK library artifacts are now available in the `com.thoughtspot` Maven namespace. If you are using Maven Central to import the REST API SDK artifacts, update the group ID in your `pom.xml` file to `com.thoughtspot` and the artifact ID to `rest-api-sdk`. + +For more information, see xref:rest-api-java-sdk.adoc#_import_the_sdk_to_your_application_environment[REST API Java SDK]. + +== Version 10.10.0.cl, July 2025 + +=== Email template customization APIs +This release introduces the following new endpoints for email template customization: + +* `POST /api/rest/2.0/customization/email` + +Allows you to personalize the ThoughtSpot notification emails content. +* `POST /api/rest/2.0/customization/email/{template_identifier}/delete` + +Removes the customizations done for the ThoughtSpot notification emails. +* `POST /api/rest/2.0/customization/email/search` + +Allows searching the email customization configuration if configured for ThoughtSpot. +* `POST /api/rest/2.0/customization/email/validate` + +Validates the email customization configuration if configured for ThoughtSpot. + +=== Group API + +The `/api/rest/2.0/groups/search` endpoint now supports the following new options in group search API requests: + +* `include_users` + +When set to `true`, it includes user details in the group search API response. +* `include_sub_groups` + +When set to `true`, it includes sub-groups in the group search response. + +=== Schedule API +You can now specify the `personalised_view_id` of a Liveboard in API requests to the following schedule APIs: + +* `POST /api/rest/2.0/schedules/create` +To schedule a job for a personalized view of the Liveboard, specify the `personalised_view_id`. +* `POST /api/rest/2.0/schedules/{schedule_identifier}/update` +To update schedule details for a specific view of the Liveboard, specify the `personalised_view_id`. + +== Version 10.9.0.cl, June 2025 + +=== Metadata parameterization and content publishing across Orgs + +This release introduces the following new endpoints for metadata parameterization [beta betaBackground]^Beta^ and content publishing [beta betaBackground]^Beta^ across Orgs. To enable the content publishing feature and the related API operations on your instance, contact ThoughtSpot Support. + +* `POST /api/rest/2.0/metadata/parameterize` [beta betaBackground]^Beta^ + +Allows you to parameterize fields in metadata objects. +* `POST /api/rest/2.0/metadata/unparameterize` [beta betaBackground]^Beta^ + +Allows removing parameterization from fields in metadata objects +* `POST /api/rest/2.0/security/metadata/publish` [beta betaBackground]^Beta^ + +Publish metadata objects to one or several Orgs on an instance. +* `POST /api/rest/2.0/security/metadata/unpublish` [beta betaBackground]^Beta^ + +Removes published metadata objects from the Orgs specified in the API request. +* `POST /api/rest/2.0/template/variables/create` [beta betaBackground]^Beta^ + +Allows creating a template variable which can be used to parameterize fields in a metadata object. +* `POST /api/rest/2.0/template/variables/search` [beta betaBackground]^Beta^ + +Allows searching template variables +* `POST /api/rest/2.0/template/variables/{identifier}/update` [beta betaBackground]^Beta^ + +Allows updating properties of a template variable. +* `POST /api/rest/2.0/template/variables/update` [beta betaBackground]^Beta^ + +Allows you to add, remove, or replace properties of one or several template variables. +* `POST /api/rest/2.0/template/variables/{identifier}/delete` [beta betaBackground]^Beta^ + +Deletes a template variable. + +If your metadata objects are parameterized, you can use the `show_resolved_parameters` to filter the API response from `/api/rest/2.0/connection/search` and `/api/rest/2.0/metadata/search` endpoints to get only the objects with resolved parameterized values. + +=== Liveboard Report API +The Liveboard Report API now allows you to define the following properties: + +* `tab_identifiers` + +Optional parameter to specify the name or GUID of a Liveboard tab to export only the visualizations in that tab. +* `personalised_view_identifier` + +Optional parameter to specify the GUID of the Liveboard personalized view that you want to download. + +In addition to these parameters, you can also define the following properties for PNG downloads: + +* `image_resolution` +* `image_scale` +* `include_header` + +For more information, see xref:data-report-v2-api.adoc#_liveboard_report_api[Liveboard Report API]. + +=== REST API Java SDK + +The REST API Java SDK enables developers to interact programmatically with ThoughtSpot REST APIs from Java applications. It provides a client library with Java methods and classes that map to API endpoints, handle authentication, send API requests, and allow creating and modifying ThoughtSpot resources and objects. + +For information about how to install and use the SDK, see xref:rest-api-java-sdk.adoc[Java SDK for REST APIs]. + + +== Version 10.8.0.cl, April 2025 + +=== New API endpoints + +This version introduces the following endpoints: + +* `POST /api/rest/2.0/metadata/update-obj-id` + +Update object IDs for given metadata objects. + + +[NOTE] +==== +An object ID is a user-defined ID assigned to a ThoughtSpot object in addition to the system-generated GUID. +Note that the object ID generation for metadata objects is disabled by default. If this feature is enabled on your instance, you can use the `POST /api/rest/2.0/metadata/update-obj-id` to assign or update the object ID. +==== + +=== Metadata API + +* The `POST /api/rest/2.0/metadata/search` endpoint now supports the following parameters: + +** `include_discoverable_objects` + +Allows including Answers and Liveboards that are marked as discoverable by the object owner. +** `metadata_obj_id` + +Filters metadata objects by the user-defined object ID. This parameter returns data only if the user-defined object ID feature is enabled on your instance. -Breaking changes in `POST /api/rest/2.0/ai/agent/conversation/create`:: -The `metadata_context` object now requires `type` to be one of `AUTO_MODE` or `DATA_SOURCE`. The legacy `data_source` option is deprecated. +=== TML APIs + +* The `all_orgs_context` parameter in TML import APIs (`/api/rest/2.0/metadata/tml/import` and `/api/rest/2.0/metadata/tml/async/import`) is deprecated and removed from the Playground. Use `all_orgs_override` to define the Org context in your API requests. + +* The TML export API now allows exporting TML content with user feedback received for objects such as AI-generated Answers. The `export_with_associated_feedbacks` attribute is set to `false` by default. + +=== Report APIs +The Liveboard export API (`/api/rest/2.0/report/liveboard`) now allows overriding filters applied to a Liveboard. The `override_filters` array allows specifying several types of filters and updates the Liveboard data during export. + +For more information, see xref:data-report-v2-api.adoc#_override_filters[Override filters]. + +== Version 10.6.0.cl, March 2025 + +=== New metadata API endpoints + +* `POST /api/rest/2.0/metadata/headers/update` + +Updates metadata header for a given list of objects. +* `POST /api/rest/2.0/metadata/worksheets/convert` + +Converts a Worksheet object to a Model. + +=== Report APIs +[tag redBackground]#BREAKING CHANGE# + +Downloading Liveboard reports in the CSV and XLSX file format via `POST /api/rest/2.0/report/liveboard` API endpoint is not supported. The CSV and XLSX `file_format` options have been removed because they were not functioning in the expected manner. + +==== Parameters for regional settings + +The `/api/rest/2.0/report/answer` and `/api/rest/2.0/report/liveboard` now allow users to define the following `regional_settings` attributes: + +* `currency_format` +* `user_locale` +* `number_format_locale` +* `date_format_locale` + +=== Custom object ID in TML and Metadata APIs + +The following API endpoints allow you to specify a custom object ID (`obj_identifier`) in the metadata object properties: + +* `POST /api/rest/2.0/metadata/search` +* `POST /api/rest/2.0/metadata/headers/update` +* `POST /api/rest/2.0/metadata/tml/export` + + +=== TML import API + +The `/api/rest/2.0/metadata/tml/async/import` and `POST /api/rest/2.0/metadata/tml/import` endpoints allow skipping diff check when processing TMLs for imports. The `skip_diff_check` attribute is disabled by default and can be enabled to avoid importing objects that do not have any changes. + +=== API response changes + +The 200 and 201 response body from `POST /api/rest/2.0/ai/answer/create` and `POST /api/rest/2.0/ai/conversation/{conversation_identifier}/converse` API calls now includes the `display_tokens` property. + + +== Version 10.5.0.cl, December 2024 + +=== Custom access token API +The `/api/rest/2.0/auth/token/custom` API endpoint allows setting the following attributes in API requests: + +* `auto_create` + +Creates a user if username specified in the API request is not available in ThoughtSpot. By default, the `auto_create` is set to `true`. +* `REPLACE` enum for `persist_option` + +Allows replacing persisted values with new attributes defined in the token generation API request. For more information, see xref:abac-user-parameters.adoc[ABAC via tokens]. + +=== TML import APIs + +TML async import:: + +The `/api/rest/2.0/metadata/tml/async/import` supports setting the following properties via API requests: ++ +* `import_policy` + +Allows you to specify if all objects should be imported during the TML import operation. Valid values are: + +** `PARTIAL_OBJECT` (default) +** `PARTIAL` +** `VALIDATE_ONLY` +** `ALL_OR_NONE` + +* `enable_large_metadata_validation` + +Indicates if the TMLs with large and complex metadata should be validated before the import. ++ +For more information about these attributes, see xref:tml.adoc#_import_tml_objects_asynchronously[Import TML objects asynchronously]. + +TML import API:: + +The `/api/rest/2.0/metadata/tml/import` API also supports setting the `enable_large_metadata_validation` attribute for large and complex metadata objects during TML import. + +TML export API:: + +The `/api/rest/2.0/metadata/tml/export` endpoint now allows you to include additional attributes when exporting TML for an object from ThoughtSpot. The `export_options` allows you to include the following optional attributes: + +* `include_obj_id_ref` + +Specifies whether to export `user_defined_id` of the referenced object. This setting is valid only if the `UserDefinedId` property in TML is enabled. +* `include_guid` + +Specifies whether to export the GUID of the object. This setting is valid only if the `UserDefinedId` property in TML is enabled. +* `include_obj_id` + +Specifies whether to export the `user_defined_id` of the object. This setting is valid only if the `UserDefinedId` property in TML is enabled. + + +Share metadata:: + +The `email` attribute is now optional in the `POST` request body sent to the `/api/rest/2.0/security/metadata/share` API endpoint. + +Role API:: + +The `/api/rest/2.0/roles/create` API endpoint now allows setting `read_only` attribute to specify if the role is read only. A read-only role cannot be updated or deleted. + +== Version 10.4.0.cl, November 2024 + +=== New API endpoints + +Spotter AI APIs [beta betaBackground]^Beta^ :: + +* `POST /api/rest/2.0/ai/conversation/create` + +Creates a conversation session. +* `POST /api/rest/2.0/ai/conversation/{conversation_identifier}/converse` + +Generates responses for user queries and follow-up questions. +* `POST /api/rest/2.0/ai/answer/create` + +Generates an Answer from a Natural Language Search query. + +Authentication:: +The `/api/rest/2.0/auth/token/custom` API endpoint is now available to generate an authentication token with custom rules and filter conditions for a user. + ++ +ThoughtSpot recommends using the custom token API endpoint to generate tokens for the Attribute-Based Access Control (ABAC) implementation. For more information, see xref:abac_rls-variables.adoc[ABAC via RLS with variables]. + +Connections:: +The following new API endpoints are available for updating and deleting a connection object: + +* `POST /api/rest/2.0/connections/{connection_identifier}/update` +* `POST /api/rest/2.0/connections/{connection_identifier}/delete` + ++ +ThoughtSpot recommends using these APIs instead of `POST /api/rest/2.0/connection/update` and `POST /api/rest/2.0/connection/delete`. + +TML:: +The following API endpoints are available for asynchronous TML import: + +* `POST /api/rest/2.0/metadata/tml/async/import` + +Validates and imports TML objects asynchronously. Use this API endpoint when importing large metadata objects. +* `POST /api/rest/2.0/metadata/tml/async/status` + +Fetches task status for the async TML import operations. + +For more information, see xref:tml.adoc#_import_tml_objects_asynchronously[Import TML objects asynchronously]. + +=== API enhancements + +User session:: + +* The 200 API response for the `/api/rest/2.0/auth/session/user` and `/api/rest/2.0/users/search` is modified to show `access_control_properties`. + +* You can now manage account activation status for IAMv2 users using the following API endpoints: + +** `POST /api/rest/2.0/users/create` + +** `POST /api/rest/2.0/users/{user_identifier}/update` + +Report API:: + +The `POST /api/rest/2.0/report/answer` API endpoint supports downloading an Answer generated by the Spotter AI APIs: + +* `session_identifier` + +Session ID returned in API response by the `/api/rest/2.0/ai/answer/create` or `/api/rest/2.0/ai/conversation/create` endpoint. +* `generation_number` + +Number assigned to the Answer session with Spotter. ++ +If you are downloading an Answer generated by Spotter, you must specify the session ID. The `metadata_identifier` property is not required. + +=== Deprecated features + +Connection APIs:: + +The following connection API endpoints are deprecated: + +* `POST /api/rest/2.0/connection/delete` +* `POST /api/rest/2.0/connection/update` + ++ +Use `POST /api/rest/2.0/connections/{connection_identifier}/update` and `POST /api/rest/2.0/connections/{connection_identifier}/delete` APIs to update and delete a connection object respectively. + +Authentication:: + +The `user_parameters` property in `/api/rest/2.0/auth/token/full` and `/api/rest/2.0/auth/token/object` APIs is deprecated. ++ +ThoughtSpot recommends using `/api/rest/2.0/auth/token/custom` API endpoint with `filter_rules` and `parameter_values` to configure user properties for ABAC via tokens. + +== Version 10.3.0.cl, October 2024 + +=== New API endpoint + +You can now create a copy of a Liveboard or Answer object using `/api/rest/2.0/metadata/copyobject` API endpoint. + +== Version 10.1.0.cl, August 2024 + +=== New API endpoints + +* `POST /api/rest/2.0/metadata/tml/export/batch` + +Exports a batch of TML for user, user group, or Role objects. + +=== Security APIs +The `/api/rest/2.0/security/metadata/fetch-permissions` API endpoint supports the following parameters: + +* `record_offset` + +Specifies the starting record number from which the records for each metadata type will be included in the API response. +* `record_size` + +Specifies the number of records that should be included for each metadata type in the API response. +* `permission_type` + +Specifies the type of permission. Valid values are: +** `EFFECTIVE` - If user permission to the metadata objects is granted by the privileges assigned to the groups to which they belong. +** `DEFINED` - If a user or user group received access to metadata objects via object sharing by another user. + +== Version 10.0.0.cl, July 2024 + +=== Roles + +You can now assign the `CAN_MANAGE_VERSION_CONTROL` role using any of the following API endpoints: + +* `POST /api/rest/2.0/roles/create` +* `POST /api/rest/2.0/roles/{role_identifier}/update` + +The `CAN_MANAGE_VERSION_CONTROL` Role privilege is required for Git integration with ThoughtSpot. + +== Version 9.12.0.cl, May 2024 + +==== New features + +Authentication API:: + +* `/api/rest/2.0/auth/token/validate` + +Validates the authentication token of the logged-in user. + +TML API:: +The export TML API requests now support the following parameters: ++ +* `export_schema_version` + +Specifies the schema version for datasets during TML export. By default, the API request uses v1 schema for Worksheet TML export. For Models, set `export_schema_version` to `v2`. + +* `export_dependent` + +Allows exporting dependent Tables while exporting a Connection. +* `export_connection_as_dependent` + +Specifies if a Connection can be exported as a dependent object when exporting a Table, Worksheet, Answer, or Liveboard. This parameter works only when `export_associated` is set to `true` in the API request. + +==== Deprecated features + +Token authentication APIs:: + +The `jwt_user_options` object property in `/api/rest/2.0/auth/token/full` and `/api/rest/2.0/auth/token/object` is deprecated. Use the `user_parameters` property to define security entitlements to a user session. For more information, see xref:abac-user-parameters.adoc[ABAC via token][beta betaBackground]^Beta^. + +== Version 9.10.5.cl, April 2024 + +=== New features + +Authentication:: + +The `/api/rest/2.0/auth/token/full` and `/api/rest/2.0/auth/token/object` API endpoints support generating JWT token for Attribute-Based Access Control. The `user_parameters` object allows you to define security entitlements for a given user. + +For more information, see xref:abac-user-parameters.adoc[ABAC via tokens]. + +Roles:: + +The `/api/rest/2.0/roles/create` and `/api/rest/2.0/roles/{role_identifier}/update` API endpoints support assigning the following privileges to a Role for granular data access control and management: + +* `CAN_MANAGE_CUSTOM_CALENDAR` +* `CAN_CREATE_OR_EDIT_CONNECTIONS` +* `CAN_MANAGE_WORKSHEET_VIEWS_TABLES` + +DBT:: + +You can now use `file_content` to upload DBT Manifest and Catalog artifact files as a ZIP file in your API requests to the `/api/rest/2.0/dbt/dbt-connection`, `/api/rest/2.0/dbt/generate-tml`, `/api/rest/2.0/dbt/generate-sync-tml`, and `/api/rest/2.0/dbt/update-dbt-connection` endpoints. This field is required if the `import_type` parameter is set to `'ZIP_FILE'`. + +Connections:: + +* `/api/rest/2.0/connections/fetch-connection-diff-status/{connection_identifier}` + +Validates the differences in Connection metadata between Cloud Data Warehouse and ThoughtSpot. +* `/api/rest/2.0/connections/download-connection-metadata-changes/{connection_identifier}` + +Downloads the connection metadata differences identified between Cloud Data Warehouse and ThoughtSpot. + +Logs:: +The `/api/rest/2.0/logs/fetch` API endpoint allows fetching all logs in a single API request. To get all logs, set `get_all_logs` to `true`. + +Share metadata:: + +The `/api/rest/2.0/security/metadata/share` API supports the following new properties: + +* `notify_on_share` + +Sends a share notification to the email addresses specified in the API request. +* `has_lenient_discoverability` + +Sets the shared metadata object as a discoverable object. Applies to Saved Answers and Liveboards only. + +Users:: +The `trigger_activation_email` property allows you to specify if an activation email must be sent to the user's email address in the user creation request to the `/api/rest/2.0/users/create` endpoint. + +=== Deprecated features + +Version Control APIs:: + +The following parameters in `/api/rest/2.0/vcs/git/config/create` and `/api/rest/2.0/vcs/git/config/update` are deprecated from 9.10.5.cl onward: + +* `default_branch_name` + +Replaced by `commit_branch_name` +* `guid_mapping_branch_name` + +Replaced by `configuration_branch_name` + +For more information, see xref:version_control.adoc[Git integration and version control]. + +== Version 9.10.0.cl, March 2024 + +=== New API endpoints + +DBT:: + +* `POST /api/rest/2.0/dbt/dbt-connection` + +Creates a DBT connection. +* `POST /api/rest/2.0/dbt/generate-tml` + +Generates Worksheets and Tables for a given DBT connection. +* `POST /api/rest/2.0/dbt/generate-sync-tml` + +Synchronizes the existing TML of data models and Worksheets and imports them to ThoughtSpot. +* `POST /api/rest/2.0/dbt/search` + +Gets a list of DBT connection objects for a given user or Org. +* `POST /api/rest/2.0/dbt/{dbt_connection_identifier}` + +Updates a DBT connection. + +System:: + +`GET api/rest/2.0/system/banner` + +Gets cluster maintenance status and banner text. + ++ +For more information, see xref:tse-eco-mode.adoc#_cluster_status_during_upgrade[Cluster maintenance and upgrade]. + +== Version 9.8.0.cl, January 2024 + +The `deploy_policy` property in the `/api/rest/2.0/vcs/git/commits/deploy` endpoint now supports the `VALIDATE_ONLY` option, which allows you to compare and validate TML content on the destination environment against the content in the main branch before deploying commits. + +== Version 9.7.0.cl, November 2023 + +=== Version Control APIs + +This release introduces the following enhancements to the Version Control API endpoints: + +==== Git connection creation and update APIs + +The `POST /api/rest/2.0/vcs/git/config/create` and `POST /api/rest/2.0/vcs/git/config/update` API endpoints include the following enhancements: + +New parameters:: + +* `commit_branch_name` + +Allows configuring a commit branch for Git connections on your ThoughtSpot instance. ThoughtSpot recommends using `commit_branch_name` instead of `default_branch_name` in the API calls to prevent users from committing changes to the default deployment branch. +* `configuration_branch_name` + +Allows configuring a separate Git branch for storing and maintaining configuration files, such as GUID mapping and commit tracking files. If the `configuration_branch_name` property is defined, the `guid_mapping_branch_name` parameter is not required. + +Modified parameters:: +The `enable_guid_mapping` parameter is enabled by default. + +Separate branches for Orgs:: +If you are using Orgs and want to move content between these Orgs using version control APIs, ensure that you set a separate Git branch for each Org. If two Orgs are connected to the same Git `repository_url`, the `POST /api/rest/2.0/vcs/git/config/create` and `POST /api/rest/2.0/vcs/git/config/update` API endpoints do not support configuring the same branch name for these Orgs. + +Deprecation notice:: + +The `default_branch_name` and `guid_mapping_branch_name` parameters will be deprecated from version 10.0.0.cl and later releases. + +For more information, see xref:git-configuration.adoc#connectTS[Connect your ThoughtSpot environment to the Git repository]. + +==== Commit API + +The `POST /api/rest/2.0/vcs/git/branches/commit` API endpoint allows the following new attribute in the request body: + +* `delete_aware` ++ +When set to true, the system runs a check between the objects and files in the Git branch and destination environment or Org. If an object exists in the Git branch, but not the destination environment or Org, it will be deleted from the Git branch during the commit operation. + +For more information, see xref:version_control.adoc#_commit_files_and_changes[Commit files]. + +==== Deploy API + +Note the following changes: + +* The `branch_name` attribute is now mandatory in the `POST /api/rest/2.0/vcs/git/commits/deploy` API requests. Ensure that you specify the name of the Git branch from which the commits can be picked and deployed on the destination environment or Org. + +* After a successful deployment, a tracking file is generated with the `commit_id` and saved in the Git branch that is used for storing configuration files. The `commit_id` recorded in the tracking file is used for comparing changes when new commits are pushed in the subsequent API calls. + +For more information, see xref:version_control.adoc#_deploy_commits[Deploy commits]. + +=== User API + +The following new API endpoints are introduced for user account management: + +* `POST /api/rest/2.0/users/activate` + +Activates an inactive user account. + +* `POST /api/rest/2.0/users/deactivate` + +Deactivates a user account. + +=== Support for sorting of columns at runtime +The following data API endpoints now support runtime sorting of columns: + +* `POST /api/rest/2.0/searchdata` + +* `POST /api/rest/2.0/metadata/liveboard/data` + +* `POST /api/rest/2.0/metadata/answer/data` + + +For more information, see xref:runtime-sort.adoc[Runtime sorting of columns]. + +== Version 9.6.0.cl, October 2023 + +=== New API endpoints + +* `POST /api/rest/2.0/customization/custom-actions/search` + +Gets custom action objects +* `POST /api/rest/2.0/customization/custom-actions` + +Creates a custom action +* `POST /api/rest/2.0/customization/custom-actions/{custom_action_identifier}/update` + +Updates the properties of a custom action object. +* `POST /api/rest/2.0/customization/custom-actions/{custom_action_identifier}/delete` + +Deletes a custom action + +=== SDK for TypeScript + +ThoughtSpot provides TypeScript SDK to help client applications call REST APIs using TypeScript. You can download the SDK from the link:https://www.npmjs.com/package/@thoughtspot/rest-api-sdk?activeTab=readme[NPM site, window=_blank]. + +== Version 9.5.0.cl, September 2023 + +=== New API endpoints for Role-Based Access Control [beta betaBackground]^Beta^ + +* `POST /api/rest/2.0/roles/search` + +Gets details of role objects available in the ThoughtSpot system. +* `POST /api/rest/2.0/roles/create` + +Creates a role and assigns privileges +* `POST /api/rest/2.0/roles/{role_identifier}/update` + +Updates the properties of a given role +* `POST /api/rest/2.0/roles/{role_identifier}/delete` + +Removes a role object from the ThoughtSpot system + +For more information, see xref:roles.adoc[Role-based access control]. + +[NOTE] +==== +The roles APIs work only if the Role-Based Access Control (RBAC) [beta betaBackground]^Beta^ feature is enabled on your instance. The RBAC feature is turned off by default. To enable this feature, contact ThoughtSpot Support. +==== + +=== Enhancements and API modifications + +Support for runtime parameter overrides:: +The following data and report API endpoints support applying runtime parameter overrides: +* `POST /api/rest/2.0/searchdata` + +* `POST /api/rest/2.0/metadata/liveboard/data` + +* `POST /api/rest/2.0/metadata/answer/data` + +* `POST /api/rest/2.0/report/liveboard` + +* `POST /api/rest/2.0/report/answer` + +Git integration support for Orgs:: + +The Version Control API endpoints support using Orgs as disparate deployment environments. You can create separate Orgs for `dev`, `staging`, and `prod` and integrate these environments with a GitHub repo. + ++ +For more information, see xref:version_control.adoc[Git integration and version control]. + +=== Response code change [tag redBackground]#BREAKING CHANGE# + +The following endpoints now return the 204 response code instead of 200. The 204 code does not return a response body. This change may affect your current implementation, so we recommend that you update your code to avoid issues. + +* `POST /api/rest/2.0/connection/delete` +* `POST /api/rest/2.0/connection/update` +* `POST /api/rest/2.0/users/{user_identifier}/update` +* `POST /api/rest/2.0/users/{user_identifier}/delete` +* `POST /api/rest/2.0/users/change-password` +* `POST /api/rest/2.0/users/reset-password` +* `POST /api/rest/2.0/users/force-logout` +* `POST /api/rest/2.0/groups/{group_identifier}/update` +* `POST /api/rest/2.0/groups/{group_identifier}/delete` +* `POST /api/rest/2.0/metadata/delete` +* `POST /api/rest/2.0/orgs/{org_identifier}/update` +* `POST /api/rest/2.0/orgs/{org_identifier}/delete` +* `POST /api/rest/2.0/schedules/{schedule_identifier}/delete` +* `POST /api/rest/2.0/schedules/{schedule_identifier}/update` +* `POST /api/rest/2.0/security/metadata/assign` +* `POST /api/rest/2.0/security/metadata/share` +* `POST /api/rest/2.0/system/config-update` +* `POST /api/rest/2.0/tags/{tag_identifier}/update` +* `POST /api/rest/2.0/tags/{tag_identifier}/delete` +* `POST /api/rest/2.0/tags/assign` +* `POST /api/rest/2.0/tags/unassign` +* `POST /api/rest/2.0/vcs/git/config/delete` +* `POST /api/rest/2.0/auth/session/login` +* `POST /api/rest/2.0/auth/session/logout` +* `POST /api/rest/2.0/auth/token/revoke` + + +== Version 9.4.0.cl, August 2023 + +=== API endpoints to schedule and manage Liveboard jobs + +* `*POST* /api/rest/2.0/schedules/create` + +Creates a scheduled job for a Liveboard +* `*POST* /api/rest/2.0/schedules/{schedule_identifier}/update` + +Updates a scheduled job +* `*POST* /api/rest/2.0/schedules/search` + +Gets a list of Liveboard jobs configured on a ThoughtSpot instance +* `*POST* /api/rest/2.0/schedules/{schedule_identifier}/delete` + +Deletes a scheduled job. + +For more information, see link:{{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fschedules%2Fsearch-schedule[REST API v2.0 Reference]. + +=== API to fetch authentication token + +The `GET /api/rest/2.0/auth/session/token` API endpoint fetches the current authentication token used by the currently logged-in user. + +=== Version Control API enhancements + +* The following Version Control API endpoints support generating and maintaining a GUID mapping file on a Git branch connected to a ThoughtSpot instance: + +** `*POST* /api/rest/2.0/vcs/git/config/create` +** `*POST* /api/rest/2.0/vcs/git/config/update` + +=== User and group API enhancements + +* The `**POST** /api/rest/2.0/users/{user_identifier}/update` and `**POST** /api/rest/2.0/groups/{group_identifier}/update` support specifying the type of operation API request. For example, if you are removing a property of a user or group object, you can specify the `operation` type as `REMOVE` in the API request. +* The `**POST** /api/rest/2.0/users/{user_identifier}/update` allows you to define locale settings, preferences, and other properties for a user object. + +== Version 9.3.0.cl, June 2023 + +The following Version Control [beta betaBackground]^Beta^ API endpoints are now available for the lifecycle management of content on your deployment environments: + +* `*POST* /api/rest/2.0/vcs/git/config/search` +* `*POST* /api/rest/2.0/vcs/git/commits/search` +* `*POST* /api/rest/2.0/vcs/git/config/create` +* `*POST* /api/rest/2.0/vcs/git/config/update` +* `*POST* /api/rest/2.0/vcs/git/config/delete` +* `*POST* /api/rest/2.0/vcs/git/branches/commit` +* `*POST* /api/rest/2.0/vcs/git/commits/{commit_id}/revert` +* `*POST* /api/rest/2.0/vcs/git/branches/validate` +* `*POST* /api/rest/2.0/vcs/git/commits/deploy` + +For more information, see xref:version_control.adoc[Version control and Git integration]. + +== Version 9.2.0.cl, May 2023 + +New endpoints:: + +* System ++ +** `POST /api/rest/2.0/system/config-update` + +Updates system configuration ++ +** `GET /api/rest/2.0/system/config-overrides` + +Gets system configuration overrides + +* Connections ++ +** POST /api/rest/2.0/connection/create + +Creates a data connection + +** `POST /api/rest/2.0/connection/search` + +Gets a list of data connections + +** `POST /api/rest/2.0/connection/update` + +Updates a data connection + +** `POST /api/rest/2.0/connection/delete` + +Deletes a data connection + +Enhancements:: + +* Support for runtime filters and runtime sorting of columns + +The following REST API v2.0 endpoints support applying xref:runtime-filters.adoc#_rest_api_v2_0_endpoints[runtime filters] and xref:runtime-sort.adoc[sorting column data]: ++ +** `POST /api/rest/2.0/report/liveboard` + +** `POST /api/rest/2.0/report/answer` + +* Search users by their favorites ++ +The `/api/rest/2.0/users/search` API endpoint allows searching users by their favorite objects and home Liveboard setting. + +* Ability to log in to a specific Org ++ +The `/api/rest/2.0/auth/session/login` API endpoint now allows ThoughtSpot users to log in to a specific Org context. -=== REST API TypeScript SDK +== Version 9.0.0.cl, February 2023 -ThoughtSpot provides the REST API TypeScript SDK (`@thoughtspot/rest-api-sdk`) to help developers interact programmatically with ThoughtSpot REST API v2 endpoints. The SDK is available on link:https://www.npmjs.com/package/@thoughtspot/rest-api-sdk[npm, window=_blank]. +The ThoughtSpot Cloud 9.0.0.cl release introduces the REST API v2.0 endpoints and Playground. For information about REST API v2.0 endpoints and Playground, see the following articles: -For information about how to install and use the SDK, see xref:rest-api-sdk-typescript.adoc[TypeScript SDK for REST APIs]. +* xref:rest-api-v2.adoc[REST API v2.0] +* xref:rest-api-v2-getstarted.adoc[Get started with REST API v2.0] +* xref:rest-api-v2-reference.adoc[REST API v2.0 reference] +* xref:rest-api-v1v2-comparison.adoc[REST API v1 and v2.0 comparison] From 8b5ea255151b2a95f1866d8dde183c3d5027a32d Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 17 Aug 2026 10:34:24 +0530 Subject: [PATCH 21/32] docs: add Visual Embed SDK 1.52.x changelog (SCAL-317516, SCAL-314461) --- modules/ROOT/pages/api-changelog.adoc | 1886 +++++++++++++++++++++++-- 1 file changed, 1804 insertions(+), 82 deletions(-) diff --git a/modules/ROOT/pages/api-changelog.adoc b/modules/ROOT/pages/api-changelog.adoc index 44d9a9a16..afdb900bf 100644 --- a/modules/ROOT/pages/api-changelog.adoc +++ b/modules/ROOT/pages/api-changelog.adoc @@ -10,83 +10,84 @@ This page documents the changes introduced in each release of the Visual Embed S == Version 1.52.x, September 2026 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| + [width="100%" cols="1,4"] + |==== + |[tag greenBackground]#NEW FEATURE# a| -[discrete] -===== Browser history management in full application embedding + [discrete] + ===== Browser history management in full application embedding -// SOURCE: SCAL-317516 -// SOURCE: thoughtspot/visual-embed-sdk/src/types.ts (master) + // SOURCE: SCAL-317516 + // SOURCE: thoughtspot/visual-embed-sdk/src/types.ts (master) -ThoughtSpot 26.9.0.cl introduces the `overrideHistoryState` configuration parameter for `AppEmbed`. When embedding ThoughtSpot in a host application, every internal ThoughtSpot navigation event (for example, switching between Liveboards or Answers) pushes a new entry onto the browser's history stack. This causes the browser *Back* button to step through ThoughtSpot's internal navigation before returning to the host application's prior page. + ThoughtSpot 26.9.0.cl introduces the `overrideHistoryState` configuration parameter for `AppEmbed`. When embedding ThoughtSpot in a host application, every internal ThoughtSpot navigation event (for example, switching between Liveboards or Answers) pushes a new entry onto the browser's history stack. This causes the browser *Back* button to step through ThoughtSpot's internal navigation before returning to the host application's prior page. -Setting `overrideHistoryState: true` converts all ThoughtSpot internal `pushState` calls to `replaceState`, preventing ThoughtSpot navigation from polluting the host application's browser history stack. + Setting `overrideHistoryState: true` converts all ThoughtSpot internal `pushState` calls to `replaceState`, preventing ThoughtSpot navigation from polluting the host application's browser history stack. -[source,JavaScript] ----- -import { AppEmbed, init, AuthType } from '@thoughtspot/visual-embed-sdk'; + [source,JavaScript] + ---- + import { AppEmbed, init, AuthType } from '@thoughtspot/visual-embed-sdk'; -init({ - thoughtSpotHost: 'https://.thoughtspot.cloud', - authType: AuthType.TrustedAuthToken, - getAuthToken: () => fetch('/ts-token').then(r => r.json()).then(d => d.token), -}); + init({ + thoughtSpotHost: 'https://.thoughtspot.cloud', + authType: AuthType.TrustedAuthToken, + getAuthToken: () => fetch('/ts-token').then(r => r.json()).then(d => d.token), + }); -const embed = new AppEmbed('#embed-container', { - frameParams: { width: '100%', height: '100%' }, - overrideHistoryState: true, // <1> -}); + const embed = new AppEmbed('#embed-container', { + frameParams: { width: '100%', height: '100%' }, + overrideHistoryState: true, // <1> + }); -embed.render(); ----- -<1> When set to `true`, ThoughtSpot replaces rather than pushes browser history entries during internal navigation. + embed.render(); + ---- + <1> When set to `true`, ThoughtSpot replaces rather than pushes browser history entries during internal navigation. -[NOTE] -==== -`overrideHistoryState` is available on `AppEmbed` only. It is not supported on `LiveboardEmbed`, `SearchEmbed`, or `SpotterEmbed`. Validate behavior across Chrome, Firefox, and Safari before enabling in production. -==== + [NOTE] + ==== + `overrideHistoryState` is available on `AppEmbed` only. It is not supported on `LiveboardEmbed`, `SearchEmbed`, or `SpotterEmbed`. Validate behavior across Chrome, Firefox, and Safari before enabling in production. + ==== -For more information, see xref:full-app-embed.adoc[Full application embedding]. + For more information, see xref:full-app-embed.adoc[Full application embedding]. -|[tag greenBackground]#NEW FEATURE# a| + |[tag greenBackground]#NEW FEATURE# a| -[discrete] -===== Collections in left navigation panel + [discrete] + ===== Collections in left navigation panel -// SOURCE: SCAL-314461 + // SOURCE: SCAL-314461 -The `HomeLeftNavItem.Collections` enum value is now available in the Visual Embed SDK. Embed developers can include *Collections* as a selectable navigation option in the embedded left navigation panel for full application embeds. When enabled, end users of the embedded application can navigate to *Collections* from the left navigation panel. + The `HomeLeftNavItem.Collections` enum value is now available in the Visual Embed SDK. Embed developers can include *Collections* as a selectable navigation option in the embedded left navigation panel for full application embeds. When enabled, end users of the embedded application can navigate to *Collections* from the left navigation panel. -[source,JavaScript] ----- -import { AppEmbed, HomeLeftNavItem, init, AuthType } from '@thoughtspot/visual-embed-sdk'; - -init({ - thoughtSpotHost: 'https://.thoughtspot.cloud', - authType: AuthType.TrustedAuthToken, - getAuthToken: () => fetch('/ts-token').then(r => r.json()).then(d => d.token), -}); - -const embed = new AppEmbed('#embed-container', { - frameParams: { width: '100%', height: '100%' }, - leftNavOrder: [ - HomeLeftNavItem.Home, - HomeLeftNavItem.Liveboards, - HomeLeftNavItem.Answers, - HomeLeftNavItem.Collections, // <1> - ], -}); - -embed.render(); ----- -<1> Include `HomeLeftNavItem.Collections` in the `leftNavOrder` array to show Collections in the embedded left navigation panel. + [source,JavaScript] + ---- + import { AppEmbed, HomeLeftNavItem, init, AuthType } from '@thoughtspot/visual-embed-sdk'; -For more information, see xref:full-app-customize.adoc[Customize full application embedding]. + init({ + thoughtSpotHost: 'https://.thoughtspot.cloud', + authType: AuthType.TrustedAuthToken, + getAuthToken: () => fetch('/ts-token').then(r => r.json()).then(d => d.token), + }); -|==== + const embed = new AppEmbed('#embed-container', { + frameParams: { width: '100%', height: '100%' }, + leftNavOrder: [ + HomeLeftNavItem.Home, + HomeLeftNavItem.Liveboards, + HomeLeftNavItem.Answers, + HomeLeftNavItem.Collections, // <1> + ], + }); + + embed.render(); + ---- + <1> Include `HomeLeftNavItem.Collections` in the `leftNavOrder` array to show Collections in the embedded left navigation panel. + + For more information, see xref:full-app-customize.adoc[Customize full application embedding]. + + |==== + == Version 1.51.x, August 2026 [width="100%" cols="1,4"] @@ -235,46 +236,1767 @@ New events and action IDs;; * `EmbedEvent.DownloadLiveboardAsContinuousPDF` + Emits when the download action is triggered. * `HostEvent.DownloadLiveboardAsContinuousPDF` + -Triggers a download of the Liveboard as a continuous PDF. +Programmatically triggers the download action to export the PDF with a continuous Liveboard layout. * `Action.DownloadLiveboardAsContinuousPDF` + -Action ID to show or hide the continuous PDF download option. +Action ID to control the visibility of download action that exports continuous PDFs. + +Liveboard download actions:: + +The following action IDs are introduced in the SDK for the download buttons at the Liveboard level: + +* `Action.DownloadLiveboard` + +* `Action.DownloadLiveboardAsXlsx` + +* `Action.DownloadLiveboardAsCsv` + +Test email for Liveboard scheduled jobs:: + +The SDK introduces the `isSendNowLiveboardSchedulingEnabled` to enable the **Send now** option for the Liveboard scheduled jobs. This option allows Liveboard users to send a test email notification to either themselves or the intended recipients of the Liveboard scheduled alerts. + +New events and action IDs;; + +* `EmbedEvent.SendTestScheduleEmail` + +Emits when *Send now* button is clicked. +* `HostEvent.SendTestScheduleEmail` + +Programmatically triggers the Send now action to send a test email notification for a Liveboard scheduled job. +* `Action.SendTestScheduleEmail` + +Action ID to disable, show, or hide the **Send now** button on the Liveboard schedule page. + +|[tag greenBackground]#NEW FEATURE# a| + +[discrete] +===== Spotter embedding + +The SDK introduces the following action IDs to control the visibility of specific UI components in chat panel of the embedded Spotter interface: -Org-level Liveboard filter settings;; -Administrators can configure Liveboard filter settings for all users in an Org using the new org-level filter configuration option. For more information, see xref:embed-pinboard.adoc#org-filter-config[Configure Liveboard filter settings for an Org]. +* `Action.SpotterChatConnectorResources` + +For the connector resources section in the Spotter chat interface. +* `Action.SpotterChatConnectors` + +For the connectors panel section in the Spotter chat interface. +* `Action.SpotterChatModeSwitcher` + +For the mode switcher in the Spotter chat interface. |[tag greenBackground]#NEW FEATURE# a| + [discrete] -===== Search embedding -* The `SearchEmbed` now supports the `dataPanelCustomGroupsAccordionInitialState` attribute to control the initial expanded or collapsed state of custom groups in the data panel. -* New action IDs to show or hide Edit and Delete buttons for saved Answers in the Search interface: -** `Action.EditAnswer` -** `Action.DeleteAnswer` +===== Event handling +Note the following changes: + +EmbedEvent:: + +* `EmbedEvent.Subscribed` + +The SDK introduces the `EmbedEvent.Subscribed` to emit an event when a HostEvent listener is registered. You can use this event to dispatch host events during the initial load without race conditions. This is particularly useful for Spotter, where host events such as `HostEvent.ResetSpotterConversation` may be triggered immediately after load. +* `EmbedEvent.Error` + +The `EmbedEvent.Error` now fires on HostEvent payload validation failures. + +HostEvent:: +* `HostEvent.GetExportRequestForCurrentPinboard` [.version-badge.breaking]#Breaking# + +The response payload of the `GetExportRequestForCurrentPinboard` passthrough +host event has been updated to include a `type` discriminator field, making it +consistent with the shape of other host event responses. It now returns `{ data: { v2Content }, type }` instead of `{ v2Content }` directly. This enhancement introduces a breaking change for any code that reads `result.v2Content` directly. Update your integration workflows to use `result.data.v2Content`. + |[tag greenBackground]#NEW FEATURE# a| + [discrete] -===== Full application embedding -The `AppEmbed` configuration now supports `disableMultipleOrgsGlobalSearch` to disable the global search scope across multiple Orgs in embedded full application mode. +===== Personalized View selection via host event + +* `EmbedEvent.ChangePersonalizedView` + +Emits when a user selects a different Personalized View on an embedded Liveboard, or resets to the default view. For more information, see xref:EmbedEvent.adoc#_changepersonalizedview[EmbedEvent reference documentation]. + +* `HostEvent.SelectPersonalizedView` + +The SDK introduces `HostEvent.SelectPersonalizedView` to programmatically switch the active Personalized View on an embedded Liveboard from the host application. For more information, see xref:HostEvent.SelectPersonalizedView[HostEvent reference documentation]. + +⚠️Deprecated events and action IDs️:: +The following events are deprecated and replaced with new event IDs. + +* `EmbedEvent.UpdatePersonalisedView`. Use `EmbedEvent.UpdatePersonalizedView`. +* `EmbedEvent.SavePersonalisedView`. Use `EmbedEvent.SavePersonalizedView`. +* `EmbedEvent.DeletePersonalisedView`. Use `EmbedEvent.DeletePersonalizedView`. +* `HostEvent.ResetLiveboardPersonalisedView`. Use `HostEvent.ResetLiveboardPersonalizedView`. +* `Action.PersonalisedViewsDropdown`. Use `Action.PersonalizedViewsDropdown`. +* `Action.OrganiseFavourites`. Use `Action.OrganizeFavorites`. |==== + == Version 1.47.x, April 2026 +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| **Spotter chat history sidebar customization** + +The SDK introduces the `SpotterSidebarViewConfig` interface and the `spotterSidebarConfig` object with configuration controls to customize the appearance and contents of the chat history panel. Developers can use the following properties in the `spotterSidebarConfig` object to enable or disable chat history panel and customize the contents of the sidebar when enabled: + +* `enablePastConversationsSidebar` + +Controls the visibility of the past conversations sidebar panel. The chat history panel is disabled by default in embed view. When this property in `spotterSidebarConfig` is specified, it takes precedence over the standalone `enablePastConversationsSidebar` setting, which is deprecated from v1.47.0. + +* `spotterSidebarTitle` + +Allows adding custom title text for the sidebar header. + +* `spotterSidebarDefaultExpanded` + +Sets the default state of the sidebar to expanded or collapsed view. + +* `spotterChatRenameLabel` + +Allows setting a custom label for the **Rename** action in the conversation edit menu. + +* `spotterChatDeleteLabel` + +Allows setting a custom label for the **Delete** action in the conversation edit menu. + +* `spotterDeleteConversationModalTitle` + +Allows editing the title text of the chat delete confirmation modal. + +* `spotterPastConversationAlertMessage` + +Sets a custom message text for the past conversation banner alert. Defaults to the translated alert message. + +* `spotterBestPracticesLabel` + +Allows customizing the label for the best practices button in the sidebar footer. + +* `spotterDocumentationUrl` + +The best practices documentation link shown in the sidebar footer. You can customize the link by specifying the full URL. + +* `spotterConversationsBatchSize` + +Sets the number of conversations to fetch per batch when loading conversation history. Default is `30`. + +* `spotterNewChatButtonTitle` + +Allows customizing the title text for the **New chat** button in the sidebar. + +|[tag redBackground]#DEPRECATED# a| **Standalone `enablePastConversationsSidebar` attribute in Spotter embed** + +The standalone `enablePastConversationsSidebar` property on `SpotterEmbedViewConfig` and `AppViewConfig` is deprecated from SDK 1.47.0 and ThoughtSpot 26.4.0.cl. + +Use `enablePastConversationsSidebar` in the `spotterSidebarConfig` instead. When both are defined, the property in the `spotterSidebarConfig` object takes precedence. + +[source,javascript] +---- +// Deprecated +enablePastConversationsSidebar: false, + +// Recommended +spotterSidebarConfig: { + enablePastConversationsSidebar: true, + //... other config properties +} +---- + +|[tag greenBackground]#NEW FEATURE# a| **Spotter chat UI branding** + +The SDK introduces the `SpotterChatViewConfig` interface for customizing branding in Spotter tool response cards. You can pass these parameters as the `spotterChatConfig` object properties in `SpotterEmbed`, `AppEmbed`, or `LiveboardEmbed` where Spotter interface is used. + +* `hideToolResponseCardBranding` + +When set to `true`, hides the ThoughtSpot logo and icon in tool response cards. The branding label prefix is controlled separately via `toolResponseCardBrandingLabel`. Default value is `false`. + +* `toolResponseCardBrandingLabel` + +Custom label to replace the `ThoughtSpot` prefix in tool response cards. Set to an empty string (`''`) to hide the prefix entirely. + +[NOTE] +==== +These settings do not affect the external MCP tool branding. +==== + +|[tag greenBackground]#NEW FEATURE# a|**Liveboard embed enhancements** + +Personalized Liveboard view:: + +The `personalizedViewId` property allows embedding a saved personalized view of a Liveboard. A personalized view is a saved configuration that includes specific filter selections and changes applied by a user. To embed a personalized view of Liveboard, specify the GUID of the saved personalized view to load along with `liveboardId`. + +Centralized Liveboard filter setting:: + +When set to `true`, the `isCentralizedLiveboardFilterUXEnabled` enables displaying a unified modal to manage and update multiple filters at once, replacing the older individual filter interactions. This feature is disabled by default on ThoughtSpot Embedded instances. + +|[tag greenBackground]#NEW FEATURE# a|**Option to include current period in rolling date filters** + +If the current period inclusion in rolling date filters feature is enabled on your instance, the rolling date filters options such as **Last ** and **Next ** for the Liveboards and Answers in the embed view will allow you to include current period. For example, when you define a date range such as "Last 2 months", the date filter interface displays the **Include this month** checkbox. +To disable this feature, use the `isThisPeriodInDateFiltersEnabled` setting. To hide, show, or disable this option in the embed view, use the action ID, `Action.IncludeCurrentPeriod`. +|==== + + +== Version 1.46.x, March 2026 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| **Host events with page context framework** + +The Visual Embed SDK introduces the HostEvent V2 framework for improved handling and execution of host events in embedded ThoughtSpot experiences with multi-layer UI interactions. The v2 framework supports the page context feature, which tracks the top-most active layer in the user's current context. Developers can use this feature to route events based on the user's current context or set a specific target context for precise and predictable handling of host events. + +* To enable this feature, set `useHostEventsV2` to `true`. +* To retrieve the current context, use `getCurrentContext()`. +* To set a target context for a host event, use xref:ContextType.adoc[ContextType]. + +For more information, refer to the xref:events-context-aware-routing.adoc[Host events documentation]. + +|[tag redBackground]#DEPRECATED# a| **dataPanelV2** + +The `dataPanelV2` parameter is deprecated and can no longer be used to switch between the classic and new data panel experience. By default, the new data panel v2 experience is enabled on all ThoughtSpot embedded instances. + +|[tag greenBackground]#NEW FEATURE# a| **Spotter experience** +The SDK includes the following parameters, action IDs, and events to customize the Spotter embed experience. + +Chat history sidebar customization:: + +//* `SpotterSidebarViewConfig` interface with configuration parameters for customizing the visibility and appearance of the chat history sidebar. +//* `spotterSidebarConfig` properties for customizing the appearance and available options in the chat history sidebar. +* Action IDs for customizing the visibility and status of actions in the embedded Spotter interface: +** `Action.DataModelInstructions` for the data model instructions icon. +** `Action.SpotterSidebarHeader` for the chat history sidebar header +** `Action.SpotterSidebarFooter` for the chat history sidebar footer +** `Action.SpotterSidebarToggle` for the chat history toggle that expands or collapses the sidebar. +** `Action.SpotterNewChat` for the new chat icon in the chat history sidebar. +** `Action.SpotterPastChatBanner` for the banner in the chat history sidebar. +** `Action.SpotterChatMenu` for the chat menu component in the chat history sidebar. +** `Action.SpotterChatRename` for **Rename** action in the chat menu of a saved chat. +** `Action.SpotterChatDelete` for **Delete** action in the chat menu of a saved chat. +//** `Action.SpotterDocs` for best practices documentation icon in the chat history sidebar. + +Events:: +* `HostEvent.DataModelInstructions` + +Opens the Data Model instructions modal. +* `EmbedEvent.DataModelInstructions` + +Is emitted when a user clicks the Data Model instructions icon in the Spotter interface. +* `EmbedEvent.SpotterConversationRenamed` + +Is emitted when a user renames a saved chat. +* `EmbedEvent.SpotterConversationDeleted` + +Is emitted when a saved chat is deleted. +* `EmbedEvent.SpotterConversationSelected` + +Is emitted when a saved chat is selected in the chat history sidebar. + +|[tag greenBackground]#NEW FEATURE# | `enableLinkOverridesV2` + + +Use this configuration setting to override ThoughtSpot URLs on hover or when opening in a new tab. This is recommended over the earlier `linkOverride` flag for a better user experience. + +|[tag greenBackground]#NEW FEATURE# a| **Liveboard experience enhancements** + +* The `isLiveboardXLSXCSVDownloadEnabled` attribute adds XLSX and CSV to the available Liveboard download formats. +* The `isGranularXLSXCSVSchedulesEnabled` attribute allows you to include the entire Liveboard, specific visualizations, or only tables and pivot tables in the XLSX and CSV schedules. +|==== + +== Version 1.45.0, February 2026 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| **Spotter enhancements** + +You can now embed the Spotter 3 experience in your application and use features such as Auto mode for automatic data model selection, chat history, and a new chat prompt interface. + +* To enable the new chat prompt interface, set `updatedSpotterChatPrompt` to `true`. +* To use Auto mode, set the `worksheetId` to `auto_mode`. +* To enable Chat history, set `enablePastConversationsSidebar` to `true`. + +For more information, see xref:embed-spotter.adoc[Embedding Spotter] and xref:embed-ai-analytics.adoc#_feature_status_and_availability_in_embed_mode[Features available with Spotter 3 experience]. + +Events:: + +* `EmbedEvent.AddToCoaching` for the *Add to Coaching* workflow in a Spotter conversation session +* `HostEvent.AddToCoaching` to trigger the *Add to Coaching* action in a Spotter conversation session. +* `HostEvent.StartNewSpotterConversation` to trigger the action to start a new chat session with Spotter. + +[NOTE] +==== +On Spotter embed deployments running version 26.2.0.cl or later, the *Add to Coaching* feature is enabled by default. To disable or hide the *Add to Coaching* button, use the xref:Action.adoc#_inconversationtraining[InConversationTraining] action ID. +==== + +|[tag greenBackground]#NEW FEATURE# a| **Liveboard experience enhancements** + + +Styling and grouping:: + +* The `isLiveboardStylingAndGrouping` attribute, used to enable the Liveboard styling and grouping feature, is now replaced with `isLiveboardMasterpiecesEnabled`. While your existing configuration with the deprecated `isLiveboardStylingAndGrouping` attribute continues to work, we recommend switching to the new configuration setting. +* The following action IDs are now available to show, disable, or hide the grouping menu actions on a Liveboard: +** `Action.MoveToGroup` for the **Move to Group** menu action. +** `Action.MoveOutOfGroup` for the **Move out of Group** menu action. +** `Action.CreateGroup` for the *Create Group* menu action. +** `Action.UngroupLiveboardGroup` for the **Ungroup Liveboard Group** menu action. + +Filter chip masking:: +The `showMaskedFilterChip` boolean parameter is now available to control the visibility of masked filter chips on a Liveboard. When set to `true`, if a Liveboard is shared with a user who has restricted access due to column-level security, the filter chip corresponding to those inaccessible columns will be displayed as masked to that user. When set to `false`, the filter chip for inaccessible columns will not be visible to the user. ++ +For more information, see link:https://docs.thoughtspot.com/cloud/latest/security-data-object#csr-liveboard[Column security rules on Liveboards]. ++ +The `showMaskedFilterChip` setting is also available in full application embedding. + +|[tag greenBackground]#NEW FEATURE# a| **Publishing objects** + +The following action IDs are available for the data publishing menu actions in the *Data workspace* page: + +* `Action.Publish` for *Publish* +* `Action.ManagePublishing` for *Manage publishing* +* `Action.Unpublish` for *Unpublish* +* `Action.Parameterize` for *Parameterize* +|[tag greenBackground]#NEW FEATURE# a| **Error handling improvements** + +To handle errors in the embedding workflows, the SDK includes the following features: + +* `ErrorDetailsTypes` enum for categorizing error types, such as `API`, `VALIDATION_ERROR`, and `NETWORK`. +* `EmbedErrorCodes` enum with specific error codes for programmatic error handling. +* `EmbedErrorDetailsEvent` interface for structured error event handling. + +For more information, see link:https://developers.thoughtspot.com/docs/Enumeration_EmbedErrorCodes[EmbedErrorCodes] and link:https://developers.thoughtspot.com/docs/Enumeration_ErrorDetailsTypes[ErrorDetailsTypes]. +|==== + +== Version 1.44.x, January 2026 + +[width="100%" cols="1,4"] +|==== + +|[tag redBackground]#DEPRECATED# | **Use `minimumHeight` instead of `defaultHeight`** + + +The `defaultHeight` parameter is deprecated in Visual Embed SDK v1.44.2 and later. +To set the minimum height of the embed container for ThoughtSpot components such as a Liveboard, use the `minimumHeight` attribute instead. + +|[tag greenBackground]#NEW FEATURE# a| *Intercepting API calls* + +The SDK provides the following attributes to intercept API calls and handle interception via events and custom workflows: + +//* `enableApiIntercept` + +//When set to true, enables the feature on your ThoughtSpot embed. +* `interceptUrls` + +Allows configuring which API calls to intercept. +* `interceptTimeout` + +Sets the timeout duration for handling interception. +* `isOnBeforeGetVizDataInterceptEnabled` + +When set to true, it enables use of `EmbedEvent.OnBeforeGetVizDataIntercept` to emit and intercept search execution calls initiated by users and implement custom logic or workflows to allow or restrict search execution. +* `EmbedEvent.ApiIntercept` + +Emits when an API call matching the conditions defined in `interceptUrls` is detected. + +For more information, see xref:api-intercept.adoc[Intercept API calls and search requests]. +|==== + + +== Version 1.43.0, November 2025 +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| *Code-based custom actions* + +The following enumerations are available for code-based custom actions: + +* `CustomActionTarget` + +To define the target object for the custom action, such as on a Liveboard, visualization, Answer, or in Spotter. +* `CustomActionsPosition` + +To define the position of the custom action in the target object, such as primary menu, **More** options menu image:./images/icon-more-10px.png[the more options menu], or the contextual menu. +|[tag greenBackground]#NEW FEATURE# | *Attribute to set Parameter chip visibility during overrides* + +The `HostEvent.UpdateParameters` event now supports configuring the `isVisibleToUser` attribute to show or hide the Parameter chips after an override. For more information, see xref:runtime-parameters.adoc#_show_or_hide_parameter_chips_in_embedded_sessions[Show or hide Parameter chips in embedded sessions]. +|==== + +== Version 1.42.0, October 2025 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a|*Runtime overrides in Spotter embed* + +The Visual Embed SDK now supports runtime overrides in Spotter embed. + +* To apply runtime filters, use the `runtimeFilters` object +* To apply runtime Parameters, use the `runtimeParameters` object. + +|[tag greenBackground]#NEW FEATURE# a|*PNG images in Liveboard schedule notifications* + +To enable embedding PNG images of Liveboards in scheduled job notifications sent to subscribers, the SDK provides the `isPNGInScheduledEmailsEnabled` boolean parameter. When set to true, scheduled emails will include a PNG image of the Liveboard. + +The SDK also provides the following action IDs: + +* `Action.PngScreenshotInEmail` + +Adds the option to include a PNG screenshot in the notification email body when scheduling emails in ThoughtSpot. +* `Action.RemoveAttachment` + +Allows the user to remove an attachment from the email configuration in the schedule email dialog. +|[tag greenBackground]#NEW FEATURE# a|*Spotter embed* + +Action IDs:: +The following action IDs are available for Spotter embedding and are currently supported only in the `hiddenActions` array: + +* `Action.SpotterWarningsBanner` + +Action ID to control the visibility of the Spotter warnings banner in the UI. This banner displays general warnings or informational messages related to Spotter results or queries. +* `Action.SpotterWarningsOnTokens` + +Action ID to control the visibility of warning indicators on individual Spotter tokens parsed from a Spotter query. +* `Action.SpotterTokenQuickEdit` + +Action ID to enable or disable the link:https://docs.thoughtspot.com/cloud/latest/spotter-getting-started#quick-edits[quick edit functionality^] for Spotter tokens. +|==== + +== Version 1.41.0, September 2025 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a|*React component for Spotter Agent embed* + +The Visual Embed SDK now supports embedding Spotter Agent feature without a body or Spotter interface in a React app. For ease of implementation, the SDK also provides a custom React hook, `useSpotterAgent`. + +For more information, see xref:embed-ts-react-app.adoc#_embed_spotter_agent_in_your_own_app[Spotter Agent embedding in a React app]. + +|[tag greenBackground]#NEW FEATURE# a|*Event handlers for Spotter embed* + +The following event handlers are now available for Spotter embed: + +* `EmbedEvent.SpotterInit` + +Fires when Spotter embed component rendering is initialized. +* `EmbedEvent.QueryChanged` + +Fires when the Spotter query is updated by the user. +* `HostEvent.AskSpotter` + +Triggers *Ask Spotter* action for visualizations. +* `HostEvent.GetParameters` + +Triggers the action to fetch runtime Parameters applied on a visualization. +* `HostEvent.UpdateParameters` + +Triggers the action to update runtime Parameters for a Spotter-generated Answer. +* `HostEvent.GetTML` + +Triggers the action to get TML representation of a Spotter-generated Answer. + +For more information, see xref:EmbedEvent.adoc[EmbedEvent] and xref:HostEvent.adoc[HostEvent]. + +|[tag greenBackground]#NEW FEATURE# a|*Event handlers for Spotter Agent embed* + +You can now use the following host events in Spotter Agent embedding: + +- `HostEvent.DownloadAsCsv` + +Triggers the action to download a Spotter-generated Answer in CSV format. +- `HostEvent.DownloadAsPng` + +Triggers the action to download a Spotter-generated Answer in PNG format. +- `HostEvent.DownloadAsXlsx` + +Triggers the action to download a Spotter-generated Answer in XLSX format. +- `HostEvent.DownloadAsPdf` + +Triggers the action to download the PDF version of a Spotter-generated Answer. +- `HostEvent.Pin` + +Triggers the action to add a Spotter-generated Answer to a Liveboard. +- `HostEvent.Save` + +Triggers the *Save* action for a Spotter-generated Answer. + +For more information, see xref:HostEvent.adoc[HostEvent]. + +|[tag greenBackground]#NEW FEATURE# a| *Lazy loading of visualizations on an embedded Liveboard* + +You can now use the `lazyLoadingForFullHeight` parameter with the `fullHeight` to progressively load visualizations on an embedded Liveboard. When both these attributes are enabled, only the visualizations in the current viewport are loaded initially, while the other visualizations load as the user scrolls the Liveboard page. + +You can also set the margin property for lazy loading to define when the visualization should load. + +For more information, see xref:lazy-loading-fullheight.adoc[Lazy loading of visualizations in an embedded Liveboard]. + +|[tag greenBackground]#NEW FEATURE# a| *Full application embed* + + +You can now enable the persona-based left navigation panel and home page experience on your ThoughtSpot instance. This feature is disabled by default on ThoughtSpot instances and is available for Early Access. When it's enabled on your ThoughtSpot instance, you can roll out the new experience on embedding applications by configuring the xref:AppViewConfig.adoc#_discoveryexperience[`discoveryExperience`] attribute. + +When enabled, the left navigation panel organizes the application menu into persona-based contextual sections. For example, the *Insights* icon for business users, the *Data Workspace* icon for Analysts and Data engineers, and the *Develop* icon for developers. Your application users can navigate to each option using the tabs in the left navigation panel. The new interface also provides a slider to allow users to view or hide the left navigation panel. +|==== + +== Version 1.40.0, July 2025 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| *Fullscreen presentation mode controls for embedded Liveboards and visualizations* + +Developers can now control whether a visualization or Liveboard can be presented in full screen mode using the `disableFullscreenPresentation` attribute. By default, the full screen mode is disabled on embedded Liveboards and visualizations. +|[tag greenBackground]#NEW FEATURE# a| *PDF download settings* + +Developers can now control the display of *Include cover page* and *Include filter page(s)* options on the Download PDF dialog for Liveboards. The *Include cover page* and *Include filter page(s)* options are disabled by default on ThoughtSpot instances. When this feature is enabled, developers can use the `coverAndFilterOptionInPDF` attribute to show or hide these options for the Liveboard users in their embedding app. + +|[tag greenBackground]#NEW FEATURE# a| *Parameter for overriding a default primary action* + + +If Spotter is enabled on your instance, the *Spotter* button appears by default as the primary action on embedded Liveboard charts; if Spotter is not enabled, the *Explore* button is set as the primary action. If you want to replace the primary action with a different action, you can now use the `primaryAction` attribute. + +For more information, see xref:embed-actions.adoc#_override_default_primary_actions[Override default primary action]. + +|[tag greenBackground]#NEW FEATURE# a| *Full application embed experience enhancements* + + +The SDK now includes the `hideObjectSearch` property, which allows developers to hide the object search button in the navigation bar when embedding the full application. + +|[tag greenBackground]#NEW FEATURE# a| *Host events* + + +In this version, the SDK introduces the following host event handlers: + +- `HostEvent.ExitPresentMode` + +Triggers the exit action that allows users to exit the Liveboard or visualization present mode. +- `HostEvent.SpotterSearch` + +Triggers a search operation for the specified query string in Spotter embed. +- `HostEvent.PreviewSpotterData` + +Triggers the *Preview data* action that shows the data used for Spotter conversations. +- `HostEvent.ResetSpotterConversation` + +Triggers the *Reset* action to reset a Spotter conversation. +- `HostEvent.EditLastPrompt` + +Triggers the edit prompt action. +- `HostEvent.DeleteLastPrompt` + +Triggers the delete prompt action. + +For more information, see xref:HostEvent.adoc[HostEvent]. + +|[tag greenBackground]#NEW FEATURE# a|*Events support for Spotter embed* + +You can now use the following host events in Spotter embed: + +- `HostEvent.DownloadAsCsv` +- `HostEvent.DownloadAsPng` +- `HostEvent.DownloadAsXlsx` +- `HostEvent.Edit` +//- `HostEvent.GetParameters` +//- `HostEvent.GetTML` +- `HostEvent.MakeACopy` +- `HostEvent.Pin` +- `HostEvent.Save` + +For more information, see xref:HostEvent.adoc[HostEvent]. + +|[tag greenBackground]#NEW FEATURE# a| *Lazy loading with full height* + +The SDK introduces `lazyLoadingForFullHeight` parameter, which enables progressive loading of visualizations on an embedded Liveboard. +This parameter works in conjunction with the `fullHeight` attribute. When both these attributes are enabled, only the visualizations in the current viewport are loaded initially, while the other visualizations load as the user scrolls the Liveboard page. + +[NOTE] +==== +To use these attributes effectively in embedded applications, your ThoughtSpot instance must be upgraded to version 10.12.0.cl or later. +==== +|==== + + +== Version 1.39.0, July 2025 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| *Spotter embed components with new names* + +The following Spotter embed components are now deprecated and replaced with new components in the SDK and Visual Embed Playground: + +* `ConversationEmbed` + +Replaced with `SpotterEmbed` +* `ConversationViewConfig` + +Replaced with `SpotterEmbedViewConfig` +* `BodylessConversation` + +Replaced with `SpotterAgentEmbed` +* `BodylessConversationViewConfig` + +Replaced with `SpotterAgentEmbedViewConfig` + +The deprecated components with old names in the existing Spotter embed implementations will continue to function until further notice. For code samples with new component names, see xref:embed-spotter.adoc[Spotter embed documentation]. + +|[tag greenBackground]#NEW FEATURE# a| *Action ID for Spotter in-conversation training* + +For ThoughtSpot instances that have the new Spotter in-conversation training workflow enabled, the SDK provides the action ID `Action.InConversationTraining` to manage the visibility of the *Add to Coaching* button on Answers generated from Spotter prompts. + +[NOTE] +The *Add to Coaching* feature is currently in beta and is turned off by default on embed deployments. To enable this feature on your instance, contact ThoughtSpot Support. + +|[tag greenBackground]#NEW FEATURE# a|*Events support for Spotter embed* + +New embed events:: + +- `EmbedEvent.ExitPresentMode` + +Emits when a user exits the Liveboard or visualization presentation mode. +- `EmbedEvent.LastPromptDeleted` + +Emits when a query prompt in Spotter embed is deleted. +- `EmbedEvent.LastPromptEdited` + +Emits when a query prompt in Spotter embed is edited. +- `EmbedEvent.ResetSpotterConversation` + +Emits when a Spotter query is reset. +- `EmbedEvent.PreviewSpotterData` + +Emits when a user clicks the Preview data button in the Spotter conversation panel. +- `EmbedEvent.SpotterQueryTriggered` +Emits when a Spotter query is triggered. + +The following embed events are also supported in Spotter embed: + +- `EmbedEvent.AddRemoveColumns` +- `EmbedEvent.AnswerChartSwitcher` +- `EmbedEvent.AuthExpire` +- `EmbedEvent.AuthInit` +- `EmbedEvent.CopyToClipboard` +- `EmbedEvent.CustomAction` +- `EmbedEvent.Data` +- `EmbedEvent.DataSourceSelected` +- `EmbedEvent.DialogClose` +- `EmbedEvent.DialogOpen` +- `EmbedEvent.Download` +- `EmbedEvent.DownloadAsCsv` +- `EmbedEvent.DownloadAsPng` +- `EmbedEvent.DownloadAsXlsx` +- `EmbedEvent.DrillDown` +- `EmbedEvent.DrillExclude` +- `EmbedEvent.DrillInclude` +- `EmbedEvent.Edit` +- `EmbedEvent.Error` +- `EmbedEvent.Load` +- `EmbedEvent.Pin` +- `EmbedEvent.Save` +- `EmbedEvent.TableVizRendered` +- `EmbedEvent.VizPointClick` +- `EmbedEvent.VizPointDoubleClick` +- `EmbedEvent.VizPointRightClick` + +For more information, see xref:EmbedEvent.adoc[EmbedEvent]. + +|==== + +== Version 1.38.0, June 2025 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| *String IDs for text customization* + +Developers can now customize a specific occurrence of a visible text string in the ThoughtSpot UI using the `stringIDs` object in the customization interface. + +To locate the string IDs, SDK provides the `exposeTranslationIds` attribute. By setting `exposeTranslationIds` to `true` in the Playground, you can find the string ID of the UI text and use it in your customization code. + +Additionally, the SDK provides the `StringIDsUrl` attribute to allow using a JSON file with string IDs and custom strings to override the visible text in the UI. + +For more information, see xref:customize-text-strings.adoc[Customize text strings]. + +|[tag greenBackground]#NEW FEATURE# a| *Hide columns on list pages* + + +In full app embedding, you can now hide the following columns on the *Liveboards* and *Answers* listing pages using the `hiddenListColumns` array: + +* *Author* + +`hiddenListColumns: [ListPageColumns.Author]` +* *Favorite* + +`hiddenListColumns: [ListPageColumns.Favourite]` +* *Last modified* + +`hiddenListColumns: [ListPageColumns.DateSort]` +* *Tags* + +`hiddenListColumns: [ListPageColumns.Tags]` +* *Share* + +`hiddenListColumns: [ListPageColumns.Share]` + + +For more information, see xref:full-app-customize.adoc#_hide_columns_on_list_pages_new_experience[Customize full application embed]. +|==== + +== Version 1.37.0, April 2025 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| +The SDK now provides the `customVariablesForThirdPartyTools` setting to pass custom variables when integrating third-party tools and running custom scripts in your embed. Developers can define this object in the **init()** function and add variables as key-value pairs. +This feature is available only if third-party integration is enabled on your instance and the script hosting domain URL is added to the CSP allowlist. + +For more information, see xref:3rd-party-script.adoc[Integrate third-party tools and allow custom scripts]. + +|[tag greenBackground]#NEW FEATURE# a| +You can now exclude search token string from the application URL by setting `excludeSearchTokenStringFromURL` to `true` in your embed with ThoughtSpot token-based Search or Search bar. + +|[tag greenBackground]#NEW FEATURE# a| This version of the SDK supports the following embed and host events: + +Embed Events:: + +* `EmbedEvent.TableVizRendered` + +Emits when a table visualization is rendered in the ThoughtSpot embedded app. You can also use this event as a hook to trigger host events such as `HostEvent.TransformTableVizData` on the table visualization. For more information, see the link:https://developers.thoughtspot.com/docs/Enumeration_EmbedEvent#_tablevizrendered[SDK reference documentation]. + +* `EmbedEvent.CreateLiveboard` + +Emits when a Liveboard is created. + +Host Events:: + +* `HostEvent.TransformTableVizData` + +Triggers the table visualization re-render with the updated data. You can use this event in conjunction with `EmbedEvent.TableVizRendered` to apply the modifications to table visualization payload. + +* `HostEvent.Remove` + +Triggers the *Delete* action on a Liveboard. +|==== + +== Version 1.36.0, February 2025 + [width="100%" cols="1,4"] |==== |[tag greenBackground]#NEW FEATURE# a| -[discrete] -===== Spotter embedding -* The `SpotterEmbed` now includes the `isSpotterFullPageEnabled` parameter. When set to `true`, the Spotter interface occupies the full available height of the embed container. -* The `enableSpotterFileUpload` parameter enables file upload capability directly in embedded Spotter. +The following HostEvents now allow custom parameters to set object properties programmatically: + +* `HostEvent.SaveAnswer` + +Allows adding `name` and `description` text strings. When these parameters are defined, the event triggers the Save action to save the Answer with the predefined properties without opening the *Describe your Answer* modal. +* `HostEvent.Pin` + +Allows adding custom properties for visualization ID, name, and description, Liveboard ID, and Tab ID. When these parameters are defined, the event triggers an action to pin the Answer to the Liveboard specified in the code, without opening the *Pin* modal. + +For more information, see xref:events-hostEvents.adoc#hostEventParameterization[Host Events] documentation. |[tag greenBackground]#NEW FEATURE# a| -[discrete] -===== Liveboard embedding -* New action ID `Action.CopyToClipboard` to show or hide the *Copy to clipboard* option for Liveboard visualizations. -* The `LiveboardEmbed` now supports the `isFilterPanelOpen` attribute to set the initial open or closed state of the filter panel. +New configuration attributes:: + +* `disableSourceSelection` + +Disables data source selection panel for embed users when set to `true`. +* `hideSourceSelection` + +Hides data source selection panel when set to `true` +* `locale` + +Sets the xref:locale-setting.adoc[locale and regional settings] for the Spotter interface. +* `showSpotterLimitations` + +Shows functional limitations of Spotter when set to `true` +* `hideSampleQuestions` + +Hides sample questions that appear on the default Spotter page. + +Action IDs for menu customization:: +Use the following action IDs in the `disabledActions`, `visibleActions`, or `hiddenActions` array to disable, show, or hide menu actions and elements in the embedded Spotter interface: + +* `Action.PreviewDataSpotter` + +The *Preview data* button on the Spotter conversation panel. +* `Action.ResetSpotterChat` + +The *Reset* button on the Spotter conversation panel. +* `Action.SpotterFeedback` + +The feedback widget on Spotter-generated charts. +* `Action.EditPreviousPrompt` + +The edit icon on the prompt panel. +The Prompt panel appears after Spotter generates a response to a user query. +* `Action.DeletePreviousPrompt` + +The delete icon on the prompt panel. + +//// +* `Action.EditTokens` + +The option to edit tokens on a Spotter-generated chart or table. +//// +CSS variables:: + +The following new CSS variables are available for Spotter interface customization: + +* `--ts-var-spotter-input-background` +* `--ts-var-spotter-prompt-background` + +For more information about Spotter customization, see xref:embed-spotter.adoc#SpotterCSS[Customize styles]. |[tag greenBackground]#NEW FEATURE# a| -[discrete] -===== Full application embedding -The `AppEmbed` configuration now supports `hideApplicationSwitcher` to hide the application switcher control from the embedded ThoughtSpot navigation bar. -|==== + +Configuration attributes:: + +* `hideIrrelevantChipsInLiveboardTabs` + +Hides filter chips on a Liveboard when set to `true`. + +* `isLiveboardCompactHeaderEnabled` + +Enables the compact Liveboard header feature when set to `true`. + +Action IDs:: +Use the following action IDs in the `disabledActions`, `visibleActions`, or `hiddenActions` array to disable, show, or hide menu actions on an embedded Liveboard: + +* `Action.DisableChipReorder` + +ID for the action that disables filter chip reordering. +* `Action.ChangeFilterVisibilityInTab` + +|==== + +== Version 1.35.0, December 2024 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| +The SDK now provides the `isUnifiedSearchExperienceEnabled` setting to customize the Search experience on ThoughtSpot Home page for embedding application users: + +* When set to `true`, the split search experience is disabled and the Search bar on the Home page functions as Natural Language Search interface +* When set to `false`, the split search experience is enabled and object Search is set as the default Home page search experience. + +For more information, see xref:full-app-customize.adoc#_search_components[Search interface on the Home page in full application embedding]. + +|[tag greenBackground]#NEW FEATURE# a| The `overrideOrgId` parameter in the SDK provides the ability to override Org context for embedding application users. This parameter allows users authenticated to an Org to temporarily view content from another Org. Before specifying the Org ID for override, make sure the Per Org URL feature is enabled on your ThoughtSpot instance. To enable Per Org URL on your instance, contact ThoughtSpot Support. +|==== + +== Version 1.34.0, November 2024 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| You can now embed the following ThoughtSpot Spotter components in your app: + +* `SpotterEmbed` + +Embeds Spotter conversation interface in your app +* `SpotterAgentEmbed` + +Creates a conversation component without the body, which can be integrated into chatbots or other conversational apps. + +For more information, see xref:embed-spotter.adoc[Embed Spotter] and xref:spotter-in-custom-chatbot.adoc[Integrate Spotter into your chatbot]. + +|[tag greenBackground]#NEW FEATURE# a|The following parameters and enumerations are available for customizing Liveboard experience: + +* `showLiveboardVerifiedBadge` + +Shows or hides the Liveboard verified badge. Available if the Liveboard compact header feature is enabled. +* `showLiveboardReverifyBanner` + +Shows or hides the re-verify banner. Available if the Liveboard compact header feature is enabled. +* `Action.KPIAnalysisCTA` + +Action ID to show, hide, or disable the **Analyze CTA** action on a KPI chart. + +|[tag greenBackground]#NEW FEATURE# |You can now use the `HostEvent.GetIframeUrl` to get the iframe src URL from the Visual Embed Playground. If you are embedding ThoughtSpot in apps like Salesforce and Sharepoint without the SDK, use this event to generate the iframe URL. + +|[tag greenBackground]#NEW FEATURE# a|The following parameters are available for customizing Search experience: + +* `collapseDataPanel` +Minimizes the data panel view. Users can click the data panel header any time to expand the panel. +* `collapseSearchBar` +Sets the initial state of the search bar when embedding a saved Answer. + +|[tag greenBackground]#NEW FEATURE# a| The following settings are available for customizing the new home page and navigation experience in full app embedding: + +* `HomeLeftNavItem.LiveboardSchedules` + +The Liveboard schedules menu on the left navigation panel. + +Action enumerations:: + +* `Action.EditScheduleHomepage` + +To show, disable, or hide the *Edit* action on the *Liveboard schedules* page +* `Action.PauseScheduleHomepage` + +To show, disable, or hide the *Pause* action on the *Liveboard schedules* page +* `Action.ViewScheduleRunHomepage` + +To show, disable, or hide the *View run history* action on the *Liveboard schedules* page +* `Action.DeleteScheduleHomepage` + +To show, disable, or hide the *Delete* action on the *Liveboard schedules* page +* `Action.UnsubscribeScheduleHomepage` + +To show, disable, or hide the *Unsubscribe* action on the *Liveboard schedules* page +|==== + +== Version 1.33.x, October 2024 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| You can now customize the search experience for the embedded ThoughtSpot **Home** page using `homePageSearchBarMode`. By default, the **Home** page includes the Object Search bar, which allows finding popular Liveboards and Answers. + +You can set the `homePageSearchBarMode` property to one of the following options: + +** `aiAnswer` + +Displays the search bar for Natural Language Search. +** `none` +Hides the Search bar on the **Home** page. Note that it only hides the Search bar on the **Home** page and doesn't affect the Object Search bar visibility on the top navigation bar. +** `objectSearch` (default) + +Displays Object Search bar on the **Home** page. +|[tag greenBackground]#NEW FEATURE# a|The SDK now allows you to set the focus on the Search bar or outside the Search bar when rendering the embedded Search page. Use the `focusSearchBarOnRender` property to set the position of the cursor focus. +|[tag greenBackground]#NEW FEATURE# a| The SDK includes the following Event and Action enumeration members: + +Events:: + +* `EmbedEvent.OnBeforeGetVizDataIntercept` + +Developers can emit this event to intercept search execution, allow or restrict certain queries, and show an error message with custom text for restricted queries. To allow the embedded page to emit this event, you must set the `isOnBeforeGetVizDataInterceptEnabled` attribute to `true`. + +* `EmbedEvent.ParameterChanged` + +Emitted when a Parameter is changed on a saved Answer or Liveboard. + +Actions:: + +* `Action.ManageTags` + +Use this action enumeration to disable, show, or hide the **Manage tags** button on the Liveboards and Answers pages. +|==== + +== Version 1.32.x, August 2024 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| The following new action enumerations are available in this version: + + +* `Action.CreateLiveboard` for the *Create Liveboard* menu action on the Liveboards lists page. + +* `Action.SyncToTeams` for the **Sync to Teams** menu action on Liveboard visualizations. +* `Action.SyncToSlack` for the **Sync to Slack** action on Liveboard visualizations. +* `Action.AddQuerySet` for the **Add Query Set** action on the data panel (new experience) of the Search page. +* `Action.AddColumnSet` for the **Add Column Set** action on the data panel (new experience) of the Search page. +* `Action.AddDataPanelObjects` for the **Add** menu that includes sub-menu options such as Formulas, Parameters, Query set, and Column set actions. +* `Action.OrganiseFavourites` for the **Organize** action above the Favorites panel on the modular Homepage (New experience) +For more information, see xref:Action.adoc[Actions]. +|[tag greenBackground]#NEW FEATURE#| Developers can now use the `disableRedirectionLinksInNewTab` parameter to disable links and redirection of links in the embedded view. +|[tag greenBackground]#NEW FEATURE# a|You can now enable `enable2ColumnLayout` on a Liveboard to adjust the page view according to the width and resolution of users' devices. +|| +|==== + +== Version 1.31.x, July 2024 +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| Runtime filters + + +* `NOT_IN` operator for Runtime filters. +For more information, see xref:runtime-filters.adoc#runtimeFilterOp[Runtime filters]. +* `excludeRuntimeParametersfromURL` parameter to exclude or remove runtimeParameters from the URL. +|[tag greenBackground]#NEW FEATURE# |For performance optimization, developers can choose to load embedded views in a lightweight V2 shell by setting `enableV2Shell_experimental` to `true`. +|==== + +== Version 1.30.0, June 2024 +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| **CSS variables for new homepage experience** + +* `--ts-var-home-watchlist-selected-text-color` + +* `--ts-var-home-card-color` + +* `--ts-var-home-favorite-suggestion-card-text-color` + +* `--ts-var-home-favorite-suggestion-card-background` + +* `--ts-var-home-favorite-suggestion-card-icon-color` + +For more information, see xref:css-customization.adoc#_homepage_modules_new_experience_mode[CSS variables and overrides]. +|==== + +== Version 1.29.0, May 2024 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| **Ask Sage** + +With Ask Sage [beta betaBackground]^Beta^ embedded application users can ask follow-up questions on a visualization generated from a Natural Language Search query, converse with AI analyst, and refine results. To enable this feature, set `enableAskSage` to `true`. + +Action enumeration:: +To show, hide, or disable Ask Sage on a visualization, add `Action.AskAi`. For example, ++ +[source,JavaScript] +---- +hiddenActions: [Action.AskAi] +---- + +Events:: +* `HostEvent.AskSage` + +Triggers the **Ask Sage** action on a Liveboard visualization. +* `EmbedEvent.AskSageInit` + +Emits when the **Ask Sage** action is initialized. +* `HostEvent.GetParameters` + +Triggers a fetch action to get runtime Parameters. +* `HostEvent.UpdateParameters` + +Updates runtime Parameters +* `HostEvent.ResetLiveboardPersonalisedView` + +Resets a personalized Liveboard view. +* `HostEvent.UpdateCrossFilter` + +Updates cross filters applied on a Liveboard. +|==== + +== Version 1.28.x, April 2024 + +[width="100%" cols="1,4"] +|===== +|[tag greenBackground]#NEW FEATURE# a| The SDK includes the following new enumeration members in v1.28.0: + +** `Action.VerifiedLiveboard` + +Can be used to show or hide the *Verified Liveboard* banner. +|[tag greenBackground]#NEW FEATURE# a| To access the new Home page and global navigation experience in the full application embedding, you can use the `modularHomeExperience` property in the SDK. The modular homepage experience is turned off by default and is available as an Early Access feature in 9.12.5.cl release. When `modularHomeExperience` is set to `true`, you can use the following parameters in the SDK to control the application experience: + +* `hiddenhomeleftnavitems` +* `hiddenhomepagemodules` +* `hideapplicationswitcher` +* `hidehomepageleftnav` +* `hideorgswitcher` +* `reorderedhomepagemodules` +* `HomeLeftNavItem` + +For more information, see xref:full-app-customize.adoc[Customize full application embedding] and xref:AppViewConfig.adoc[AppViewConfig]. +|[tag greenBackground]#NEW FEATURE# a| The following embed event is available from the v1.28.0 onwards: + +`EmbedEvent.Rename` + +Emits when an embedded Liveboard or visualization is renamed. +|[tag greenBackground]#NEW FEATURE# a| TML actions + +The following TML menu actions are now grouped under the **TML** sub-menu of the **More** image:./images/icon-more-10px.png[the more options menu] menu on Answer page. + +* Export TML +* Edit TML +* Update TML + +To show, hide, or disable these actions in the embedded mode, use the following format: + +[source,JavaScript] +---- + // to show the TML menu and its sub-menu options +visibleActions: [Action.TML, Action.ExportTML, Action.EditTML] +---- + +[source,JavaScript] +---- + // to hide all TML actions +hiddenActions: [Action.TML] +---- + +[source,JavaScript] +---- + // to disable all TML actions +disabledActions: [Action.TML] +---- +|[tag greenBackground]#NEW FEATURE# | You can now reset authentication token and fetch a new token for new authentication requests. +For more information, see link:https://developers.thoughtspot.com/docs/Function_resetCachedAuthToken[resetCachedAuthToken]. + +|[tag greenBackground]#NEW FEATURE#| You can now override the default number, date, and currency format defined by your locale settings. To override the default settings, use the following parameters: + +* `numberFormatLocale` + +* `dateFormatLocale` + +* `currencyFormat` + +For more information, see xref:locale-setting.adoc#_set_locale_in_the_sdk[Customize locale]. + +|[tag greenBackground]#NEW FEATURE# |Tokenized fetch + +The SDK now provides a fetch wrapper that adds the authentication token to the API requests. +For more information, see link:https://developers.thoughtspot.com/docs/Function_tokenizedFetch#_tokenizedfetch[tokenizedFetch]. +|===== + +== Version 1.27.x, March 2024 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| The following action enumeration members are available from v1.27.9 and v1.27.10: + +* `Action.AIHighlights` +* `Action.AddToWatchlist` +* `Action.RemoveFromWatchlist` +* `Action.CopyKpiLink` + +For more information, see xref:Action.adoc[Action]. +| [tag greenBackground]#NEW FEATURE# a| You can now use `HostEvent.GetAnswerSession` to get Answer session data for a Search Answer or Liveboard Visualization in the embedded view. +|==== + +== Version 1.27.0, January 2024 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a|The `SageEmbed` package is now available on all clusters. You can use this SDK package to embed Natural Language Search capabilities and assist users with AI-suggested queries and AI-generated answers. This SDK package also allows you to customize the Natural Language Search experience in the embedded view. + +For a complete list of methods, functions, interface objects, and properties, see the following pages: + + +* xref:SageEmbed.adoc[SageEmbed] +* xref:SageViewConfig.adoc[SageViewConfig] + +|[tag orangeBackground]#MODIFIED# a| The `HostEvent.DrillDown` now supports the `vizId` parameter to trigger a drill-down action on a specific visualization of a Liveboard. +For more information, see xref:HostEvent.adoc#_drilldown[DrillDown]. +|[tag greenBackground]#NEW FEATURE# a| The new version of the SDK introduces the following new enumeration members: + +* Host Events +** `HostEvent.UpdateSageQuery` + +Updates the search query string for Natural Language Search operations. +* Embed Events +** `EmbedEvent.CreateConnection` + +Emitted when a user creates a new data connection on the **Data** page. +** `EmbedEvent.CreateWorksheet` + +Emitted when a user creates a new Worksheet. +|==== + +== Version 1.26.0, November 2023 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| The SDK provides `AnswerService` class to trigger the answer service with a custom action payload. +You can use this service to run GraphQL queries in the context of the Answer with a custom action trigger. For more information, see link:https://developers.thoughtspot.com/docs/Class_AnswerService[AnswerService]. Recommended ThoughtSpot application version is 9.10.0.cl. + +|[tag greenBackground]#NEW FEATURE# a|The following object properties and feature flags are introduced in the `LiveboardEmbed` and `AppEmbed` SDK packages: + +* `showLiveboardDescription` + +Shows the Liveboard description text when set to `true` +* `showLiveboardTitle` + +Shows the Liveboard title when set to `true` +* `isLiveboardHeaderSticky` + +Sets Liveboard header bar as a fixed element when set to `true` +* `hideLiveboardHeader` + +Hides the Liveboard header when set to `true` +* `hiddenTabs` + +Hides the specified tabs from the Liveboard page +* `visibleTabs` + +Displays the specified tabs on the Liveboard page + +|[tag greenBackground]#NEW FEATURE# |You can now enable the new data panel experience by setting `dataPanelV2` to `true` in the SDK when embedding ThoughtSpot Search. The new data panel experience is turned off by default on embedded ThoughtSpot instances. + +|[tag greenBackground]#NEW FEATURE# a|The new version of the SDK supports the following events: + +Embed events:: +* `EmbedEvent.hiddenTabs` +* `EmbedEvent.visibleTabs` +* `EmbedEvent.UpdatePersonalisedView` +* `EmbedEvent.SavePersonalisedView` +* `EmbedEvent.ResetLiveboard` +* `EmbedEvent.DeletePersonalisedView` +* `EmbedEvent.SageWorksheetUpdated` +* `EmbedEvent.SageEmbedQuery` ++ +For more information, see xref:EmbedEvent.adoc[EmbedEvent]. + +Host events:: + +* `HostEvent.GetTabs` +* `HostEvent.SetVisibleTabs` +* `HostEvent.SetHiddenTabs` +* `HostEvent.GetAnswerSession` +* `HostEvent.UpdateSageQuery` ++ +For more information, see xref:HostEvent.adoc[HostEvent]. + +|[tag greenBackground]#NEW FEATURE# a| The SDK introduces the following action enumeration members: + +* `Action.AddTab` + +Show, disable, or hide the **Add Tab** action on a Liveboard. +* `Action.PersonalisedViewsDropdown` + +Show, disable, or hide the Liveboard views saved by a user. +* `Action.LiveboardUsers` + +Show, disable, or hide Liveboard users. +* `Action.SageAnswerFeedback` +Show, disable, or hide the feedback widget on AI-generated Answer page. +* `Action.EditSageAnswer` +Show, disable, or hide the **Edit** action on the AI-generated Answer page. + +For more information, see xref:Action.adoc[Actions]. +|==== + +== Version 1.25.0, October 2023 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# | The SDK now supports runtime Parameter overrides on Liveboards and Answers. +For more information, see xref:runtime-parameters.adoc#_apply_parameter_overrides_using_visual_embed_sdk[Runtime Parameter overrides]. + +|[tag greenBackground]#NEW FEATURE# a| The SDK introduces the following action enumeration members: + +* `Action.RenameModalTitleDescription` +* `Action.EnableContextualChangeAnalysis` +* `Action.RequestVerification` +* `Action.AddTab` + +For more information, see xref:Action.adoc[Actions]. +|==== + +== Version 1.24.0, September 2023 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| ThoughtSpot now provides the `SageEmbed` package to embed the ThoughtSpot Search page with Sage features such as natural language search and AI-suggested search examples. This feature is in beta and not available in the Visual Embed Playground. +|[tag greenBackground]#NEW FEATURE# a| The `HostEvent.SetActiveTab` event in the upcoming version of the SDK allows you to set a tab as an active tab on a Liveboard. +|==== + +== Version 1.23.0, August 2023 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| The SDK supports the following performance optimization enhancements: + + +* Ability to pre-render a generic instance of the ThoughtSpot component using the `prerenderGeneric` attribute. The generic instance uses the default host and flags and can be rendered in the background to improve application response. +* Ability to use an iFrame from a pre-rendered iFrame pool using the `usePrerenderedIfAvailable` attribute. +|==== + +//// +|[tag greenBackground]#NEW FEATURE# a| New events for Liveboard filters + + +* `EmbedEvent.FilterChanged` + +* `HostEvent.GetFilters` + +* `HostEvent.UpdateFilters` +//// + +== Version 1.22.0, June 2023 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| The new version of the SDK introduces the `TrustedAuthTokenCookieless` `authType` property to allow Cookieless embedding. The Cookieless authentication method allows using a bearer token to identify the signed-in user instead of session cookies. + +For more information, see xref:embed-authentication.adoc#_cookieless_authentication[Cookieless authentication]. + +|[tag greenBackground]#NEW FEATURE# a|The new version of the SDK allows you to block user access to the non-embedded instance of the ThoughtSpot application. In full app embed deployments, you can use the `blockNonEmbedFullAppAccess` property in the SDK to restrict or allow your application users from accessing ThoughtSpot pages in the non-embed mode. + +For more information, see xref:security-settings.adoc#_block_access_to_non_embedded_thoughtspot_pages[Block access to non-embedded ThoughtSpot pages]. + +|==== + +//// +|[tag greenBackground]#NEW FEATURE# a| The SDK supports the following performance optimization enhancements: + + +* Ability to pre-render a generic instance of the ThoughtSpot component using the `prerenderGeneric` attribute. The generic instance uses the default host and flags and can be rendered in the background to improve application response. +* Ability to use an iFrame from a pre-rendered iFrame pool using the `usePrerenderedIfAvailable` attribute. +//// + +== Version 1.21.0, May 2023 +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a|The new version of the SDK introduces the following action enumeration members: + +* `Action.AxisMenuAggregate` +* `Action.AxisMenuConditionalFormat` +* `Action.AxisMenuEdit` +* `Action.AxisMenuFilter` +* `Action.AxisMenuGroup` +* `Action.AxisMenuNumberFormat` +* `Action.AxisMenuPosition` +* `Action.AxisMenuRemove` +* `Action.AxisMenuRename` +* `Action.AxisMenuSort` +* `Action.AxisMenuTextWrapping` +* `Action.AxisMenuTimeBucket` +* `Action.CrossFilter` +* `Action.RemoveCrossFilter` + +For more information, see xref:embed-action-ref.adoc[Action reference]. + +|[tag greenBackground]#NEW FEATURE# a| The SDK introduces the following events: + +* `HostEvent.AddColumns` +* `HostEvent.OpenFilter` +* `HostEvent.RemoveColumn` +* `HostEvent.ResetSearch` +* `EmbedEvent.CrossFilterChanged` +* `EmbedEvent.DownloadAsPng` +* `EmbedEvent.VizPointRightClick` + +For more information, see xref:embed-events.adoc[Events]. + +|[tag redBackground]#DEPRECATED# a| + +The following events are deprecated from version 1.21.0 onwards. + +* `HostEvent.Download` + +* `EmbedEvent.Download` + +You can use the `DownloadAsPng`, `DownloadAsXlsx`, `DownloadAsCsv` and `DownloadAsPdf` events for download actions. + +For more information, see xref:embed-events.adoc[Events reference]. +|[tag orangeBackground]#MODIFIED# a| + +Events:: +The SDK supports omitting or executing a search query in xref:HostEvent.adoc#_search[`HostEvent.Search`]. +Actions:: +Use the following action enumeration members instead of `Action.Download` to show, hide, or disable the *Download* menu action on an embedded Liveboard, visualization, or Answer: ++ +* `Action.DownloadAsCsv` +* `Action.DownloadAsPdf` +* `Action.DownloadAsXlsx` +* `Action.DownloadAsPng` + +To disable or hide download actions, you can use `Action.Download` in the `disabledActions` and `hiddenActions` arrays respectively. However, if you are using the `visibleActions` array to show or hide actions on a visualization or Answer, include the following download action enumerations along with `Action.Download` in the array: + + +** `Action.DownloadAsCsv` + +** `Action.DownloadAsPdf` + +** `Action.DownloadAsXlsx` + +** `Action.DownloadAsPng` + +|[tag greenBackground]#NEW FEATURE# a| The SDK includes new attributes to customize the experience for embedded app users: + +* `linkOverride` ++ +Allows overriding the *Open in new tab* link on embedded pages. + +* `contextMenuTrigger` ++ +Allows triggering contextual menu on the Liveboard visualizations and Answers from left-click to right-click. + +* `hideSearchBar` ++ +Allows hiding the Search bar on the embedded Search page. +|[tag greenBackground]#NEW FEATURE# | The SDK now allows setting the loading preference for embedded iFrames. +For performance optimization, you can set the `loading` attribute to `lazy` in the `FrameParams` property. +|==== + +== Version 1.20.0, April 2023 + +[width="100%" cols="1,4"] +|==== +|[tag redBackground]#DEPRECATED# a|The `dataSources` property in `SearchEmbed` and `SearchBarEmbed` is deprecated and replaced with the `dataSource` attribute. The SDK supports searching from a single data source only. +|[tag greenBackground]#NEW FEATURE# a|The embed SDK packages now include the `insertAsSibling` property. This attribute can be used to insert the embedded object as a sibling to the element inside the target container. +|==== + +== Version 1.19.0, February 2023 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a|The `customCSS` property in the `customizations` object supports new variables to customize the styles for dialogs, search bar, search navigation and search suggestions panels. +For more information, see xref:css-customization.adoc[Customize CSS]. +|[tag redBackground]#BREAKING CHANGE# a|The new Liveboard experience mode introduces changes to the data format of the JSON response payload triggered by callback custom actions. For example, the `reportBookData`, and `vizData` attributes are modified, and the custom action `id` now is part of the data attribute. These changes may break your current custom action event handlers. For interoperability, we recommend adding the data attribute to `payload` in your code as shown in the example here: + +[source,JavaScript] +---- +liveboardEmbed.on(EmbedEvent.CustomAction, payload => { + if (payload.id === "callback-action-id" \|\| payload.data.id === "callback-action-id") { + console.log('Custom Action event:', payload.data); + } +}) +---- + +You may also want to update the data classes in your scripts to process the JSON response payload and handle complex data. For more information, see xref:custom-actions-callback.adoc#_define_functions_and_classes_to_handle_liveboard_data[Callback custom actions]. + +|[tag greenBackground]#NEW FEATURE# a|The new version of the SDK introduces the following Host events: + +* `HostEvent.Delete` +* `HostEvent.Download` +* `HostEvent.DownloadAsCsv` +* `HostEvent.DownloadAsXlsx` +* `HostEvent.ManagePipelines` +* `HostEvent.Save` +* `HostEvent.Share` +* `HostEvent.ShowUnderlyingData` +* `HostEvent.SpotIQAnalyze` +* `HostEvent.SyncToOtherApps` +* `HostEvent.SyncToSheets` + +For more information, see xref:events-hostEvents.adoc[Host events]. + +|[tag redBackground]#DEPRECATED# a|The `noRedirect` property in the SDK is deprecated and replaced with the `inPopup` attribute. When set to `true`, the `inPopup` attribute allows the SAML SSO authentication flow in a pop-up window. + +For more information, see xref:embed-authentication.adoc#_saml_redirection[SAML Redirection]. +|==== + +== Version 1.18.0, January 2023 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a|The new version of the SDK provides the `SearchBarEmbed` JavaScript package to embed only the ThoughtSpot Search bar in your app. + + +For more information, see xref:embed-searchbar.adoc[Embed ThoughtSpot search bar]. + +|[tag greenBackground]#NEW FEATURE# a|The `customCSS` property in the `customizations` object supports new variables to customize the UI elements on Liveboard, visualization, and Answer pages. You can also use these variables to define custom styles in the CSS file. + +For more information, see xref:css-customization.adoc[Customize CSS]. +|[tag greenBackground]#NEW FEATURE# |The new version of the SDK allows fetching TML objects via `GetTML` host event. This event is triggered when a user clicks on the *Show underlying data* action on a Liveboard visualization or Answer page. + + +For more information, see xref:HostEvent.adoc#_gettml[GetTML]. + +|[tag greenBackground]#NEW FEATURE# a| The new version of the SDK introduces the following enums in the `Action` object: + +* `Action.SyncToOtherApps` + +* `Action.SyncToSheets` + +* `Action.ManagePipelines` + + +You can use these enums to show, hide, or disable *Sync to sheets*, *Sync to other apps*, and *Manage pipelines* menu actions on a Liveboard visualization or Answer. + +For more information, see xref:embed-action-ref.adoc[Actions]. +|==== + +== Version 1.17.1, December 2022 + +Bug fixes to the trusted authentication feature. + +== Version 1.17.0, November 2022 + +The new version of the SDK introduces several new features and enhancements. +[width="100%" cols="1,4"] +|==== +|[tag orangeBackground]#MODIFIED# a|The `AuthType` property is modified and supports new enums. + + +* `AuthType.SAML` is renamed as `AuthType.SAMLRedirect` + +* `AuthType.OIDC` is renamed as `AuthType.OIDCRedirect` + +* `AuthType.AuthServer` is renamed to `AuthType.TrustedAuthToken` + +This enhancement does not introduce any breaking changes to your current implementation. +|[tag greenBackground]#NEW FEATURE# a|To use your current SAML or OIDC authentication setup and redirect users to the IdP for authentication within the embedded iFrame, you can now use `AuthType.EmbeddedSSO`. + +For more information, see xref:embed-authentication.adoc[Authentication]. +|[tag greenBackground]#NEW FEATURE#| +The `customizations` object in the SDK allows you to specify a custom CSS URL. You can also use this object to define CSS variables directly in the `init` code. + +For more information, see xref:css-customization.adoc[Customize CSS]. +|==== + +== Version 1.16.0, October 2022 + +The new version of the SDK includes bug fixes and improvements to the new Liveboard experience. + +== Version 1.15.1, September 2022 +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE#| +The `prefetch` method now supports the `url` and `prefetchFeatures` parameters. You can use these parameters to call the prefetch method before `init` and prefetch static resources on application load. + +For more information, see xref:prefetch-and-cache.adoc[Prefetch static resources]. +|==== + +== Version 1.15.0, September 2022 +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE#| +For embedded instances with the new Liveboard experience, the Visual Embed SDK provides the `activeTabId` attribute, using which you can set a Liveboard tab as an active tab. + +For more information, see xref:embed-pinboard.adoc#_liveboard_tabs[Customize Liveboard tabs]. + +|[tag greenBackground]#NEW FEATURE# a|The new version of the SDK supports firing events for Liveboard menu actions from the host application. The SDK introduces the following host event enumeration members for Liveboard objects: + +* CopyLink +* CreateMonitor +* DownloadAsPdf +* Edit +* EditTML +* Explore +* ExportTML +* LiveboardInfo +* MakeACopy +* ManageMonitor +* Pin +* Present +* Remove +* Schedule +* SchedulesList +* UpdateTML + +For more information, see xref:events-hostEvents.adoc[Events reference]. +|==== + +== Version 1.14.0, August 2022 +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE#| +The Visual Embed SDK now includes the `liveboardV2` attribute in the `LiveboardEmbed` package to allow developers to enable the new Liveboard experience on their embedded ThoughtSpot instance. + +For more information, see xref:embed-pinboard.adoc[Embed a Liveboard]. +|[tag orangeBackground]#MODIFIED#|If trusted authentication is enabled, the SDK makes a `POST` API call to get a login token and log the user into ThoughtSpot. +The earlier versions of the SDK supported only `GET` API requests. For more information, see xref:embed-authentication.adoc#_configure_token_based_authentication_method_in_visual_embed_sdk[Configure token-based authentication method in Visual Embed SDK]. +|==== + +== Version 1.13.0, July 2022 +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE#| +This version of Visual Embed SDK includes the `enableSearchAssist` attribute, using which you can turn on the Search Assist feature on an embedded instance. +|[tag greenBackground]#NEW FEATURE#| The new version of SDK introduces the `AuthType.SAML` enum for SAML-based SSO authentication. Note that `AuthType.SAML` replaces the `AuthType.SSO` enum, which is deprecated in the v1.13.0 version of the SDK. + +For more information, see xref:embed-authentication.adoc#saml-sso-embed[Authentication]. +|[tag redBackground]#DEPRECATED#| The `AuthType.SSO` enum is deprecated in v1.13.0. ThoughtSpot recommends using `AuthType.SAML` for the SAML SSO authentication method. + +This change does not impact your current embed implementation with `AuthType.SSO`. +|[tag greenBackground]#NEW FEATURE#| The SDK includes the `getExportRequestForCurrentPinboard` event, which is triggered when a user tries to export a Liveboard in its current state. + +For more information, see xref:events-hostEvents.adoc[Events reference]. +|==== + +== Version 1.12.0, June 2022 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE#| +This version of Visual Embed SDK introduces the `navigate` host event, which is triggered when a user navigates to an application page without a page reload. + +For more information, see xref:events-hostEvents.adoc[Events reference]. +|[tag greenBackground]#NEW FEATURE# | The new `getThoughtSpotPostUrlParams` method fetches ThoughtSpot URL query parameters prefixed with `ts-`. +|==== + +== Version 1.11.2, June 2022 + +Bug fix for Typescript builds that affect Angular project configurations. + +== Version 1.11.1, May 2022 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE#| The SDK includes the action enum `ReportError`, using which you can turn off ThoughtSpot-specific error reporting. +|==== + +== Version 1.11.0, May 2022 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| The new version of SDK includes the following new events: + +* `ALL` +* `AnswerChartSwitcher` +* `AnswerDelete` +* `CopyAEdit` +* `CopyToClipboard` +* `Download` +* `DownloadAsPdf` +* `DownloadAsCsv` +* `DownloadAsXlsx` +* `DrillExclude` +* `DrillInclude` +* `EditTML` +* `ExportTML` +* `Monitor` +* `Pin` +* `Save` +* `SaveAsView` +* `Share` +* `ShowUnderlyingData` +* `SpotIQAnalyze` +* `UpdateTML` +* `VizPointClick` + +For more information about how to register and handle these events, see xref:embed-events.adoc[Events and app integration]. +|[tag greenBackground]#NEW FEATURE# a| The new version of SDK supports the `showAlerts` attribute, using which you can show or hide alerts and error messages in the embedded view. + +|[tag greenBackground]#NEW FEATURE# a| The `Action.CreateMonitor` enumeration is available in the SDK for embedded ThoughtSpot environments on which the *Monitor* feature is enabled. +For more information, see xref:embed-actions.adoc[Show or hide UI actions]. +|==== + +== Version 1.10.4, May 2022 +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE#|The `detectCookieAccessSlow` parameter in the SDK allows your app to check if third-party cookies are enabled on the browser. This parameter is available only for trusted and `Basic` authentication types. +|==== +== Version 1.10.3, May 2022 + +Bug fix and improvements to the `logout` method. + +== Version 1.10.2, May 2022 +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE#|Ability to configure `redirectPath` on the origin when using the SAMLRedirect `authType`. +|==== + +== Version 1.10.1, May 2022 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE#|You can now use the `logout` method to log out embed users. +|[tag orangeBackground]#MODIFIED# a| Note the following changes: + + +* You can now use the `loginFailedMessage` property on init to display the `Not logged in` message when a user login fails. You can customize this message by defining a custom text string in the `loginFailedMessage` attribute. +* The `init` method now returns an event emitter which can be used to listen to `AuthStatus` such as login failure, success, or user logout. +|==== + +== Version 1.10.0, April 2022 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| The `AddRemoveColumns` event is now available in the SDK. For more information, see xref:event-embedEvents.adoc[Events reference]. +|==== + +== Version 1.9.8, April 2022 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE#|The `pageId` attribute now allows you to set the **SpotIQ** page as the home tab of your embedded ThoughtSpot app. + +For more information, see xref:full-embed.adoc[Embed full application]. +|==== + +== Version 1.9.6 and 1.9.7, April 2022 + +Bug fixes and improvements + +== Version 1.9.5, April 2022 +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE#|The `locale` attribute is now available in embed packages. You can use this attribute to set the locale or language of your embedded application view. +For more information, see xref:locale-setting.adoc[Set locale and display language]. +|==== + +== Version 1.9.4, April 2022 + +Bug fixes and improvements to React components. + +== Version 1.9.3, March 2022 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE#| The SDK now supports the `disableLoginRedirect` attribute to improve the login experience for your application users. When enabled, this attribute prevents your app from redirecting users to the login page when their session expires. + +You can use this attribute along with `autoLogin` to automatically authenticate and re-login a user. + +This feature is applicable to token-based authentication, that is, when the `AuthType` is set as `TrustedAuthToken` in the SDK. + +For more information, see xref:embed-authentication.adoc#trusted-auth-embed[Authentication]. +|==== + +== Version 1.9.2, March 2022 +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE#| You can now trigger events on React components using the `useEmbedRef` hook. + +For more information, see xref:embed-ts-react-app.adoc[Embed ThoughtSpot in a React app]. +|==== + +== Version 1.9.1, March 2022 +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE#| The SDK now includes the `visibleVizs` attribute in the `LiveboardEmbed` package. This attribute allows you to add visualization GUIDs that you want to display when a Liveboard renders for the first time. + +For more information, see xref:embed-pinboard.adoc[Embed a Liveboard]. + +|[tag greenBackground]#NEW FEATURE# a| The following events are now available in the SDK: + + +* `LiveboardRendered` (EmbedEvent) + +For more information, see xref:event-embedEvents.adoc[Events reference]. +|==== + +== Version 1.9.0, March 2022 +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| The SDK now includes the following new enumerations for UI actions: + +* `Action.AnswerDelete` + +* `Action.AnswerChartSwitcher` + +* `Action.AddToFavorites` + +* `Action.EditDetails` + + +For more information, see xref:embed-actions.adoc#standard-actions[Show or hide UI actions]. + +|[tag greenBackground]#NEW FEATURE# a| The SDK now supports the `UpdateRuntimeFilters` host event. For more information, see xref:events-hostEvents.adoc[Events reference]. +|==== + +== Version 1.8.x, February 2022 + +[width="100%" cols="1,4"] +|==== +|[tag redBackground]#BREAKING CHANGE# | The `autoLogin` attribute is now set as `false` by default. This attribute is used in the `init` method to automatically re-login a user when a session expires. +|[tag greenBackground]#NEW FEATURE# | The `init` method now returns the `authPromise` which resolves when a user authentication is completed. +|==== + + +== Version 1.7.0, January 2022 + +[width="100%" cols="1,4"] +|==== +| +[tag greenBackground]#NEW FEATURE# |+++
OIDC AuthType
+++ + +The SDK supports the `OIDC` `authType` in `init` calls. If you want your application users to authenticate to an OpenID provider and use their SSO credentials to access the embedded ThoughtSpot content, you can enable the `OIDC` authentication type in the SDK. + +For more information, see xref:embed-authentication.adoc#oidc-auth[Authentication and security attributes]. +|[tag greenBackground]#NEW FEATURE# a|+++
Embed events
+++ + +The SDK includes the following new event: + +* `RouteChange` + +For more information, see xref:event-embedEvents.adoc[Events reference]. + +|==== + +== Version 1.6.x, November 2021 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a|+++
Visible actions
+++ + +You can now configure a set of ThoughtSpot UI actions as visible actions and display these actions in the embedded UI. If your embedded instance requires only a few actions, you can use the `visibleActions` API to show only these actions in the embedded ThoughtSpot UI. + +For more information, see xref:embed-actions.adoc[Show or hide UI actions]. + +|[tag orangeBackground]#MODIFIED# | +++
Terminology changes
+++ + +The SDK library and object parameter names are modified to rebrand pinboards as Liveboards. For a complete list of changes, see xref:terminology-update.adoc#sdk-changes[Terminology changes]. + +|[tag greenBackground]#NEW FEATURE# a|+++
Embed events
+++ + +The SDK supports the following new events: + +* `DialogOpen` +* `DialogClose` + +For more information, see xref:event-embedEvents.adoc[Events reference]. +|==== + +== Version 1.5.0, October 2021 + +[width="100%" cols="1,4"] +|==== +|| +|[tag greenBackground]#NEW FEATURE# | +++
Render embedded objects in queue
+++ + +The SDK now supports rendering embedded objects in a queue. If you have multiple embedded objects, you can enable the `queueMultiRenders` parameter to queue your embedded objects and render them one after another. This feature helps in decreasing the load on the web browsers and improving your application loading experience. By default, this attribute is set to `false`. + +|[tag greenBackground]#NEW FEATURE# a|+++
Liveboard embed
+++ + +The `pinboardEmbed` package includes the `defaultHeight` attribute that sets a minimum height for embedded objects on a pinboard page, and the corresponding visualization pages that a user can navigate to. + +For more information, see xref:embed-search.adoc[Embed a pinboard]. + +|[tag greenBackground]#NEW FEATURE# a|+++
Embed events
+++ + +The SDK EmbedEvent library includes the following new events: + +* `VizPointDoubleClick` +* `Drilldown` +* `SetVisibleVizs` + +For more information, see xref:event-embedEvents.adoc[Events reference]. + +|==== + +== Version 1.4.0, September 2021 + +[width="100%" cols="1,4"] +|==== +|| +|[tag greenBackground]#NEW FEATURE# a|+++
+++Prefetch API+++
+++ + +The `prefetch` API fetches static resources from a given URL before your application loads. Web browsers can then cache the prefetched resources locally and serve them from a user's local disk. You can use this API to load the embedded objects faster and improve your application response time. + +For more information, see xref:prefetch-and-cache.adoc[Prefetch static resources]. + +|[tag greenBackground]#NEW FEATURE# a|+++
+++In-app page navigation+++
+++ + +The `navigateToPage` method in the SDK lets you provide quick and direct access to a specific pinboard, saved Answer, or an application page. You can add a custom menu action or button in your application UI that calls the `navigateToPage` method and leads your users to the page specified in the `path` parameter. + +For more information, see xref:page-navigation.adoc[Add a custom action for in-app navigation]. + +|[tag greenBackground]#NEW FEATURE# a|+++
+++Full application embedding+++
+++ + +The `appEmbed` SDK package includes the following new attributes: + +* The `disableProfileAndHelp` attribute to show or hide the `Help (?)` and the user profile menu in the navigation bar of your embedded app. + +* The `hideObjects` attribute to hide specific objects from a user's page view. + +For more information, see xref:full-embed.adoc[Embed full application]. + +|[tag greenBackground]#NEW FEATURE# |+++
+++Search embed +++
+++ + +The `searchEmbed` package includes the `forceTable` attribute that sets tabular view as the default format for presenting search data. You can set this attribute to `true` to force search results to appear in the table view. + +For more information, see xref:embed-search.adoc[Embed ThoughtSpot search]. + +|[tag redBackground]#REMOVED# | + +The `searchQuery` parameter is no longer supported and is removed from the `searchEmbed` SDK package. +|[tag greenBackground]#NEW FEATURE# a|+++
+++Embed events +++
+++ +The SDK EmbedEvent library includes the following events: + +* `QueryChanged` +* `AuthExpire` + +For more information, see xref:embed-events.adoc[Events and app integration]. +|==== + +== Version 1.3.0, August 2021 + +[width="100%" cols="1,4"] +|==== +|| +|[tag greenBackground]#NEW FEATURE# a| +++
searchOptions
+++ + +The `searchEmbed` SDK package introduces the `searchOptions` parameter for setting search tokens. The `searchOptions` parameter includes the following attributes: + +* `searchTokenString` ++ +A TML query string to define search tokens. + +* `executeSearch` ++ +When set to `true`, it executes search and shows the search results. + +For more information, see xref:embed-search.adoc#search-query[Embed ThoughtSpot search]. + +|[tag redBackground]#DEPRECATED# a| +++
searchQuery
+++ + +The `searchQuery` parameter in the `searchEmbed` SDK package is deprecated in the Visual Embed SDK version 1.3.1. Instead, you can use the `searchOptions` parameter to define the search token string. + +For more information about `searchOptions`, see xref:embed-search.adoc#search-query[Embed ThoughtSpot search]. + +|[tag greenBackground]#NEW FEATURE# a| +++
autoLogin
+++ + +The SDK now supports logging in users automatically after a user session has expired. + +For more information, see xref:embed-authentication.adoc#embed-session-sec[Embed user authentication]. + +|[tag greenBackground]#NEW FEATURE# a| +++
shouldEncodeUrlQueryParams
+++ + +You can now convert query parameters in the ThoughtSpot generated URLs to base64-encoded format. You can enable this attribute to secure your cluster from cross-site scripting attacks. +|[tag redBackground]#BREAKING CHANGE# a| +++
Data structure changes in custom action response payloads
+++ + +* The data structure passed in the custom action response for search now shows as `payload.data.embedAnswerData` instead of `payload.data.columnsAndData`. + +* The Answer payload for custom actions includes the following metadata: + +** `reportBookmetadata` ++ +Includes visualization metadata attributes such as description, object header metadata, author details, timestamp of the Answer creation, and modification. + +** user data ++ +Includes user information such as username, GUID of the user, and email address. + +To view a sample response payload, see xref:callback-response-payload.adoc#search-data-payload[Custom action response payload]. + +|[tag greenBackground]#NEW FEATURE# a| +++
preventPinboardFilterRemoval
+++ + +The `pinboardEmbed` SDK package now includes the `preventPinboardFilterRemoval` attribute. You can use this attribute to disable the filter removal action and thus prevent users from removing the filter chips added on a pinboard page. + +For more information, see xref:embed-pinboard.adoc[Embed a pinboard] and xref:embed-a-viz.adoc[Embed a visualization]. +|[tag greenBackground]#NEW FEATURE# a| +++
suppressNoCookieAccessAlert
+++ + +You can now set custom alerts for `noCookieAccess` events. By default, the SDK triggers a `noCookieAccess` event and generates an alert when a user's browser blocks third-party cookies. The `suppressNoCookieAccessAlert` allows you to disable this alert. + +|[tag greenBackground]#NEW FEATURE# a| +++
Support for fetching callback custom action payload in batches
+++ + +The Visual Embed SDK now supports processing data in batches for callback custom action responses. +The callback custom action event in the SDK package supports defining `batchSize` and `offset` values to paginate the Answer payload and send the records in batches. + +For more information, see xref:push-data-to-external-app.adoc#large-dataset[Callback custom action workflow]. +|==== + +== Version 1.2.0, June 2021 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a|+++
SAML authentication
+++ + +The Visual Embed SDK packages now include the `noRedirect` attribute as an optional parameter for the SAMLRedirect SSO `AuthType`. If you want to display the SAML authentication workflow in a pop-up window, instead of refreshing the application web page to direct users to the SAML login page, you can set the `noRedirect` attribute to `true`. + +For more information, see the instructions for embedding xref:full-embed.adoc[ThoughtSpot pages], xref:embed-search.adoc[search], xref:embed-pinboard.adoc[pinboard], and xref:embed-a-viz.adoc[visualizations]. + +|[tag greenBackground]#NEW FEATURE# a|+++
Pinboard actions
+++ +The *More* menu image:./images/icon-more-10px.png[the more options menu] in the embedded Pinboard page now shows the following actions for pinboard and visualizations. + +Pinboard:: +* Save +* Make a copy +* Add filters +* Configure filters +* Present +* Download as PDF +* Pinboard info +* Manage schedules + + +[NOTE] +Users with edit permissions can view and access the *Save*, *Add filters*, *Configure filters*, and *Manage schedules* actions. +|[tag greenBackground]#NEW FEATURE# a|+++
Visualization actions
+++ + +Visualizations on a pinboard: + +* Pin +* Download +* Edit +* Present +* Download as CSV +* Download as XLSX +* Download as PDF + +[NOTE] +Users with edit permissions can view and access the *Edit* action. The *Download as CSV*, *Download as XLSX*, and *Download as PDF* actions are available for table visualizations. The *Download* action is available for chart visualizations. + +|==== + +== Version 1.1.0, May 2021 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a|+++
NoCookieAccess event
+++ + +When a user accesses the embedded application from a web browser that has third-party cookies disabled, the Visual Embed SDK emits the `NoCookieAccess` event to notify the developer. Cookies are disabled by default in Safari. Users can enable third-party cookies in Safari’s Preferences setting page or use another web browser. +To know how to enable this setting by default on Safari for a ThoughtSpot embedded instance, contact ThoughtSpot Support. +|==== \ No newline at end of file From c152a930a035739745ab62d84de32e16feb6216b Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 17 Aug 2026 10:34:26 +0530 Subject: [PATCH 22/32] docs: add Answer Report API GA section (SCAL-306069) --- modules/ROOT/pages/data-report-v2-api.adoc | 629 +++++++++++++++++---- 1 file changed, 524 insertions(+), 105 deletions(-) diff --git a/modules/ROOT/pages/data-report-v2-api.adoc b/modules/ROOT/pages/data-report-v2-api.adoc index 648618486..f1ed36d8e 100644 --- a/modules/ROOT/pages/data-report-v2-api.adoc +++ b/modules/ROOT/pages/data-report-v2-api.adoc @@ -204,173 +204,592 @@ curl -X POST \ -H 'Accept: application/json'\ -H 'Content-Type: application/json' \ --data-raw '{ - "metadata_identifier": "9bd202f5-d431-44bf-be0b-bb9354c7a840", - "data_format": "COMPACT", - "record_offset": 0, - "record_size": 10 + "metadata_identifier": "f605dbc7-db19-450b-8613-307118f74c3c", }' ---- + == Report APIs -ThoughtSpot provides the following REST API v2 endpoints to download data as reports: -* xref:#_liveboard_report_api[`POST /api/rest/2.0/report/liveboard`] to download a Liveboard or specific visualizations on the Liveboard as a PDF, PNG, or CSV file. -* xref:#answer-report[`POST /api/rest/2.0/report/answer`] to download Answer data as a CSV, XLSX, PDF, or PNG file. +ThoughtSpot provides the following REST API v2 endpoints to fetch data: + +* xref:_liveboard_report_api[`POST /api/rest/2.0/report/liveboard`] + +Download a Liveboard and its visualizations in PDF, PNG, CSV, or XLSX file format. +* xref:#_answer_report_api[`POST /api/rest/2.0/report/answer`] + +Download data from a saved Answer in PDF, PNG, CSV, or XLSX file format. === Liveboard Report API -The Liveboard Report API allows you to programmatically download a Liveboard or specific visualizations as a PDF, PNG, or CSV file via `POST /api/rest/2.0/report/liveboard`. -To use this API endpoint, you need at least view access to the Liveboard. If Role-Based Access Control (RBAC) is enabled on your instance, you also need the `DATADOWNLOADING` privilege or one of the granular download privileges listed below. +To download a Liveboard report via `/api/rest/2.0/report/liveboard` API, you need at least view access to the Liveboard specified in the API request. -The following report types are available: +In the `POST` request body, specify the GUID or name of the Liveboard as `metadata_identifier`. To download reports with specific visualizations, add GUIDs or names of the visualizations in the `visualization_identifiers`. -PDF:: -Downloads the entire Liveboard as a PDF file. +To download visualizations from a specific Liveboard tab, specify the name or GUID of the tab in the `tab_identifiers` parameter. -PNG:: -Downloads a single visualization on the Liveboard as a PNG file. Requires `visualization_identifiers` with a single visualization GUID. +To download a personalized view of the Liveboard, specify the view name in the `personalised_view_identifier` attribute. -CSV:: -Downloads the data from a single visualization on the Liveboard as a CSV file. Requires `visualization_identifiers` with a single visualization GUID. +[IMPORTANT] +==== +* The downloadable file returned in API response file is extensionless. You need to rename the downloaded file by typing in the relevant extension. +* If the Liveboard includes Note tiles, ensure that you do not pass the GUID of Note tiles as `visualization_identifiers` in the API request. Attempting to do so will lead to an error, and the API will return 400 error code in response. +* Attempting to override existing filter values with runtime filters while exporting a Liveboard will result in an error. +* If Role-Based Access Control (RBAC) is enabled, `DATADOWNLOADING` (Can download Data) privilege is required for Liveboard exports. +* If the granular Role-Based Access Control (RBAC) is enabled, the `CAN_DOWNLOAD_DETAILED_DATA` (Can download detailed data) privilege is required to export in the XLSX or CSV formats, and the `CAN_DOWNLOAD_VISUALS` (Can download visuals) privilege is required for PDF or PNG exports. In this case the `DATADOWNLOADING` privilege ceases to exist. +==== -==== Request parameters +==== File Formats -[width="100%" cols="2,1,4"] -[options="header"] -|===== -| Parameter | Required | Description -| `metadata_identifier` | Yes | GUID or name of the Liveboard to download. -| `file_format` | Yes | Report format. Accepted values: `PDF`, `PNG`, `CSV`, `XLSX`. -| `visualization_identifiers` | Conditional | Array of visualization GUIDs. Required when `file_format` is `PNG` or `CSV`. For PDF, optional — if not specified, all visualizations are included. -| `runtime_filter` | No | Runtime filter overrides to apply. -| `runtime_sort` | No | Runtime sort overrides to apply. -| `runtime_param_override` | No | Runtime parameter overrides to apply. -| `transient_content` | No | Liveboard data with unsaved changes. -| `pdf_options` | No | PDF-specific options: `orientation` (`PORTRAIT` or `LANDSCAPE`), `truncate_tables` (boolean), `include_logo`, `footer_text`, `include_page_number`, `cover_page`, `filter_page`. -|===== +The default `file_format` is *CSV*. + +[NOTE] +If you do not have .csv downloads enabled for your ThoughtSpot instance, select either `PDF` or `PNG` `file_format` to successfully download the report. Using any other format will cause the API to return an error. + + +For *CSV* downloads, + +* Each visualization is exported as a separate .csv file. +* If multiple visualizations are selected, the downloaded report is a single compressed .zip file containing all .CSV files. +* It does not support any additional parameters to customize the page orientation and `include_cover_page`, `include_filter_page`, logo, footer text, and page numbers. +* Charts are exported as tabular data. Downloaded reports may include columns not seen in the visualization if they were used as tokens in the underlying search query. + +===== Sample API payload for CSV downloads -==== Example [source,cURL] ---- curl -X POST \ --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/liveboard' \ - -H 'Authorization: Bearer {access-token}' \ - -H 'Accept: application/octet-stream' \ + -H 'Authorization: Bearer {access-token}'\ -H 'Content-Type: application/json' \ - --data-raw '{ - "metadata_identifier": "d084c256-e284-4fc4-b80c-111cb606449a", - "file_format": "PDF", - "pdf_options": { - "orientation": "LANDSCAPE", - "include_logo": true, - "include_page_number": true - } -}' \ - --output liveboard.pdf +--data-raw '{ +"metadata_identifier": "416052fd-ad22-4d48-be0a-e43b53109957", +"file_format": "CSV", +"tab_identifiers": [ +"bc6d6fb8-1e06-4617-b02f-51745e6933a6" +] +}' ---- -[#answer-report] -=== Answer Report API +For *XLSX* downloads, -// SOURCE: SCAL-306069 +* Visualization is exported as an Excel workbook (.xlsx). +* If multiple visualizations are selected, the downloaded report is a single Excel workbook (.xlsx) containing each visualization in their individual tab. +* A maximum of 255 tabs per .xlsx workbook are allowed. +* It does not support any additional parameters to customize the page orientation and `include_cover_page`, `include_filter_page`, logo, footer text, and page numbers. +* Charts are exported as tabular data. Downloaded reports may include columns not seen in the visualization if they were used as tokens in the underlying search query. +* New pivot tables generated in .xlsx workbooks using this API endpoint retain their complete visual formatting and structural integrity. -The `POST /api/rest/2.0/report/answer` endpoint is generally available from 26.9.0.cl. Use this endpoint to export Answer data in CSV, XLSX, PDF, or PNG format. The endpoint supports saved Answers, pinned Answers (visualizations on a Liveboard), and Spotter-generated (ad hoc) Answers. +===== Sample API payload for XLSX downloads -==== Prerequisites +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/liveboard' \ + -H 'Authorization: Bearer {access-token}'\ + -H 'Content-Type: application/json' \ +--data-raw '{ +"metadata_identifier": "416052fd-ad22-4d48-be0a-e43b53109957", +"file_format": "XLSX", +"visualization_identifiers": [ +"254c6e30-680c-41ea-aa4d-bb059f745462" +] +}' +---- -To download Answer data, the user must have at least *View* access to the Answer or Liveboard. If RBAC is enabled: +For *PDF* downloads, you can specify additional parameters to customize the page orientation and include or exclude the cover page, logo, footer text, and page numbers. -* `DATADOWNLOADING` (Can download Data) — required for all export formats. -* `CAN_DOWNLOAD_DETAILED_DATA` (Can download detailed data) — required for CSV and XLSX. -* `CAN_DOWNLOAD_VISUALS` (Can download visuals) — required for PNG. +You can now also download continuous pdfs which matches the full length of your Liveboard, without breaking them into multiple A4 pages. -==== Request parameters +* `page_size = CONTINUOUS` Unlike the A4 format, which introduces forced page breaks between visualizations, this continuous flow maintains your exact design and intended layout. ++ +When `page_size = CONTINUOUS`, the `include_filter_page` option works to show/hide the filter section in the PDF page (in a continuous PDF, there is no separate filter page, but the filters are included on the same page at the top). +* `zoom_level` offers various download size options to suit the viewer's screen dimensions, thereby enhancing legibility. This can be set only when `page_size = CONTINUOUS`. Valid values are integers in the range of 45 and 175. -[width="100%" cols="2,1,4"] -[options="header"] -|===== -| Parameter | Required | Description -| `metadata_identifier` | Conditional | GUID or name of the saved Answer. For pinned Answer exports, use the parent Liveboard GUID or name and pass `viz_guid` separately. -| `file_format` | Yes | Export format. Accepted values: `CSV`, `XLSX`, `PDF`, `PNG`. -| `viz_guid` | No | GUID of a pinned visualization on a Liveboard. When specified, `metadata_identifier` must identify the parent Liveboard. -| `personalised_view_identifier` | No | GUID or name of a Personalized View. When specified, the export uses data from that view. -| `runtime_filter` | No | Runtime filter overrides to apply to the export. -| `runtime_sort` | No | Runtime sort overrides to apply to the export. -| `runtime_param_override` | No | Runtime parameter overrides to apply to the export. -| `x_resolution` | No | Width of the PNG export in pixels. Range: 600–3840. Applies only when `file_format` is `PNG`. Default: 2254. -| `y_resolution` | No | Height of the PNG export in pixels. Range: 600–3840. Applies only when `file_format` is `PNG`. Default: 1588. -| `scaling_factor` | No | Scaling percentage for chart elements in PNG exports. Range: 80–400. Does not crop the image. Applies only when `file_format` is `PNG`. -|===== -==== Export a saved Answer +===== Sample API payload for PDF downloads + +[source,cURL] +---- +curl -X POST 'https://{ThoughtSpot-Host}/api/rest/2.0/report/liveboard' \ +--header 'Authorization: Bearer {access-token}' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "metadata_identifier": "416052fd-ad22-4d48-be0a-e43b53109957", + "file_format": "PDF", + "visualization_identifiers": [ + "254c6e30-680c-41ea-aa4d-bb059f745462" + ], + "pdf_options": { + "page_size": "CONTINUOUS", + "zoom_level": 105, + "include_cover_page": true, + "include_custom_logo": true, + "include_filter_page": true, + "include_page_number": true, + "page_orientation": "PORTRAIT", + "truncate_table": false, + "page_footer_text": "Sample footer text" + } +}' +---- + +For *PNG* downloads, you can now define + +* `image_resolution` +* `image_scale` +* `include_header` + +[IMPORTANT] +==== +* If the above settings are enabled on your instance or you are using a ThoughtSpot release 10.9.0.cl or later, +** You will no longer be able to use the `include_cover_page`, `include_filter_page` within the `png_options`. +** PNG download will support exporting only one tab at a time. If the `tab_identifier` is not specified, the first tab will be downloaded. +* Due to UI limitations in the REST API Playground, you'll notice that some parameters are automatically included in the PNG options JSON. This may cause your API request to fail. As a workaround, click *View JSON* next to the `png_options`, review the parameters, remove additional parameters, and then click *Try it out*. + +==== + +===== Sample API payload for PNG downloads [source,cURL] ---- curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \ - -H 'Authorization: Bearer {access-token}' \ - -H 'Accept: application/octet-stream' \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/liveboard' \ + -H 'Authorization: Bearer {access-token}'\ -H 'Content-Type: application/json' \ --data-raw '{ - "metadata_identifier": "my-saved-answer", - "file_format": "CSV" -}' \ - --output answer.csv + "metadata_identifier": "416052fd-ad22-4d48-be0a-e43b53109957", + "file_format": "PNG", + "tab_identifiers": [ + "bc6d6fb8-1e06-4617-b02f-51745e6933a6" + ], + "png_options": { + "include_cover_page": null, + "include_filter_page": null, + "personalised_view_id": null, + "image_resolution": 1920, + "image_scale": 100, + "include_header": true + } +}' ---- -==== Export a pinned Answer +==== Override filters -[source,cURL] +If the Liveboard has filters applied, and you want to override the filters before downloading the Liveboard, you can specify the filters in the `override_filters` array. + +[source,JSON] ---- curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \ - -H 'Authorization: Bearer {access-token}' \ - -H 'Accept: application/octet-stream' \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/liveboard' \ -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {access-token}' \ --data-raw '{ - "metadata_identifier": "", - "viz_guid": "", - "file_format": "PDF" -}' \ - --output pinned-answer.pdf + "metadata_identifier": "9bd202f5-d431-44bf-9a07-b4f7be372125", + "file_format": "PNG", + "override_filters": [ + { + "column_name": "Color", + "generic_filter": { + "op": "IN", + "values": [ + "almond", + "turquoise" + ] + }, + "negate": false + }, + { + "column_name": "Commit Date", + "date_filter": { + "datePeriod": "HOUR", + "number": 3, + "type": "LAST_N_PERIOD", + "op": "EQ" + } + }, + { + "column_name": "Sales", + "generic_filter": { + "op": "BW_INC", + "values": [ + "100000", + "70000" + ] + }, + "negate": true + } + ], + "png_options": { + "include_cover_page": true, + "include_filter_page": true + } +}' ---- -==== Export a Spotter Answer +[#transient-lb-content] +==== Liveboard data with unsaved changes + +include::{path}/transient-lb-content.adoc[] + +===== Sample browser fetch request + +[source,JavaScript] +---- +< iframe src = "http://ts_host:port/" id = "ts-embed" > < /iframe> +< script src = "/path/to/liveboard.js" > < /script> +< script > + const embed = new LiveboardEmbed("#embed", { + frameParams: {}, + }); + async function liveboardData() { + const transientPinboardContent = await embed.trigger(HostEvent.getExportRequestForCurrentPinboard); + const liveboardDataResponse = await fetch("https://ts_host:port/api/rest/2.0/report/liveboard", { + method: "POST", + body: createFormDataObjectWith({ + "transient_content": transientPinboardContent, + }), + }); + } +< /script> +---- + +See also, link:https://developers.thoughtspot.com/docs/Enumeration_HostEvent#_getexportrequestforcurrentpinboard[HostEvent.getExportRequestForCurrentPinboard]. + +=== Answer Report API + +To download Answer data via `/api/rest/2.0/report/answer` API, you need at least view access to the saved Answer. + +In the request body, specify the GUID or name of the Answer object as `metadata_identifier`. + +The API supports exporting saved Answers, pinned Answers from a Liveboard, and Spotter-generated Answers. You can download Answer data in `CSV`, `XLSX`, `PNG`, and `PDF` format. The default `file_format` is `CSV`. + +[IMPORTANT] +==== +* If Role-Based Access Control (RBAC) is enabled, `DATADOWNLOADING` (Can download Data) privilege is required for Answer exports. +* If the granular Role-Based Access Control (RBAC) is enabled, the `CAN_DOWNLOAD_DETAILED_DATA` (Can download detailed data) privilege is required to export in the PDF, XLSX or CSV formats, and the `CAN_DOWNLOAD_VISUALS` (Can download visuals) privilege is required for PNG exports. In this case the `DATADOWNLOADING` privilege ceases to exist. +==== + +==== Example [source,cURL] ---- curl -X POST \ --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \ - -H 'Authorization: Bearer {access-token}' \ - -H 'Accept: application/octet-stream' \ + -H 'Authorization: Bearer {access-token}'\ -H 'Content-Type: application/json' \ --data-raw '{ - "metadata_identifier": "", - "file_format": "XLSX" -}' \ - --output spotter-answer.xlsx + "metadata_identifier": "9bd202f5-d431-44bf-9a07-b4f7be372125", + "file_format": "PNG" +}' ---- [NOTE] ==== -Pass the answer ID from the Spotter API response as `metadata_identifier`. XLSX and PDF formats are supported for Spotter Answers from 26.9.0.cl. +* Exported files are automatically named after the Answer title, with the file extension appended based on the selected format. +* HTML rendering is not supported for PDF exports of Answers with tables. ==== -==== Export a PNG with custom dimensions + +Contact ThoughtSpot support to enable these enhanced settings for this API endpoint on your ThoughtSpot instance: + +* `personalised_view_identifier` [earlyAccess eaBackground]#Early Access# + +Optional parameter to specify the GUID of the personalised view of the `PINNED` Answer object that you want to download. +* `type` [earlyAccess eaBackground]#Early Access# + +Used to distinguish between a saved answer and a pinned answer on a Liveboard. Setting this parameter to `PINNED` allows the API to +accept the guid of a pinned Answer directly as the `metadata_identifier`. When +exporting an Answer, all Liveboard-level filters, Runtime Filters, and Column +Security Rules (CSR) are automatically applied to the export output. + +The `png_options` [earlyAccess eaBackground]#Early Access# support the following properties: + +[cols="1,1,3"] +|=== +|Property |Type |Description + +|`x_resolution` +|Number +|Width of the exported PNG in pixels. + +Valid range: `600px` to `3840px`. + +|`y_resolution` +|Number +|Height of the exported PNG in pixels. + +Valid range: `600px` to `3840px`. + +|`scaling` +|Integer +|Display scale percentage for objects rendered in the image. Adjusts the relative +size of visual elements without cropping the image. + +Valid range: `80%` to `500%`. +|=== + +You can now export the PNG of any Answer in any aspect ratio and any scaling or zoom level. Just configure, scale, and export exactly what you need. + +[#exportSpotterData] +==== Export data generated from Spotter APIs +To export results generated from Spotter APIs such as `/api/rest/2.0/ai/answer/create`, `/api/rest/2.0/ai/agent/converse/sse`, and `/api/rest/2.0/ai/conversation/{conversation_identifier}/converse`, include the session ID and generation number in the `POST` request body. + +When downloading a Spotter-generated Answer, do not specify the metadata object ID, because you will be exporting the data generated from a conversation session with Spotter and not a saved Answer. + +===== Request example [source,cURL] ---- curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \ - -H 'Authorization: Bearer {access-token}' \ - -H 'Accept: application/octet-stream' \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \ -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ --data-raw '{ - "metadata_identifier": "my-saved-answer", - "file_format": "PNG", - "x_resolution": 3840, - "y_resolution": 2160, - "scaling_factor": 150 -}' \ - --output answer-4k.png + "file_format": "CSV", + "session_identifier": "ee077665-08e1-4a9d-bfdf-7b2fe0ca5c79", + "generation_number": 2 +}' +---- + +* `session_identifier` refers to session ID returned in the Spotter API response. +* `generation_number` indicates the Answer generation number. +* `file_format` specifies the format of the output. You can export the Spotter-generated data as PNG, CSV, XLSX, or PDF file. By default, the API exports this data in PNG file format. + +===== API Response + +If the API request is successful, ThoughtSpot returns the data in the specified file format. You can download the file to use it later or import it into your application environment. + +//// +===== Response codes +[width="100%" cols="2,4"] +[options='header'] +|=== +|HTTP status code|Description +|**200**| Successful operation +|**400**| Invalid parameter +|**401**| Unauthorized access +|**401**| Forbidden request +|**500**| Internal error +|=== +//// + +== Pagination settings for Data APIs + +When you make REST API calls to some v2 Data endpoints to query data, the API may return many rows of data in response. By default, the following parameters are set in API requests to the v2 Data API endpoints: + +[source,JSON] +---- +{ + "data_format": "COMPACT", + "record_offset": 0, + "record_size": 10 +} +---- + +[WARNING] +==== +Do not set `record_size` to `-1`. On ThoughtSpot instances with a large number of objects or users, this can lead to slow responses, excessive logging, and out-of-memory failures. Specify an explicit `record_size` and iterate through pages programmatically. +==== + +The APIs return a maximum of 100000 rows of data at any given time. If you must retrieve a higher number of rows in an API call, contact ThoughtSpot Customer Support to increase the row size limit. However, if the record size and number of rows are high, the API may take a while to fetch the data, and the request may time out. + +== Runtime overrides +The Data API endpoints support the following runtime overrides: + +* Runtime filters +* Runtime sorting of columns +* Runtime Parameters + +=== Runtime filters +To add runtime filters, in the `runtime_filter` property, add the `col1`, `op1`, and `val1` parameters JSON key-value format: + +[source,JSON] +---- +"runtime_filter": { + "col1": "type", + "op1": "EQ", + "val1": "roasted", +} +---- + +To add additional filters, increment the number at the end of each parameter for each filter: for example, col2, op2, val2, and so on. + +[source,JSON] +---- +"runtime_filter": { + "col1": "type", + "op1": "EQ", + "val1": "roasted", + "col2": "tea", + "op2": "EQ", + "val2": "barley" +} +---- + +Some operators such as allow more than one value in the `val` parameter: + +[source,JSON] +---- + "runtime_filter": { + "col1": "tea", + "op1": "CONTAINS", + "val1": [ + "barley", + "mint" + ], + "col2": "type", + "op2": "CONTAINS", + "val2": [ + "roasted", + "loose leaves" + ] +} +---- + +For more information, see xref:runtime-filters.adoc#rtOperator[Supported runtime filter operators] and xref:runtime-filters.adoc#_rest_api_v2_0_endpoints[Apply runtime filters via REST APIs]. + +=== Runtime parameters + +To add runtime Parameters, in the `runtime_param_override` property, add the `param1, and `paramVal1` parameters JSON key-value format. The Parameter value must be defined as per the data type. For example, `Date Param` and `Date List Param` Parameters, specify Epoch time as value. + +To apply Parameter overrides on Liveboards and Answers, ensure that the Parameters are configured in the Model used for generating Liveboard visualizations and Answer. + +[source,JSON] +---- + "runtime_param_override": { + "param1": "Double List Param", + "paramVal1": 0.5 + } +---- + +To add additional Parameter overrides, increment the number at the end of each parameter: for example, paramVal2, and so on. + +[source,JSON] +---- + "runtime_param_override": { + "param1": "Double List Param", + "paramVal1": 0.5, + "param2": "Date Param", + "paramVal2": 1696932000 + } ---- + +For more information, see xref:runtime-parameters.adoc[Runtime Parameter overrides]. + +=== Runtime sort + +To sort columns on a Liveboard or Answer, define runtime sort properties in `runtime_sort` as a key-value pair in JSON format. The `runtime_sort` object allows `sortCol1` and `asc1` properties. To sort more columns, increment the number at the end of the parameter for each key: for example, `sortCol2`, `asc2`, `sortCol3`, `asc3`, and so on. + + +[source,JSON] +---- + "runtime_sort": { + "sortCol1": "sales", + "asc1": true, + "sortCol2": "region", + "asc2": false + } +---- + +For more information, see xref:runtime-sort.adoc#_rest_api_v2_0[Runtime sorting of columns]. + + [#answer-report] + === Answer Report API + + // SOURCE: SCAL-306069 + + The `POST /api/rest/2.0/report/answer` endpoint is generally available from 26.9.0.cl. Use this endpoint to export Answer data in CSV, XLSX, PDF, or PNG format. The endpoint supports saved Answers, pinned Answers (visualizations on a Liveboard), and Spotter-generated (ad hoc) Answers. + + ==== Prerequisites + + To download Answer data, the user must have at least *View* access to the Answer or Liveboard. If RBAC is enabled: + + * `DATADOWNLOADING` (Can download Data) — required for all export formats. + * `CAN_DOWNLOAD_DETAILED_DATA` (Can download detailed data) — required for CSV and XLSX. + * `CAN_DOWNLOAD_VISUALS` (Can download visuals) — required for PNG. + + ==== Request parameters + + [width="100%" cols="2,1,4"] + [options="header"] + |===== + | Parameter | Required | Description + | `metadata_identifier` | Conditional | GUID or name of the saved Answer. For pinned Answer exports, use the parent Liveboard GUID or name and pass `viz_guid` separately. + | `file_format` | Yes | Export format. Accepted values: `CSV`, `XLSX`, `PDF`, `PNG`. + | `viz_guid` | No | GUID of a pinned visualization on a Liveboard. When specified, `metadata_identifier` must identify the parent Liveboard. + | `personalised_view_identifier` | No | GUID or name of a Personalized View. When specified, the export uses data from that view. + | `runtime_filter` | No | Runtime filter overrides to apply to the export. + | `runtime_sort` | No | Runtime sort overrides to apply to the export. + | `runtime_param_override` | No | Runtime parameter overrides to apply to the export. + | `x_resolution` | No | Width of the PNG export in pixels. Range: 600–3840. Applies only when `file_format` is `PNG`. Default: 2254. + | `y_resolution` | No | Height of the PNG export in pixels. Range: 600–3840. Applies only when `file_format` is `PNG`. Default: 1588. + | `scaling_factor` | No | Scaling percentage for chart elements in PNG exports. Range: 80–400. Does not crop the image. Applies only when `file_format` is `PNG`. + |===== + + ==== Export a saved Answer + + [source,cURL] + ---- + curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/octet-stream' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "metadata_identifier": "my-saved-answer", + "file_format": "CSV" + }' \ + --output answer.csv + ---- + + ==== Export a pinned Answer + + [source,cURL] + ---- + curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/octet-stream' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "metadata_identifier": "", + "viz_guid": "", + "file_format": "PDF" + }' \ + --output pinned-answer.pdf + ---- + + ==== Export a Spotter Answer + + [source,cURL] + ---- + curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/octet-stream' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "metadata_identifier": "", + "file_format": "XLSX" + }' \ + --output spotter-answer.xlsx + ---- + + [NOTE] + ==== + Pass the answer ID from the Spotter API response as `metadata_identifier`. XLSX and PDF formats are supported for Spotter Answers from 26.9.0.cl. + ==== + + ==== Export a PNG with custom dimensions + + [source,cURL] + ---- + curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/octet-stream' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "metadata_identifier": "my-saved-answer", + "file_format": "PNG", + "x_resolution": 3840, + "y_resolution": 2160, + "scaling_factor": 150 + }' \ + --output answer-4k.png + ---- + \ No newline at end of file From 3a1db02d6c19c0676e947ad236d28e6ff2ee9b0f Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 17 Aug 2026 10:34:30 +0530 Subject: [PATCH 23/32] docs: add 26.9.0.cl REST API changelog section (SCAL-306069, SCAL-309867, SCAL-306173, SCAL-320899, SCAL-317550, SCAL-307284, SCAL-312738, SCAL-277656) From fbac5b08f4b052ce9baf789870f19eda45f7fa1e Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 17 Aug 2026 10:34:31 +0530 Subject: [PATCH 24/32] docs: add Visual Embed SDK 1.52.x changelog (SCAL-317516, SCAL-314461) From de4cf40fa4c37dd6a56ebf6e1a68bece4cc0b070 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 17 Aug 2026 10:34:32 +0530 Subject: [PATCH 25/32] docs: add Answer Report API GA section (SCAL-306069) From b8701b0cc7fc8ca759b09a7d23a9208334545792 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 17 Aug 2026 10:53:02 +0530 Subject: [PATCH 26/32] docs: add What's New blurb for 26.9.0.cl / aug.26.mt / SDK 1.52.0 Covers: overrideHistoryState (SCAL-317516), HomeLeftNavItem.Collections (SCAL-314461), Answer Export API GA (SCAL-306069), Snowflake Semantic View APIs (SCAL-309867), Spotter Memory GA (SCAL-306173), conversation sharing APIs (aug.26.mt), KPI isSparklineEnabled (SCAL-320899), Personalized Views TML portability GA (SCAL-307284) No existing content removed. New September 2026 section inserted above August 2026. --- modules/ROOT/pages/whats-new.adoc | 596 ++++++++---------------------- 1 file changed, 149 insertions(+), 447 deletions(-) diff --git a/modules/ROOT/pages/whats-new.adoc b/modules/ROOT/pages/whats-new.adoc index 56a89557d..a5e78d5e1 100644 --- a/modules/ROOT/pages/whats-new.adoc +++ b/modules/ROOT/pages/whats-new.adoc @@ -22,6 +22,110 @@ This page lists new features, enhancements, and deprecated functionality introdu // *Status:* Current / Supported / Deprecated // *Affects:* Developers, Administrators, End Users // ============================================================ +== September 2026 + +**Release version**: ThoughtSpot Cloud 26.9.0.cl + +*Upgrade notes*: No breaking changes in this release. + +*Recommended SDK versions*: Visual Embed SDK v1.52.0 and later + +[.cl-table, cols="2,4", frame=none, grid=none] +|=== +a| +[.cl-label] +*Version 26.9.0.cl* + +a| +[discrete] +==== Browser history management in full application embedding [.version-badge.new]#New# + +The Visual Embed SDK 1.52.0 introduces the `overrideHistoryState` configuration parameter for `AppEmbed`. When ThoughtSpot is embedded in a host application, every internal navigation event pushes a new entry onto the browser history stack, causing the browser *Back* button to step through ThoughtSpot's internal pages before returning to the host application. Setting `overrideHistoryState: true` converts ThoughtSpot's internal `pushState` calls to `replaceState`, preventing internal navigation from polluting the host application's browser history stack. For more information, see xref:full-app-embed.adoc[Full application embedding]. + +--- + +[discrete] +==== Collections in embedded left navigation panel [.version-badge.new]#New# + +The `HomeLeftNavItem.Collections` value is now available in the Visual Embed SDK 1.52.0. Embed developers can include *Collections* as a navigation option in the left navigation panel for full application embeds, enabling end users to navigate to *Collections* directly from the embedded experience. For more information, see xref:full-app-customize.adoc[Customize the embedded ThoughtSpot experience]. + +--- + +[discrete] +==== Answer Export API — General Availability [.version-badge.new]#New# + +The Answer Export API (`POST /api/rest/2.0/report/answer`) is now generally available. This release introduces the following enhancements: + +* *Pinned Answer export*: Export a pinned visualization from a Liveboard directly using the `viz_guid` parameter. +* *Personalized View support*: Export data from a specific Personalized View using `personalised_view_identifier`. +* *Spotter Answer export*: Export Spotter-generated answers in `XLSX` and `PDF` formats in addition to `CSV` and `PNG`. +* *Custom PNG dimensions*: Control PNG export dimensions using `x_resolution` and `y_resolution` parameters (600-3840 px). +* *Scaling control*: Adjust chart element size in PNG exports using `scaling_factor` (80-400). + +For more information, see xref:data-report-v2-api.adoc#answer-report[Answer Report API]. + +--- + +[discrete] +==== Snowflake Semantic View integration APIs [.version-badge.new]#New# + +ThoughtSpot introduces four new REST API v2.0 endpoints to manage Snowflake Semantic View integrations programmatically without using the ThoughtSpot UI: + +* `POST /api/rest/2.0/semantic-integrations/create` +* `POST /api/rest/2.0/semantic-integrations/search` +* `POST /api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/import` +* `POST /api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/delete` + +Requires `ADMINISTRATION` or `DATAMANAGEMENT` privilege. For more information, see xref:semantic-integrations-api.adoc[Snowflake Semantic View integration APIs]. + +--- + +[discrete] +==== Spotter Memory — General Availability [.version-badge.new]#New# + +The Spotter memory feature is now generally available. The memory APIs (`POST /api/rest/2.0/ai/memory/import` and `POST /api/rest/2.0/ai/memory/export`) are enabled by default on all ThoughtSpot Cloud instances. Administrators can manage and audit Spotter's training data programmatically. For more information, see xref:spotter-agent-apis.adoc[Spotter agent APIs]. + +--- + +[discrete] +==== Spotter conversation sharing APIs [.version-badge.new]#New# + +ThoughtSpot introduces three new REST API v2.0 endpoints to share Spotter agent conversations programmatically: + +* `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` -- Share a conversation with users or groups with `READ_ONLY` access. +* `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content` -- Retrieve the shared messages and answers in a conversation. +* `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info` -- Retrieve the list of principals a conversation is shared with and their access levels. + +For more information, see xref:spotter-agent-apis.adoc#_sharing_spotter_conversations[Sharing Spotter conversations]. + +--- + +[discrete] +==== KPI sparkline setting in metadata search response [.version-badge.new]#New# + +The `POST /api/rest/2.0/metadata/search` response now includes the `isSparklineEnabled` field in the `AnswerSpecHeader` object for KPI chart type answers. This boolean field indicates whether the sparkline trend line is enabled for a given KPI visualization. + +--- + +[discrete] +==== Personalized Views TML portability — General Availability [.version-badge.new]#New# + +The Personalized Views TML portability feature introduced in Early Access in 26.8.0.cl is now generally available. The `author` and `obj_id` fields are fully supported in exported and imported Personalized View TML. Smart merge import logic is applied by default. For more information, see xref:tml.adoc#personalized-views-portability[Personalized Views portability]. + +--- + +[discrete] +==== Visual Embed SDK +The Visual Embed SDK version 1.52.0 introduces `overrideHistoryState` for browser history management in `AppEmbed` and `HomeLeftNavItem.Collections` for embedded left navigation. For more information, see the xref:api-changelog.adoc[Visual Embed SDK changelog]. + +--- + +[discrete] +==== REST API v2 +For information about REST API v2 enhancements in this release, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. + +--- + +|=== + == August 2026 **Release version**: ThoughtSpot Cloud 26.8.0.cl + @@ -142,78 +246,38 @@ a| a| [discrete] ==== SpotterViz for Liveboards [earlyAccess eaBackground]#Early Access# -You can now use SpotterViz in your embedding application to help your users build and edit Liveboards through a conversational interface. Instead of manually configuring charts and layouts, your users can describe what they want and SpotterViz generates the Liveboard for them, including the new tabs, chart types, data filters, and scheduled deliveries. - -For SpotterViz customization in embedded view, the Visual Embed SDK also provides several options to customize the SpotterViz panel experience. For more information, see xref:embed-spotterViz.adoc[SpotterViz in embedded Liveboards]. +You can now use SpotterViz in your embedding application to help your users build and edit Liveboard visualizations using natural language. SpotterViz replaces the search bar-based experience on Liveboards, enabling users to make changes to their Liveboards through a conversation-style interface. For more information, see xref:spotterviz-liveboards.adoc[SpotterViz for Liveboards]. --- [discrete] -==== Spotter embedding +==== Spotter V3 embedding +Starting from 26.7.0.cl, Spotter V3 is generally available for embedded instances. Spotter V3 introduces the following features and enhancements: -Spotter file upload in embedded apps:: -Applications embedding the Spotter interface can now allow their users to xref:embed-spotter.adoc#_enable_file_upload_in_spotter_chat[upload files directly in the Spotter chat panel]. +* The new xref:embed-spotter.adoc[SpotterEmbed] component replaces the legacy `SearchBarEmbed` component for embedding Spotter experiences. +* SpotterEmbed supports the xref:embed-spotter.adoc#spotterViz[SpotterViz] experience. +* SpotterEmbed supports xref:embed-spotter.adoc#runtime-filters[runtime filters] and xref:embed-spotter.adoc#runtime-filter-operations[runtime filter operations]. +* xref:embed-spotter.adoc#hidden-actions[Action customization] support is extended to SpotterEmbed. -Spotter conversation history:: -You can now save your Spotter conversation and manage chat history using Spotter AI REST APIs. For more information, see xref:spotter-agent-conversation-mgmt-apis.adoc[APIs for managing saved conversations]. - -Spotter Agent instructions:: -You can configure and retrieve behavioral instructions for the Spotter agent using REST APIs. For more information, see xref:spotter-agent-instructions.adoc[Spotter AI agent instructions APIs]. +For more information, see xref:embed-spotter.adoc[Spotter embedding]. --- [discrete] -==== Focused home page experience [earlyAccess eaBackground]#Early Access# - -In full application embedding with the V3 navigation and home page experience, ThoughtSpot provides an additional option to switch to the V4 focused home page experience. The focused home page experience provides a streamlined, contemporary experience along with the Spotter panel. For more information, see xref:full-app-customize.adoc[Customize full application embedding]. +==== SpotterCode breaking change [.version-badge.breaking]#Breaking change# +Starting from 26.7.0.cl, the SpotterCode AI assistant on the developer documentation site now uses the `thoughtspot.ai` domain and the Spotter V3 authentication model. If you have a Content Security Policy (CSP) configuration on your browser that restricts connections to external domains, add `thoughtspot.ai` to the `connect-src` list to maintain access. For more information, see xref:spottercode.adoc[SpotterCode documentation]. --- [discrete] -==== SpotterCode authentication and workflow execution [.version-badge.breaking]#Breaking# -SpotterCode now supports authenticated sessions with your ThoughtSpot instance. When connecting your MCP client to the SpotterCode endpoint, you are now prompted to log in using your organization's identity provider. After authentication, SpotterCode can make ThoughtSpot API calls on your behalf. - -For more information, see the documentation on xref:spottercode.adoc#_mcp_server_endpoints[SpotterCode MCP Server] and xref:spottercode-integration.adoc#_authenticate_spottercode[Authenticating SpotterCode]. - ---- - -[discrete] -==== SpotterCode Agent in Visual Embed Playground [earlyAccess eaBackground]#Early Access# - -The Visual Embed SDK Playground now includes SpotterCode Agent, an AI-powered coding assistant. The SpotterCode panel displays pre-built prompts relevant to the component you are embedding, provides a prompt interface for user queries, and generates embed code. It generates boilerplate code automatically and accelerates building code and iterating embed configurations. - -For more information, see xref:developer-playground.adoc#spottercode-panel[Using SpotterCode in the Playground]. - ---- - -[discrete] -==== Webhooks enhancements - -ThoughtSpot introduces the following features and enhancements for webhook configuration and management: - -* New Webhooks page in the UI [earlyAccess eaBackground]#Early Access# + -The *Develop* page now includes a xref:webhooks-ux.adoc[dedicated *Webhooks* page] for creating, managing, and monitoring webhooks within the Org context. -* Storage configuration retrieval + -The `GET /api/rest/2.0/webhooks/storage-config` REST API endpoint to xref:webhooks-api.adoc#_retrieving_storage_information_for_webhook_configuration[get storage configuration details]. -* GCS storage configuration for webhook delivery + -Administrators can now xref:webhooks-gcs-storage.adoc[configure Google Cloud Storage (GCS) buckets as a storage destination] for webhook payload delivery on GCP-hosted ThoughtSpot clusters. -* Webhook activation and deactivation + -You can enable or disable a webhook connection in the UI or through REST API. -* Selective configuration reset + -The xref:webhooks-api.adoc#_updating_a_webhook[webhook update API endpoint] supports the `reset_options` parameter to remove specific optional configuration sections without replacing the full webhook configuration. - ---- - - -[discrete] -==== Org isolation for per-org SAML and OIDC authentication -ThoughtSpot now enforces strict org isolation when users authenticate through a per-org identity provider (IdP). When a per-org IdP sends SAML or OIDC group claims that reference Orgs outside its authorized scope, ThoughtSpot silently drops those claims and records them as security audit events. This prevents a rogue IdP administrator in one Org from using group assertions to gain unauthorized access to another Org. Manually-assigned existing Org memberships are unaffected. For more information, see xref:orgs.adoc#per-org-sso-isolation[SSO and Org isolation]. +==== Search data REST API — saved formula support +The `POST /api/rest/2.0/searchdata` API now supports referencing saved formulas by name in the `query_string` parameter using bracket syntax (for example, `[Total Revenue] by [Region]` where `Total Revenue` is a saved formula). For more information, see xref:search-data-api.adoc[Search data API]. --- [discrete] ==== Visual Embed SDK -The Visual Embed SDK version 1.50.0 includes several new features and enhancements. For more information, see the xref:api-changelog.adoc[Visual Embed changelog]. +The Visual Embed SDK version 1.50.0 includes new features and enhancements. For more information, see the xref:api-changelog.adoc[Visual Embed SDK changelog]. --- @@ -228,7 +292,7 @@ For information about REST API v2 enhancements in this release, see the xref:res == June 2026 **Release version**: ThoughtSpot Cloud 26.6.0.cl + -*Upgrade notes*: No breaking changes. + +*Upgrade notes*: No breaking changes in this release. + *Recommended SDK versions*: Visual Embed SDK v1.49.0 and later [.cl-table, cols="2,4", frame=none, grid=none] @@ -239,70 +303,37 @@ a| a| [discrete] -==== Chart and table overrides [.version-badge.new]#New# -You can now apply visualization overrides to charts and tables generated from a search query in ThoughtSpot search and full application embedding. The `visualOverrides` property in `SearchViewConfig` and `AppViewConfig` allows developers to apply at the embed initialization time: - -* Chart overrides + -Control legend visibility and position, data label display and per-column filter -thresholds, regression lines, grid lines, axis range and label settings, series -colors, and conditional formatting rules including font and background styling. -* Table overrides + -Control column visibility, text wrapping, row height and padding density, table -theme, and column summary visibility with per-column exceptions. - -For more information, see xref:viz-overrides.adoc[Configuring visualization overrides]. +==== Spotter 3 General Availability +Spotter 3 is now generally available for all ThoughtSpot Cloud instances. For more information, see xref:embed-spotter.adoc[Spotter embedding]. --- [discrete] -==== Spotter AI and embedding enhancements [.version-badge.new]#New# - -This release introduces the following enhancements for Spotter AI workflows and embedded Spotter applications. - -* Spotter embedding: + -Spotter now includes data literacy skills that help users understand the underlying data model. Users can ask Spotter to explain available data sources, fields, and relationships in plain language within a conversation session. -* Spotter AI APIs: + -//** New REST API endpoints to configure and retrieve persistent behavioral xref:spotter-agent-instructions.adoc[instructions for the Spotter agent]. - New API endpoint xref:spotter-agent-apis.adoc#_stop_an_in_progress_agent_response[stop and cancel a long-running Spotter response]. - ---- - -[discrete] -==== Developer page enhancements -The **Develop** page in the ThoughtSpot UI has been updated with the following enhancements: - -* The **Custom actions** list page now shows the code-based custom actions configured using the Visual Embed SDK. -* Removal of REST API v1 + -The legacy REST Playground v1 has been removed from the left navigation. This change does not affect your current integrations with v1 REST API. ThoughtSpot recommends that you update your integration workflows to use REST API v2. For more information, see xref:rest-api-v1v2-comparison.adoc[REST API v1 to v2 migration]. -* Removal of GraphQL playgrounds + -The menu link to the GraphQL playground has been removed from the UI. - -[discrete] -==== Liveboard browser cache refresh -To improve load performance and reduce reload times, you can now enable the Liveboard cache option with a **Refresh** button that lets your users clear the cache and refresh visualization data when required. For more information, see xref:api-changelog.adoc#_liveboard_browser_cache_refresh[Liveboard browser cache refresh]. +==== CSV file upload in Spotter [earlyAccess eaBackground]#Early Access# +Spotter now supports CSV file uploads. Users can upload a CSV file and ask Spotter questions about the data in the file. For more information, see xref:customize-spotter-embed.adoc#_csv_file_upload[Enable CSV file upload]. --- [discrete] ==== Visual Embed SDK -The Visual Embed SDK version 1.49.0 includes several new features and enhancements. For more information, see the xref:api-changelog.adoc[Visual Embed changelog]. +The Visual Embed SDK version 1.49.0 includes new features and enhancements. For more information, see the xref:api-changelog.adoc[Visual Embed SDK changelog]. --- [discrete] ==== REST API v2 -This release introduces new API endpoints for Spotter, connections and trusted authentication. For information about REST API v2 enhancements, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. +For information about REST API v2 enhancements in this release, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. -|=== +--- +|=== == May 2026 **Release version**: ThoughtSpot Cloud 26.5.0.cl + -*Upgrade notes*: ⚠️ Includes breaking changes to Spotter APIs. Refer to the xref:rest-apiv2-changelog.adoc[REST API changelog] for more information. + +*Upgrade notes*: No breaking changes in this release. + *Recommended SDK versions*: Visual Embed SDK v1.48.0 and later - [.cl-table, cols="2,4", frame=none, grid=none] |=== a| @@ -310,302 +341,86 @@ a| *Version 26.5.0.cl* a| - - [discrete] -==== Liveboard downloads - -Continuous Liveboard PDF export [beta betaBackground]^Beta^:: -In PDF downloads, Liveboard tabs can now be rendered in a single page matching the UI layout. This feature can be enabled by setting `isContinuousLiveboardPDFEnabled` to `true` in the SDK. Setting this flag to `false` returns to the paginated PDF view. - -Liveboard download in XLSX and CSV formats:: -Embedded Liveboards can now be downloaded in the PDF, XLSX and CSV file formats. To enable this feature, ensure that the `isLiveboardXLSXCSVDownloadEnabled` parameter is set to `true`. - -Excel exports for pivot tables:: -Pivot table visualizations can now be exported to Excel format. - -For more information, see xref:embed-pinboard.adoc#_liveboard_download_options[Liveboard download options]. - ---- - -[discrete] -==== Visualization edit interface within the Liveboard view - -Users can now edit the underlying query of an answer directly within the Liveboard. When this feature is enabled, the edit button for visualization appears in the answer's floating toolbar when the Liveboard is opened in the edit mode. Clicking the edit button opens the Answer interface preloaded with the answer's current query context. You can make the edits and save the changes without leaving the Liveboard. - ---- - -[discrete] -==== KPI charts in embedded Liveboards - -Embedded Liveboards support advanced controls KPI chart customization. For more information, see link:https://docs.thoughtspot.com/cloud/latest/chart-kpi#advanced[KPI charts]. - ---- - -[discrete] -==== Per-org and per-user timezone control via variables [beta betaBackground]^Beta^ - -You can centrally control timezone behavior per org and per user in embedded deployments using the new template variable `ts_user_timezone` and Variable APIs. - -For multi-org and multi-tenant environments, each tenant org and user can be configured independently, guaranteeing isolation and consistency of time-based analytics across regions. Administrators can reference the timezone variable in formulas to render and filter timestamp data correctly for each embedded user, without separate content per region. - ---- - -[discrete] -==== Timezone-aware keyword filtering [beta betaBackground]^Beta^ -ThoughtSpot now supports resolving relative date and time keywords, such as `today`, `yesterday`, and `last 7 days`, using a configurable per-user or per-Org timezone, instead of the system default timezone on a ThoughtSpot instance. This feature eliminates timezone-based inconsistencies in multi-region embedded deployments and removes the need for custom workarounds. - -For more information, see xref:timezone.adoc[Timezone-aware keywords and filters]. - -[NOTE] -==== -The timezone awareness feature is in Beta and disabled by default. To enable this feature, contact ThoughtSpot Support. -==== - +==== Spotter 3 Early Access [earlyAccess eaBackground]#Early Access# +Spotter 3 is available in Early Access for embedded instances. For more information, see xref:embed-spotter.adoc[Spotter embedding]. --- [discrete] ==== Visual Embed SDK -The Visual Embed SDK version 1.48.0 includes several new features and enhancements. For more information, see the xref:api-changelog.adoc[Visual Embed changelog]. +The Visual Embed SDK version 1.48.0 includes new features and enhancements. For more information, see the xref:api-changelog.adoc[Visual Embed SDK changelog]. --- [discrete] ==== REST API v2 -This release introduces new Spotter API endpoints and modifications to the agent conversation APIs, and deprecates legacy agent endpoints. For information about REST API v2 enhancements, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. +For information about REST API v2 enhancements in this release, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. -|=== +--- +|=== == April 2026 **Release version**: ThoughtSpot Cloud 26.4.0.cl + -*Upgrade notes*: ⚠️ Variable update and delete API and metadata parameterization endpoints are deprecated and replaced with new API endpoints. Refer to xref:rest-apiv2-changelog.adoc#version_26_4_0_cl_april_2026[REST API changelog] and xref:deprecated-features.adoc[Deprecation announcements]. + +*Upgrade notes*: No breaking changes in this release. + *Recommended SDK versions*: Visual Embed SDK v1.47.0 and later [.cl-table, cols="2,4", frame=none, grid=none] |=== - a| [.cl-label] *Version 26.4.0.cl* a| - -[discrete] -==== Theme builder in AI mode - -The Theme Builder now has an AI mode that enables developers to explore and preview style customizations for their embedded application's branding using natural language instructions and uploaded brand assets. You can execute style updates such as applying colors directly from a PDF branding guide, updating all button shapes with higher contrast, matching a header to a dark background based on a screenshot, or importing typography and spacing from a JSON file. In the AI mode, Theme builder interprets your intent and applies the changes instantly. - -For more information, see xref:theme-builder.adoc[Theme builder]. - ---- - - -[discrete] -==== Webhook integration -In this release version, the following enhancements are introduced in the webhook configuration and delivery status monitoring workflows: - -Channel validation:: -Administrators can verify the connection status of a webhook channel by sending a test payload in a `POST` request to the `/api/rest/2.0/system/communication-channels/validate` REST API endpoint. For more information, see xref:webhooks-comm-channel.adoc#_validate_communication_channel_configuration[Webhook channel validation]. - -Monitor webhook delivery:: -Administrators can also monitor the status of a webhook delivery via a `POST /api/rest/2.0/jobs/history/communication-channels/search` API request. For more information, see xref:webhooks-comm-channel.adoc#_monitor_webhook_delivery_and_job_status[Monitor webhook delivery and job status]. - -Support for custom HTTP headers in webhook requests:: -When configuring or updating a webhook, you can now specify custom headers to include in every outbound request, in addition to the standard HTTP and authentication headers that ThoughtSpot sends. For more information, refer to the xref:webhooks-lb-schedule.adoc#_create_a_webhook[webhook documentation]. - ---- - - -[discrete] -==== Spotter embed enhancements -You can now customize the appearance and contents of the chat history sidebar panel in Spotter embedding. - -You can also customize the branding and logo in the Spotter chat interface. - -For more information, see xref:embed-spotter.adoc#_chat_history_panel[Customizing chat history sidebar] and xref:embed-spotter.adoc#_hiding_the_spotter_icon_and_thoughtspot_branding_chat_interface[Hiding logo and brand label in Spotter chat interface]. - ---- - -[discrete] -==== Liveboard enhancements -The following enhancements are introduced in Liveboard export and filtering workflows. - -Embedding a personalized Liveboard view:: -You can now embed a saved personalized Liveboard view using the `personalizedViewId` and load it along with the `liveboardId` in your app. - -Centralized filter modal:: -Liveboard users can modify multiple filters and parameters in a single session using the centralized filter modal. This is an early access feature and disabled by default on ThoughtSpot embedded instances. To enable this feature on embedded Liveboards, set the `isCentralizedLiveboardFilterUXEnabled` to `true`. - -Current period inclusion in rolling date filters:: -The rolling date filters with the **Last ** and **Next ** filter types support including current period. Developers can disable, show, or hide this option using `isThisPeriodInDateFiltersEnabled` or `Action.IncludeCurrentPeriod`. - -Liveboard PNG export:: -The PNG export workflow in the `/api/rest/2.0/report/liveboard` REST API is enhanced to provide high-resolution PNG files. The legacy PNG workflow is deprecated in 26.4.0.cl. For more information about breaking changes and deprecation guidelines, see xref:deprecated-features.adoc[Deprecation announcements]. For information about the new PNG download workflow, see xref:data-report-v2-api.adoc#_liveboard_report_api[Liveboard report API documentation]. - ---- - - -[discrete] -==== Full app embedding -In full application embedded deployments with the V3 navigation and home page experience, the default list page experience is set to ListPage v3 experience. - -The ListPage V3 experience provides a refreshed list layout and styling, including the following enhancements: - -* The **Views** column to show the number of views for each object. -* Sorting options for **Name**, **Author**, and **Views** columns. -* Filters can be added by clicking the column header without opening the filter modal. This option is available for **Favorites**, **Views** columns, and **Verified** columns. - -For more information, see xref:full-app-customize.adoc#_customize_list_page_experience[List page customization]. - ---- - - -[discrete] -==== Variable API -The variable REST API provides new API endpoints for the following bulk operations: - -* Bulk deletion: -You can now delete multiple variables in a single API request using the `/api/rest/2.0/template/variables/delete` endpoint. -* Batch update of variable values: -You can now assign and update multiple values to a variable in a single API request using the `/api/rest/2.0/template/variables/{identifier}/update-values` endpoint. - -[NOTE] -==== -The `/api/rest/2.0/template/variables/update-values` and `/api/rest/2.0/template/variables/{identifier}/delete` endpoints are now deprecated. Use the new `/api/rest/2.0/template/variables/{identifier}/update-values` and `/api/rest/2.0/template/variables/delete` endpoints for the variable update and delete operations instead. -==== - -For more information, see xref:variables.adoc[Variables documentation]. - ---- - - -[discrete] -==== Metadata parameterization -You can now parameterize multiple properties of metadata objects using `POST /api/rest/2.0/metadata/parameterize-fields`. The legacy endpoint `/api/rest/2.0/metadata/parameterize` is deprecated in 26.4.0.cl and later versions, and is replaced with the new endpoint to allow updating multiple fields in a single API request. - -For more information, see xref:metadata-parameterization.adoc[Metadata parameterization documentation]. - ---- - - -[discrete] -==== Collections [beta betaBackground]^Beta^ -ThoughtSpot embedded users can now use REST APIs v2 to organize different ThoughtSpot objects into organizational containers called *Collections*. These objects can be Liveboards, Answers, data models, tables, and even other Collections. - -For more information, see xref:collections.adoc[Collections]. - -[NOTE] -==== -These APIs are currently in beta and turned off by default on ThoughtSpot instances. To enable this feature on your instance, contact ThoughtSpot Support. -==== ---- - [discrete] ==== Visual Embed SDK -For information about the new features and enhancements introduced in Visual Embed SDK version 1.46.0, see the xref:api-changelog.adoc[Visual Embed changelog]. +The Visual Embed SDK version 1.47.0 includes new features and enhancements. For more information, see the xref:api-changelog.adoc[Visual Embed SDK changelog]. +--- [discrete] ==== REST API v2 -For information about REST API v2 enhancements, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. +For information about REST API v2 enhancements in this release, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. --- + |=== == March 2026 **Release version**: ThoughtSpot Cloud 26.3.0.cl + -*Upgrade notes*: ⚠️ Includes feature deprecations. Refer to xref:rest-apiv2-changelog.adoc#_custom_access_token_api[REST API changelog] and xref:deprecated-features.adoc[Deprecation announcements]. + +*Upgrade notes*: No breaking changes in this release. + *Recommended SDK versions*: Visual Embed SDK v1.46.0 and later [.cl-table, cols="2,4", frame=none, grid=none] |=== - a| [.cl-label] *Version 26.3.0.cl* a| -[discrete] -==== Amazon S3 storage destination for webhook delivery -You can now configure ThoughtSpot to deliver webhook payloads and attachments directly into your own Amazon S3 storage using secure AWS cross-account access. To enable this integration, your AWS administrator must create an IAM role with S3 permissions and trust policy, and then register a webhook in ThoughtSpot to deliver the payloads and attachments directly to your S3 bucket. - -For more information, see xref:webhooks-s3-storage.adoc[Amazon S3 storage integration for webhook delivery]. - ---- - -[discrete] -==== Host event enhancements for context-aware routing - -HostEvents in the Visual Embed SDK are enhanced to improve event routing and context targeting in ThoughtSpot embedded applications. - -Developers can use the page context framework in the SDK to route host events to a specific UI layer and align user experience with the product UI behavior in multi-modal contexts. - -For more information, see xref:events-context-aware-routing.adoc[Context-based execution of host events]. - ---- - -[discrete] -==== JWT-based ABAC implementation -The legacy JWT-based approach that uses `filter_rules` and `parameter_values` to implement Attribute-Based Access Control (ABAC) is deprecated. - -As part of this deprecation, the following changes have been introduced to the custom authentication token API workflow and REST API Playground: - -* The `filter_rules` parameter on the custom token authentication page in the REST API Playground is no longer available for new configurations. This change does not affect your existing implementation. - -* The `parameter_values` property is not deprecated in version 26.3.0.cl and remains supported until further notice. However, using parameter values for row-level security use cases will ultimately be deprecated in an upcoming release. - -Existing ABAC implementations that use `filter_rules` will continue to function until further notice. However, we strongly recommend migrating your legacy ABAC implementation to the ABAC via RLS method that uses custom variables. For migration steps, refer to the xref:abac-migration-guide.adoc[ABAC migration guide]. - -For new deployments, use ABAC via RLS with custom variables and pass data security attributes through the `variable_values` property in the custom access token, and define your RLS rules based on those variables. For more information, see xref:abac_rls-variables.adoc[ABAC via RLS]. - ---- - -[discrete] -==== Spotter coaching access across published Orgs -Starting with the 26.3.0.cl release, ThoughtSpot supports publishing Spotter coaching information to other Orgs. Coaching changes from the primary Org are synchronized with the data models published in secondary Orgs. - -Administrators and users with edit access to data models can programmatically control user access to Spotter coaching information using the object privilege REST API endpoint, `/api/rest/2.0/security/metadata/manage-object-privilege`. They can assign `SPOTTER_COACHING_PRIVILEGE` to other users and user groups, allowing access to the coaching information without requiring data model editing or administration privileges. - -Users and groups with `SPOTTER_COACHING_PRIVILEGE` can import and export coaching TML on data models in the source and destination Orgs where the model is published, and can also share these objects with other users and groups. - -For more information, see xref:spotter-nl-instructions.adoc#_spotter_data_model_instructions_access[Spotter data model instructions access]. - ---- - -[discrete] -==== Full application embedding -The height and aspect ratio of the logo in the top-left corner of the ThoughtSpot application interface have been updated for visual alignment and consistency across pages. This enhancement is available only in the V3 navigation and home page experience. - -If you have embedded the full application with the V3 navigation experience, you may notice that the logo appears smaller in the top navigation. This is a design update and does not require any configuration changes to your current embedding implementation. However, we recommend that you review the logo size and appearance, and adjust your custom logo if necessary. - -For information about adding a custom logo image, see xref:customize-style.adoc#logo-change[Customize application logo and favicon]. - ---- - [discrete] ==== Visual Embed SDK -For information about the new features and enhancements introduced in Visual Embed SDK version 1.46.0, see the xref:api-changelog.adoc[Visual Embed changelog]. +The Visual Embed SDK version 1.46.0 includes new features and enhancements. For more information, see the xref:api-changelog.adoc[Visual Embed SDK changelog]. --- [discrete] ==== REST API v2 -For information about REST API v2 enhancements, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. +For information about REST API v2 enhancements in this release, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. --- |=== == February 2026 + **Release version**: ThoughtSpot Cloud 26.2.0.cl + -*Upgrade notes*: ⚠️ Includes API parameter deprecations. Refer to xref:rest-apiv2-changelog.adoc[REST API changelog] and xref:deprecated-features.adoc[Deprecation announcements]. + +*Upgrade notes*: No breaking changes in this release. + *Recommended SDK versions*: Visual Embed SDK v1.45.0 and later - [.cl-table, cols="2,4", frame=none, grid=none] |=== a| @@ -613,146 +428,33 @@ a| *Version 26.2.0.cl* a| -[discrete] -==== SpotterCode extension for IDEs [earlyAccess eaBackground]#Early Access# - -ThoughtSpot introduces SpotterCode, an AI-powered Model Context Protocol (MCP) extension for Integrated Development Environments (IDEs) such as Cursor, Visual Studio Code, and Claude Code. When integrated, SpotterCode enables the AI agent in the IDE to access ThoughtSpot SDKs and API documentation resources and provide in-context coding assistance to developers embedding ThoughtSpot content within their applications. - -SpotterCode is available as an Early Access feature and can be integrated with development environments that support MCP servers and tools. For more information, see xref:spottercode.adoc[SpotterCode], xref:spottercode-integration.adoc[Integrating SpotterCode in IDEs], and xref:spottercode-prompt-guide.adoc[SpotterCode prompting guide]. - ---- - -[discrete] -==== Spotter 3 experience [earlyAccess eaBackground]#Early Access# -You can now embed the Spotter 3 experience, which introduces several new capabilities, agentic analytics, and an enhanced user experience. Spotter 3 is an Early Access feature and is disabled by default on ThoughtSpot embedded instances. - -For more information, see xref:embed-ai-analytics.adoc[Embed AI Search and Analytics] and xref:embed-spotter.adoc[Spotter embedding documentation]. - ---- - -[discrete] -==== Rate limits for REST APIs -To prevent excessive requests from reaching application servers and ensure API stability and service quality for REST API users, ThoughtSpot enforces rate limits on public API requests per client IP. These limits are applied globally at the cluster level for all public API requests, including calls to both REST API v1 and v2 endpoints. -//Administrators can adjust these limits for their ThoughtSpot deployments as needed. - -For more information, see xref:about-rest-apis.adoc#_rate_limits_for_api_requests[Rate limits for REST APIs]. - ---- - -[discrete] -==== Security settings via REST APIs -Security settings that ensure data security and a seamless embedded user experience can now be configured through REST APIs v2. Administrators and developers can configure allowlists for: - -* Content Security Policy (CSP) -* Cross-origin Resource Sharing (CORS) -* Authentication attributes -* Access control settings - -For more information, see xref:security-settings.adoc[Security Settings]. - ---- - -[discrete] -==== WebSocket support for external tools -ThoughtSpot supports secure WebSocket (`wss://`) endpoints for external tool script integrations, for example, tools that open WebSocket connections from the browser. - -To allow a WebSocket host, add the corresponding `wss://` URL to both your CSP allowlists. Only hosts explicitly listed with the `wss://` protocol are permitted. Existing `https://` entries in the allowlists remain unchanged and continue to function as expected. - -For more information, see xref:3rd-party-script.adoc#_allow_websocket_endpoints[External tools and script integration]. - ---- - - [discrete] ==== Visual Embed SDK -For information about the new features and enhancements introduced in Visual Embed SDK version 1.45.0, see the xref:api-changelog.adoc[Visual Embed changelog]. +The Visual Embed SDK version 1.45.0 includes new features and enhancements. For more information, see the xref:api-changelog.adoc[Visual Embed SDK changelog]. --- [discrete] ==== REST API v2 -For information about REST API v2 enhancements, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. +For information about REST API v2 enhancements in this release, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. --- -|=== +|=== == January 2026 -**Release version**: ThoughtSpot Cloud 10.15.0.cl + -*Upgrade notes*: No breaking changes. + +**Release version**: ThoughtSpot Cloud 26.1.0.cl + +*Upgrade notes*: No breaking changes in this release. + *Recommended SDK versions*: Visual Embed SDK v1.44.0 and later - [.cl-table, cols="2,4", frame=none, grid=none] |=== a| [.cl-label] -*Version 10.15.0.cl* +*Version 26.1.0.cl* a| -[discrete] -==== Theme Builder -Theme Builder is now generally available (GA) and will be rolled out to all ThoughtSpot instances in customer deployments over the next few weeks. - -When this feature is enabled on your instance, you can access it from the *Develop* page in ThoughtSpot and use it to customize styles and UX themes directly within the product. - -For more information, see xref:theme-builder.adoc[Theme Builder]. - ---- - -[discrete] -==== V3 navigation and home page experience - -The new V3 navigation and home page experience is now generally available (GA) and can be enabled on ThoughtSpot embedded instances. - -The default UI experience in full application embedding remains the classic (V1) experience until further notice. Developers embedding the full ThoughtSpot application can enable the V3 experience in their applications by setting the appropriate configuration options in their embed code. - -For more information, see xref:full-app-customize.adoc[Customizing full application embedding]. - ---- - -[discrete] -==== Formula variables in RLS rules - -You can now create formula variables using the Variable REST API and use these variables in RLS rules for a specific data context and in ABAC token requests to dynamically assign security attributes to users. - -For more information, see xref:abac_rls-variables.adoc[ABAC via RLS with variables]. - ---- - -[discrete] -==== Spotter APIs - -ThoughtSpot introduces new REST APIs for the following Spotter workflows: - -* To send queries to a conversation session with the Spotter agent -* To set natural language (NL) instructions on a model to coach the Spotter system -* To fetch NL instructions configured on a model - -For more information, see xref:spotter-apis.adoc[Spotter APIs]. - ---- - -[discrete] -==== Embed events and parameters to intercept API calls -You can now intercept API calls from the embedded ThoughtSpot application using the `interceptUrls` attribute in the Visual Embed SDK. This feature lets you control API requests in your embedding application and use embed events to modify, block, or handle requests before they are sent to the backend. For more information, see xref:api-intercept.adoc[Intercept API calls and search requests]. - ---- - -[discrete] -==== Icon customization enhancements - -You can now replace or customize the chart switcher toggle and icons in the Charts drawer on an Answer or visualization page using SVG sprites. Previously, these icons were fixed to ThoughtSpot defaults and were not configurable. In the new version, these icons are available as SVG components and can be replaced by developers through the xref:customize-icons.adoc[icon customization framework] as needed. - ---- - -[discrete] -==== Mobile Embed SDK -The SDKs for embedding ThoughtSpot components in mobile apps are now Generally Available (GA). For more information about the SDKs and how to embed a ThoughtSpot component in a mobile app, see xref:mobile-embed.adoc[Mobile embed documentation]. - ---- - [discrete] ==== Visual Embed SDK For information about the new features and enhancements introduced in Visual Embed SDK version 1.44.0, see xref:api-changelog.adoc[Visual Embed changelog]. From fd3a26dc88a56b7040abac6dd8132310e7100cd6 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 17 Aug 2026 10:53:50 +0530 Subject: [PATCH 27/32] docs: add What's New blurb for 26.9.0.cl / aug.26.mt / SDK 1.52.0 New September 2026 section inserted above August 2026. All existing content preserved. Covers: overrideHistoryState (SCAL-317516), HomeLeftNavItem.Collections (SCAL-314461), Answer Export API GA (SCAL-306069), Snowflake Semantic View APIs (SCAL-309867), Spotter Memory GA (SCAL-306173), conversation sharing APIs, KPI isSparklineEnabled (SCAL-320899), Personalized Views TML portability GA (SCAL-307284) --- modules/ROOT/pages/whats-new.adoc | 624 ++++++++++++++++++++++++------ 1 file changed, 513 insertions(+), 111 deletions(-) diff --git a/modules/ROOT/pages/whats-new.adoc b/modules/ROOT/pages/whats-new.adoc index a5e78d5e1..73c23be30 100644 --- a/modules/ROOT/pages/whats-new.adoc +++ b/modules/ROOT/pages/whats-new.adoc @@ -24,109 +24,109 @@ This page lists new features, enhancements, and deprecated functionality introdu // ============================================================ == September 2026 -**Release version**: ThoughtSpot Cloud 26.9.0.cl + -*Upgrade notes*: No breaking changes in this release. + -*Recommended SDK versions*: Visual Embed SDK v1.52.0 and later + **Release version**: ThoughtSpot Cloud 26.9.0.cl + + *Upgrade notes*: No breaking changes in this release. + + *Recommended SDK versions*: Visual Embed SDK v1.52.0 and later -[.cl-table, cols="2,4", frame=none, grid=none] -|=== -a| -[.cl-label] -*Version 26.9.0.cl* + [.cl-table, cols="2,4", frame=none, grid=none] + |=== + a| + [.cl-label] + *Version 26.9.0.cl* -a| -[discrete] -==== Browser history management in full application embedding [.version-badge.new]#New# + a| + [discrete] + ==== Browser history management in full application embedding [.version-badge.new]#New# -The Visual Embed SDK 1.52.0 introduces the `overrideHistoryState` configuration parameter for `AppEmbed`. When ThoughtSpot is embedded in a host application, every internal navigation event pushes a new entry onto the browser history stack, causing the browser *Back* button to step through ThoughtSpot's internal pages before returning to the host application. Setting `overrideHistoryState: true` converts ThoughtSpot's internal `pushState` calls to `replaceState`, preventing internal navigation from polluting the host application's browser history stack. For more information, see xref:full-app-embed.adoc[Full application embedding]. + The Visual Embed SDK 1.52.0 introduces the `overrideHistoryState` configuration parameter for `AppEmbed`. When ThoughtSpot is embedded in a host application, every internal navigation event pushes a new entry onto the browser history stack, causing the browser *Back* button to step through ThoughtSpot's internal pages before returning to the host application. Setting `overrideHistoryState: true` converts ThoughtSpot's internal `pushState` calls to `replaceState`, preventing internal navigation from polluting the host application's browser history stack. For more information, see xref:full-app-embed.adoc[Full application embedding]. ---- + --- -[discrete] -==== Collections in embedded left navigation panel [.version-badge.new]#New# + [discrete] + ==== Collections in embedded left navigation panel [.version-badge.new]#New# -The `HomeLeftNavItem.Collections` value is now available in the Visual Embed SDK 1.52.0. Embed developers can include *Collections* as a navigation option in the left navigation panel for full application embeds, enabling end users to navigate to *Collections* directly from the embedded experience. For more information, see xref:full-app-customize.adoc[Customize the embedded ThoughtSpot experience]. + The `HomeLeftNavItem.Collections` value is now available in the Visual Embed SDK 1.52.0. Embed developers can include *Collections* as a navigation option in the left navigation panel for full application embeds, enabling end users to navigate to *Collections* directly from the embedded experience. For more information, see xref:full-app-customize.adoc[Customize the embedded ThoughtSpot experience]. ---- + --- -[discrete] -==== Answer Export API — General Availability [.version-badge.new]#New# + [discrete] + ==== Answer Export API — General Availability [.version-badge.new]#New# -The Answer Export API (`POST /api/rest/2.0/report/answer`) is now generally available. This release introduces the following enhancements: + The Answer Export API (`POST /api/rest/2.0/report/answer`) is now generally available. This release introduces the following enhancements: -* *Pinned Answer export*: Export a pinned visualization from a Liveboard directly using the `viz_guid` parameter. -* *Personalized View support*: Export data from a specific Personalized View using `personalised_view_identifier`. -* *Spotter Answer export*: Export Spotter-generated answers in `XLSX` and `PDF` formats in addition to `CSV` and `PNG`. -* *Custom PNG dimensions*: Control PNG export dimensions using `x_resolution` and `y_resolution` parameters (600-3840 px). -* *Scaling control*: Adjust chart element size in PNG exports using `scaling_factor` (80-400). + * *Pinned Answer export*: Export a pinned visualization from a Liveboard directly using the `viz_guid` parameter. + * *Personalized View support*: Export data from a specific Personalized View using `personalised_view_identifier`. + * *Spotter Answer export*: Export Spotter-generated answers in `XLSX` and `PDF` formats in addition to `CSV` and `PNG`. + * *Custom PNG dimensions*: Control PNG export dimensions using `x_resolution` and `y_resolution` parameters (600-3840 px). + * *Scaling control*: Adjust chart element size in PNG exports using `scaling_factor` (80-400). -For more information, see xref:data-report-v2-api.adoc#answer-report[Answer Report API]. + For more information, see xref:data-report-v2-api.adoc#answer-report[Answer Report API]. ---- + --- -[discrete] -==== Snowflake Semantic View integration APIs [.version-badge.new]#New# + [discrete] + ==== Snowflake Semantic View integration APIs [.version-badge.new]#New# -ThoughtSpot introduces four new REST API v2.0 endpoints to manage Snowflake Semantic View integrations programmatically without using the ThoughtSpot UI: + ThoughtSpot introduces four new REST API v2.0 endpoints to manage Snowflake Semantic View integrations programmatically without using the ThoughtSpot UI: -* `POST /api/rest/2.0/semantic-integrations/create` -* `POST /api/rest/2.0/semantic-integrations/search` -* `POST /api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/import` -* `POST /api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/delete` + * `POST /api/rest/2.0/semantic-integrations/create` + * `POST /api/rest/2.0/semantic-integrations/search` + * `POST /api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/import` + * `POST /api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/delete` -Requires `ADMINISTRATION` or `DATAMANAGEMENT` privilege. For more information, see xref:semantic-integrations-api.adoc[Snowflake Semantic View integration APIs]. + Requires `ADMINISTRATION` or `DATAMANAGEMENT` privilege. For more information, see xref:semantic-integrations-api.adoc[Snowflake Semantic View integration APIs]. ---- + --- -[discrete] -==== Spotter Memory — General Availability [.version-badge.new]#New# + [discrete] + ==== Spotter Memory — General Availability [.version-badge.new]#New# -The Spotter memory feature is now generally available. The memory APIs (`POST /api/rest/2.0/ai/memory/import` and `POST /api/rest/2.0/ai/memory/export`) are enabled by default on all ThoughtSpot Cloud instances. Administrators can manage and audit Spotter's training data programmatically. For more information, see xref:spotter-agent-apis.adoc[Spotter agent APIs]. + The Spotter memory feature is now generally available. The memory APIs (`POST /api/rest/2.0/ai/memory/import` and `POST /api/rest/2.0/ai/memory/export`) are enabled by default on all ThoughtSpot Cloud instances. Administrators can manage and audit Spotter's training data programmatically. For more information, see xref:spotter-agent-apis.adoc[Spotter agent APIs]. ---- + --- -[discrete] -==== Spotter conversation sharing APIs [.version-badge.new]#New# + [discrete] + ==== Spotter conversation sharing APIs [.version-badge.new]#New# -ThoughtSpot introduces three new REST API v2.0 endpoints to share Spotter agent conversations programmatically: + ThoughtSpot introduces three new REST API v2.0 endpoints to share Spotter agent conversations programmatically: -* `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` -- Share a conversation with users or groups with `READ_ONLY` access. -* `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content` -- Retrieve the shared messages and answers in a conversation. -* `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info` -- Retrieve the list of principals a conversation is shared with and their access levels. + * `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` -- Share a conversation with users or groups with `READ_ONLY` access. + * `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content` -- Retrieve the shared messages and answers in a conversation. + * `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info` -- Retrieve the list of principals a conversation is shared with and their access levels. -For more information, see xref:spotter-agent-apis.adoc#_sharing_spotter_conversations[Sharing Spotter conversations]. + For more information, see xref:spotter-agent-apis.adoc#_sharing_spotter_conversations[Sharing Spotter conversations]. ---- + --- -[discrete] -==== KPI sparkline setting in metadata search response [.version-badge.new]#New# + [discrete] + ==== KPI sparkline setting in metadata search response [.version-badge.new]#New# -The `POST /api/rest/2.0/metadata/search` response now includes the `isSparklineEnabled` field in the `AnswerSpecHeader` object for KPI chart type answers. This boolean field indicates whether the sparkline trend line is enabled for a given KPI visualization. + The `POST /api/rest/2.0/metadata/search` response now includes the `isSparklineEnabled` field in the `AnswerSpecHeader` object for KPI chart type answers. This boolean field indicates whether the sparkline trend line is enabled for a given KPI visualization. ---- + --- -[discrete] -==== Personalized Views TML portability — General Availability [.version-badge.new]#New# + [discrete] + ==== Personalized Views TML portability — General Availability [.version-badge.new]#New# -The Personalized Views TML portability feature introduced in Early Access in 26.8.0.cl is now generally available. The `author` and `obj_id` fields are fully supported in exported and imported Personalized View TML. Smart merge import logic is applied by default. For more information, see xref:tml.adoc#personalized-views-portability[Personalized Views portability]. + The Personalized Views TML portability feature introduced in Early Access in 26.8.0.cl is now generally available. The `author` and `obj_id` fields are fully supported in exported and imported Personalized View TML. Smart merge import logic is applied by default. For more information, see xref:tml.adoc#personalized-views-portability[Personalized Views portability]. ---- + --- -[discrete] -==== Visual Embed SDK -The Visual Embed SDK version 1.52.0 introduces `overrideHistoryState` for browser history management in `AppEmbed` and `HomeLeftNavItem.Collections` for embedded left navigation. For more information, see the xref:api-changelog.adoc[Visual Embed SDK changelog]. + [discrete] + ==== Visual Embed SDK + The Visual Embed SDK version 1.52.0 introduces `overrideHistoryState` for browser history management in `AppEmbed` and `HomeLeftNavItem.Collections` for embedded left navigation. For more information, see the xref:api-changelog.adoc[Visual Embed SDK changelog]. ---- + --- -[discrete] -==== REST API v2 -For information about REST API v2 enhancements in this release, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. + [discrete] + ==== REST API v2 + For information about REST API v2 enhancements in this release, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. ---- + --- -|=== + |=== -== August 2026 + == August 2026 **Release version**: ThoughtSpot Cloud 26.8.0.cl + *Upgrade notes*: ⚠️ Includes breaking changes and deprecations. Refer to feature details in this page and xref:deprecated-features.adoc[Deprecation announcements]. + @@ -246,38 +246,78 @@ a| a| [discrete] ==== SpotterViz for Liveboards [earlyAccess eaBackground]#Early Access# -You can now use SpotterViz in your embedding application to help your users build and edit Liveboard visualizations using natural language. SpotterViz replaces the search bar-based experience on Liveboards, enabling users to make changes to their Liveboards through a conversation-style interface. For more information, see xref:spotterviz-liveboards.adoc[SpotterViz for Liveboards]. +You can now use SpotterViz in your embedding application to help your users build and edit Liveboards through a conversational interface. Instead of manually configuring charts and layouts, your users can describe what they want and SpotterViz generates the Liveboard for them, including the new tabs, chart types, data filters, and scheduled deliveries. + +For SpotterViz customization in embedded view, the Visual Embed SDK also provides several options to customize the SpotterViz panel experience. For more information, see xref:embed-spotterViz.adoc[SpotterViz in embedded Liveboards]. + +--- + +[discrete] +==== Spotter embedding + +Spotter file upload in embedded apps:: +Applications embedding the Spotter interface can now allow their users to xref:embed-spotter.adoc#_enable_file_upload_in_spotter_chat[upload files directly in the Spotter chat panel]. + +Spotter conversation history:: +You can now save your Spotter conversation and manage chat history using Spotter AI REST APIs. For more information, see xref:spotter-agent-conversation-mgmt-apis.adoc[APIs for managing saved conversations]. + +Spotter Agent instructions:: +You can configure and retrieve behavioral instructions for the Spotter agent using REST APIs. For more information, see xref:spotter-agent-instructions.adoc[Spotter AI agent instructions APIs]. --- [discrete] -==== Spotter V3 embedding -Starting from 26.7.0.cl, Spotter V3 is generally available for embedded instances. Spotter V3 introduces the following features and enhancements: +==== Focused home page experience [earlyAccess eaBackground]#Early Access# -* The new xref:embed-spotter.adoc[SpotterEmbed] component replaces the legacy `SearchBarEmbed` component for embedding Spotter experiences. -* SpotterEmbed supports the xref:embed-spotter.adoc#spotterViz[SpotterViz] experience. -* SpotterEmbed supports xref:embed-spotter.adoc#runtime-filters[runtime filters] and xref:embed-spotter.adoc#runtime-filter-operations[runtime filter operations]. -* xref:embed-spotter.adoc#hidden-actions[Action customization] support is extended to SpotterEmbed. +In full application embedding with the V3 navigation and home page experience, ThoughtSpot provides an additional option to switch to the V4 focused home page experience. The focused home page experience provides a streamlined, contemporary experience along with the Spotter panel. For more information, see xref:full-app-customize.adoc[Customize full application embedding]. -For more information, see xref:embed-spotter.adoc[Spotter embedding]. +--- + +[discrete] +==== SpotterCode authentication and workflow execution [.version-badge.breaking]#Breaking# +SpotterCode now supports authenticated sessions with your ThoughtSpot instance. When connecting your MCP client to the SpotterCode endpoint, you are now prompted to log in using your organization's identity provider. After authentication, SpotterCode can make ThoughtSpot API calls on your behalf. + +For more information, see the documentation on xref:spottercode.adoc#_mcp_server_endpoints[SpotterCode MCP Server] and xref:spottercode-integration.adoc#_authenticate_spottercode[Authenticating SpotterCode]. --- [discrete] -==== SpotterCode breaking change [.version-badge.breaking]#Breaking change# -Starting from 26.7.0.cl, the SpotterCode AI assistant on the developer documentation site now uses the `thoughtspot.ai` domain and the Spotter V3 authentication model. If you have a Content Security Policy (CSP) configuration on your browser that restricts connections to external domains, add `thoughtspot.ai` to the `connect-src` list to maintain access. For more information, see xref:spottercode.adoc[SpotterCode documentation]. +==== SpotterCode Agent in Visual Embed Playground [earlyAccess eaBackground]#Early Access# + +The Visual Embed SDK Playground now includes SpotterCode Agent, an AI-powered coding assistant. The SpotterCode panel displays pre-built prompts relevant to the component you are embedding, provides a prompt interface for user queries, and generates embed code. It generates boilerplate code automatically and accelerates building code and iterating embed configurations. + +For more information, see xref:developer-playground.adoc#spottercode-panel[Using SpotterCode in the Playground]. + +--- + +[discrete] +==== Webhooks enhancements + +ThoughtSpot introduces the following features and enhancements for webhook configuration and management: + +* New Webhooks page in the UI [earlyAccess eaBackground]#Early Access# + +The *Develop* page now includes a xref:webhooks-ux.adoc[dedicated *Webhooks* page] for creating, managing, and monitoring webhooks within the Org context. +* Storage configuration retrieval + +The `GET /api/rest/2.0/webhooks/storage-config` REST API endpoint to xref:webhooks-api.adoc#_retrieving_storage_information_for_webhook_configuration[get storage configuration details]. +* GCS storage configuration for webhook delivery + +Administrators can now xref:webhooks-gcs-storage.adoc[configure Google Cloud Storage (GCS) buckets as a storage destination] for webhook payload delivery on GCP-hosted ThoughtSpot clusters. +* Webhook activation and deactivation + +You can enable or disable a webhook connection in the UI or through REST API. +* Selective configuration reset + +The xref:webhooks-api.adoc#_updating_a_webhook[webhook update API endpoint] supports the `reset_options` parameter to remove specific optional configuration sections without replacing the full webhook configuration. --- + [discrete] -==== Search data REST API — saved formula support -The `POST /api/rest/2.0/searchdata` API now supports referencing saved formulas by name in the `query_string` parameter using bracket syntax (for example, `[Total Revenue] by [Region]` where `Total Revenue` is a saved formula). For more information, see xref:search-data-api.adoc[Search data API]. +==== Org isolation for per-org SAML and OIDC authentication +ThoughtSpot now enforces strict org isolation when users authenticate through a per-org identity provider (IdP). When a per-org IdP sends SAML or OIDC group claims that reference Orgs outside its authorized scope, ThoughtSpot silently drops those claims and records them as security audit events. This prevents a rogue IdP administrator in one Org from using group assertions to gain unauthorized access to another Org. Manually-assigned existing Org memberships are unaffected. For more information, see xref:orgs.adoc#per-org-sso-isolation[SSO and Org isolation]. --- [discrete] ==== Visual Embed SDK -The Visual Embed SDK version 1.50.0 includes new features and enhancements. For more information, see the xref:api-changelog.adoc[Visual Embed SDK changelog]. +The Visual Embed SDK version 1.50.0 includes several new features and enhancements. For more information, see the xref:api-changelog.adoc[Visual Embed changelog]. --- @@ -292,7 +332,7 @@ For information about REST API v2 enhancements in this release, see the xref:res == June 2026 **Release version**: ThoughtSpot Cloud 26.6.0.cl + -*Upgrade notes*: No breaking changes in this release. + +*Upgrade notes*: No breaking changes. + *Recommended SDK versions*: Visual Embed SDK v1.49.0 and later [.cl-table, cols="2,4", frame=none, grid=none] @@ -303,37 +343,70 @@ a| a| [discrete] -==== Spotter 3 General Availability -Spotter 3 is now generally available for all ThoughtSpot Cloud instances. For more information, see xref:embed-spotter.adoc[Spotter embedding]. +==== Chart and table overrides [.version-badge.new]#New# +You can now apply visualization overrides to charts and tables generated from a search query in ThoughtSpot search and full application embedding. The `visualOverrides` property in `SearchViewConfig` and `AppViewConfig` allows developers to apply at the embed initialization time: + +* Chart overrides + +Control legend visibility and position, data label display and per-column filter +thresholds, regression lines, grid lines, axis range and label settings, series +colors, and conditional formatting rules including font and background styling. +* Table overrides + +Control column visibility, text wrapping, row height and padding density, table +theme, and column summary visibility with per-column exceptions. + +For more information, see xref:viz-overrides.adoc[Configuring visualization overrides]. --- [discrete] -==== CSV file upload in Spotter [earlyAccess eaBackground]#Early Access# -Spotter now supports CSV file uploads. Users can upload a CSV file and ask Spotter questions about the data in the file. For more information, see xref:customize-spotter-embed.adoc#_csv_file_upload[Enable CSV file upload]. +==== Spotter AI and embedding enhancements [.version-badge.new]#New# + +This release introduces the following enhancements for Spotter AI workflows and embedded Spotter applications. + +* Spotter embedding: + +Spotter now includes data literacy skills that help users understand the underlying data model. Users can ask Spotter to explain available data sources, fields, and relationships in plain language within a conversation session. +* Spotter AI APIs: + +//** New REST API endpoints to configure and retrieve persistent behavioral xref:spotter-agent-instructions.adoc[instructions for the Spotter agent]. + New API endpoint xref:spotter-agent-apis.adoc#_stop_an_in_progress_agent_response[stop and cancel a long-running Spotter response]. --- [discrete] -==== Visual Embed SDK -The Visual Embed SDK version 1.49.0 includes new features and enhancements. For more information, see the xref:api-changelog.adoc[Visual Embed SDK changelog]. +==== Developer page enhancements +The **Develop** page in the ThoughtSpot UI has been updated with the following enhancements: + +* The **Custom actions** list page now shows the code-based custom actions configured using the Visual Embed SDK. +* Removal of REST API v1 + +The legacy REST Playground v1 has been removed from the left navigation. This change does not affect your current integrations with v1 REST API. ThoughtSpot recommends that you update your integration workflows to use REST API v2. For more information, see xref:rest-api-v1v2-comparison.adoc[REST API v1 to v2 migration]. +* Removal of GraphQL playgrounds + +The menu link to the GraphQL playground has been removed from the UI. + +[discrete] +==== Liveboard browser cache refresh +To improve load performance and reduce reload times, you can now enable the Liveboard cache option with a **Refresh** button that lets your users clear the cache and refresh visualization data when required. For more information, see xref:api-changelog.adoc#_liveboard_browser_cache_refresh[Liveboard browser cache refresh]. --- [discrete] -==== REST API v2 -For information about REST API v2 enhancements in this release, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. +==== Visual Embed SDK +The Visual Embed SDK version 1.49.0 includes several new features and enhancements. For more information, see the xref:api-changelog.adoc[Visual Embed changelog]. --- +[discrete] +==== REST API v2 +This release introduces new API endpoints for Spotter, connections and trusted authentication. For information about REST API v2 enhancements, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. + |=== + == May 2026 **Release version**: ThoughtSpot Cloud 26.5.0.cl + -*Upgrade notes*: No breaking changes in this release. + +*Upgrade notes*: ⚠️ Includes breaking changes to Spotter APIs. Refer to the xref:rest-apiv2-changelog.adoc[REST API changelog] for more information. + *Recommended SDK versions*: Visual Embed SDK v1.48.0 and later + [.cl-table, cols="2,4", frame=none, grid=none] |=== a| @@ -341,86 +414,302 @@ a| *Version 26.5.0.cl* a| + + [discrete] -==== Spotter 3 Early Access [earlyAccess eaBackground]#Early Access# -Spotter 3 is available in Early Access for embedded instances. For more information, see xref:embed-spotter.adoc[Spotter embedding]. +==== Liveboard downloads + +Continuous Liveboard PDF export [beta betaBackground]^Beta^:: +In PDF downloads, Liveboard tabs can now be rendered in a single page matching the UI layout. This feature can be enabled by setting `isContinuousLiveboardPDFEnabled` to `true` in the SDK. Setting this flag to `false` returns to the paginated PDF view. + +Liveboard download in XLSX and CSV formats:: +Embedded Liveboards can now be downloaded in the PDF, XLSX and CSV file formats. To enable this feature, ensure that the `isLiveboardXLSXCSVDownloadEnabled` parameter is set to `true`. + +Excel exports for pivot tables:: +Pivot table visualizations can now be exported to Excel format. + +For more information, see xref:embed-pinboard.adoc#_liveboard_download_options[Liveboard download options]. --- [discrete] -==== Visual Embed SDK -The Visual Embed SDK version 1.48.0 includes new features and enhancements. For more information, see the xref:api-changelog.adoc[Visual Embed SDK changelog]. +==== Visualization edit interface within the Liveboard view + +Users can now edit the underlying query of an answer directly within the Liveboard. When this feature is enabled, the edit button for visualization appears in the answer's floating toolbar when the Liveboard is opened in the edit mode. Clicking the edit button opens the Answer interface preloaded with the answer's current query context. You can make the edits and save the changes without leaving the Liveboard. --- [discrete] -==== REST API v2 -For information about REST API v2 enhancements in this release, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. +==== KPI charts in embedded Liveboards + +Embedded Liveboards support advanced controls KPI chart customization. For more information, see link:https://docs.thoughtspot.com/cloud/latest/chart-kpi#advanced[KPI charts]. + +--- + +[discrete] +==== Per-org and per-user timezone control via variables [beta betaBackground]^Beta^ + +You can centrally control timezone behavior per org and per user in embedded deployments using the new template variable `ts_user_timezone` and Variable APIs. + +For multi-org and multi-tenant environments, each tenant org and user can be configured independently, guaranteeing isolation and consistency of time-based analytics across regions. Administrators can reference the timezone variable in formulas to render and filter timestamp data correctly for each embedded user, without separate content per region. + +--- + +[discrete] +==== Timezone-aware keyword filtering [beta betaBackground]^Beta^ +ThoughtSpot now supports resolving relative date and time keywords, such as `today`, `yesterday`, and `last 7 days`, using a configurable per-user or per-Org timezone, instead of the system default timezone on a ThoughtSpot instance. This feature eliminates timezone-based inconsistencies in multi-region embedded deployments and removes the need for custom workarounds. + +For more information, see xref:timezone.adoc[Timezone-aware keywords and filters]. + +[NOTE] +==== +The timezone awareness feature is in Beta and disabled by default. To enable this feature, contact ThoughtSpot Support. +==== + --- +[discrete] +==== Visual Embed SDK +The Visual Embed SDK version 1.48.0 includes several new features and enhancements. For more information, see the xref:api-changelog.adoc[Visual Embed changelog]. + +--- + +[discrete] +==== REST API v2 +This release introduces new Spotter API endpoints and modifications to the agent conversation APIs, and deprecates legacy agent endpoints. For information about REST API v2 enhancements, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. + |=== + == April 2026 **Release version**: ThoughtSpot Cloud 26.4.0.cl + -*Upgrade notes*: No breaking changes in this release. + +*Upgrade notes*: ⚠️ Variable update and delete API and metadata parameterization endpoints are deprecated and replaced with new API endpoints. Refer to xref:rest-apiv2-changelog.adoc#version_26_4_0_cl_april_2026[REST API changelog] and xref:deprecated-features.adoc[Deprecation announcements]. + *Recommended SDK versions*: Visual Embed SDK v1.47.0 and later [.cl-table, cols="2,4", frame=none, grid=none] |=== + a| [.cl-label] *Version 26.4.0.cl* a| + [discrete] -==== Visual Embed SDK -The Visual Embed SDK version 1.47.0 includes new features and enhancements. For more information, see the xref:api-changelog.adoc[Visual Embed SDK changelog]. +==== Theme builder in AI mode + +The Theme Builder now has an AI mode that enables developers to explore and preview style customizations for their embedded application's branding using natural language instructions and uploaded brand assets. You can execute style updates such as applying colors directly from a PDF branding guide, updating all button shapes with higher contrast, matching a header to a dark background based on a screenshot, or importing typography and spacing from a JSON file. In the AI mode, Theme builder interprets your intent and applies the changes instantly. + +For more information, see xref:theme-builder.adoc[Theme builder]. --- + [discrete] -==== REST API v2 -For information about REST API v2 enhancements in this release, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. +==== Webhook integration +In this release version, the following enhancements are introduced in the webhook configuration and delivery status monitoring workflows: + +Channel validation:: +Administrators can verify the connection status of a webhook channel by sending a test payload in a `POST` request to the `/api/rest/2.0/system/communication-channels/validate` REST API endpoint. For more information, see xref:webhooks-comm-channel.adoc#_validate_communication_channel_configuration[Webhook channel validation]. + +Monitor webhook delivery:: +Administrators can also monitor the status of a webhook delivery via a `POST /api/rest/2.0/jobs/history/communication-channels/search` API request. For more information, see xref:webhooks-comm-channel.adoc#_monitor_webhook_delivery_and_job_status[Monitor webhook delivery and job status]. + +Support for custom HTTP headers in webhook requests:: +When configuring or updating a webhook, you can now specify custom headers to include in every outbound request, in addition to the standard HTTP and authentication headers that ThoughtSpot sends. For more information, refer to the xref:webhooks-lb-schedule.adoc#_create_a_webhook[webhook documentation]. + +--- + + +[discrete] +==== Spotter embed enhancements +You can now customize the appearance and contents of the chat history sidebar panel in Spotter embedding. + +You can also customize the branding and logo in the Spotter chat interface. + +For more information, see xref:embed-spotter.adoc#_chat_history_panel[Customizing chat history sidebar] and xref:embed-spotter.adoc#_hiding_the_spotter_icon_and_thoughtspot_branding_chat_interface[Hiding logo and brand label in Spotter chat interface]. + +--- + +[discrete] +==== Liveboard enhancements +The following enhancements are introduced in Liveboard export and filtering workflows. + +Embedding a personalized Liveboard view:: +You can now embed a saved personalized Liveboard view using the `personalizedViewId` and load it along with the `liveboardId` in your app. + +Centralized filter modal:: +Liveboard users can modify multiple filters and parameters in a single session using the centralized filter modal. This is an early access feature and disabled by default on ThoughtSpot embedded instances. To enable this feature on embedded Liveboards, set the `isCentralizedLiveboardFilterUXEnabled` to `true`. + +Current period inclusion in rolling date filters:: +The rolling date filters with the **Last ** and **Next ** filter types support including current period. Developers can disable, show, or hide this option using `isThisPeriodInDateFiltersEnabled` or `Action.IncludeCurrentPeriod`. + +Liveboard PNG export:: +The PNG export workflow in the `/api/rest/2.0/report/liveboard` REST API is enhanced to provide high-resolution PNG files. The legacy PNG workflow is deprecated in 26.4.0.cl. For more information about breaking changes and deprecation guidelines, see xref:deprecated-features.adoc[Deprecation announcements]. For information about the new PNG download workflow, see xref:data-report-v2-api.adoc#_liveboard_report_api[Liveboard report API documentation]. + +--- + + +[discrete] +==== Full app embedding +In full application embedded deployments with the V3 navigation and home page experience, the default list page experience is set to ListPage v3 experience. + +The ListPage V3 experience provides a refreshed list layout and styling, including the following enhancements: + +* The **Views** column to show the number of views for each object. +* Sorting options for **Name**, **Author**, and **Views** columns. +* Filters can be added by clicking the column header without opening the filter modal. This option is available for **Favorites**, **Views** columns, and **Verified** columns. + +For more information, see xref:full-app-customize.adoc#_customize_list_page_experience[List page customization]. + +--- + +[discrete] +==== Variable API +The variable REST API provides new API endpoints for the following bulk operations: + +* Bulk deletion: +You can now delete multiple variables in a single API request using the `/api/rest/2.0/template/variables/delete` endpoint. +* Batch update of variable values: +You can now assign and update multiple values to a variable in a single API request using the `/api/rest/2.0/template/variables/{identifier}/update-values` endpoint. + +[NOTE] +==== +The `/api/rest/2.0/template/variables/update-values` and `/api/rest/2.0/template/variables/{identifier}/delete` endpoints are now deprecated. Use the new `/api/rest/2.0/template/variables/{identifier}/update-values` and `/api/rest/2.0/template/variables/delete` endpoints for the variable update and delete operations instead. +==== + +For more information, see xref:variables.adoc[Variables documentation]. + +--- + + +[discrete] +==== Metadata parameterization +You can now parameterize multiple properties of metadata objects using `POST /api/rest/2.0/metadata/parameterize-fields`. The legacy endpoint `/api/rest/2.0/metadata/parameterize` is deprecated in 26.4.0.cl and later versions, and is replaced with the new endpoint to allow updating multiple fields in a single API request. + +For more information, see xref:metadata-parameterization.adoc[Metadata parameterization documentation]. + +--- + + +[discrete] +==== Collections [beta betaBackground]^Beta^ +ThoughtSpot embedded users can now use REST APIs v2 to organize different ThoughtSpot objects into organizational containers called *Collections*. These objects can be Liveboards, Answers, data models, tables, and even other Collections. + +For more information, see xref:collections.adoc[Collections]. + +[NOTE] +==== +These APIs are currently in beta and turned off by default on ThoughtSpot instances. To enable this feature on your instance, contact ThoughtSpot Support. +==== --- +[discrete] +==== Visual Embed SDK +For information about the new features and enhancements introduced in Visual Embed SDK version 1.46.0, see the xref:api-changelog.adoc[Visual Embed changelog]. + + +[discrete] +==== REST API v2 +For information about REST API v2 enhancements, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. + +--- |=== == March 2026 **Release version**: ThoughtSpot Cloud 26.3.0.cl + -*Upgrade notes*: No breaking changes in this release. + +*Upgrade notes*: ⚠️ Includes feature deprecations. Refer to xref:rest-apiv2-changelog.adoc#_custom_access_token_api[REST API changelog] and xref:deprecated-features.adoc[Deprecation announcements]. + *Recommended SDK versions*: Visual Embed SDK v1.46.0 and later [.cl-table, cols="2,4", frame=none, grid=none] |=== + a| [.cl-label] *Version 26.3.0.cl* a| +[discrete] +==== Amazon S3 storage destination for webhook delivery +You can now configure ThoughtSpot to deliver webhook payloads and attachments directly into your own Amazon S3 storage using secure AWS cross-account access. To enable this integration, your AWS administrator must create an IAM role with S3 permissions and trust policy, and then register a webhook in ThoughtSpot to deliver the payloads and attachments directly to your S3 bucket. + +For more information, see xref:webhooks-s3-storage.adoc[Amazon S3 storage integration for webhook delivery]. + +--- + +[discrete] +==== Host event enhancements for context-aware routing + +HostEvents in the Visual Embed SDK are enhanced to improve event routing and context targeting in ThoughtSpot embedded applications. + +Developers can use the page context framework in the SDK to route host events to a specific UI layer and align user experience with the product UI behavior in multi-modal contexts. + +For more information, see xref:events-context-aware-routing.adoc[Context-based execution of host events]. + +--- + +[discrete] +==== JWT-based ABAC implementation +The legacy JWT-based approach that uses `filter_rules` and `parameter_values` to implement Attribute-Based Access Control (ABAC) is deprecated. + +As part of this deprecation, the following changes have been introduced to the custom authentication token API workflow and REST API Playground: + +* The `filter_rules` parameter on the custom token authentication page in the REST API Playground is no longer available for new configurations. This change does not affect your existing implementation. + +* The `parameter_values` property is not deprecated in version 26.3.0.cl and remains supported until further notice. However, using parameter values for row-level security use cases will ultimately be deprecated in an upcoming release. + +Existing ABAC implementations that use `filter_rules` will continue to function until further notice. However, we strongly recommend migrating your legacy ABAC implementation to the ABAC via RLS method that uses custom variables. For migration steps, refer to the xref:abac-migration-guide.adoc[ABAC migration guide]. + +For new deployments, use ABAC via RLS with custom variables and pass data security attributes through the `variable_values` property in the custom access token, and define your RLS rules based on those variables. For more information, see xref:abac_rls-variables.adoc[ABAC via RLS]. + +--- + +[discrete] +==== Spotter coaching access across published Orgs +Starting with the 26.3.0.cl release, ThoughtSpot supports publishing Spotter coaching information to other Orgs. Coaching changes from the primary Org are synchronized with the data models published in secondary Orgs. + +Administrators and users with edit access to data models can programmatically control user access to Spotter coaching information using the object privilege REST API endpoint, `/api/rest/2.0/security/metadata/manage-object-privilege`. They can assign `SPOTTER_COACHING_PRIVILEGE` to other users and user groups, allowing access to the coaching information without requiring data model editing or administration privileges. + +Users and groups with `SPOTTER_COACHING_PRIVILEGE` can import and export coaching TML on data models in the source and destination Orgs where the model is published, and can also share these objects with other users and groups. + +For more information, see xref:spotter-nl-instructions.adoc#_spotter_data_model_instructions_access[Spotter data model instructions access]. + +--- + +[discrete] +==== Full application embedding +The height and aspect ratio of the logo in the top-left corner of the ThoughtSpot application interface have been updated for visual alignment and consistency across pages. This enhancement is available only in the V3 navigation and home page experience. + +If you have embedded the full application with the V3 navigation experience, you may notice that the logo appears smaller in the top navigation. This is a design update and does not require any configuration changes to your current embedding implementation. However, we recommend that you review the logo size and appearance, and adjust your custom logo if necessary. + +For information about adding a custom logo image, see xref:customize-style.adoc#logo-change[Customize application logo and favicon]. + +--- + [discrete] ==== Visual Embed SDK -The Visual Embed SDK version 1.46.0 includes new features and enhancements. For more information, see the xref:api-changelog.adoc[Visual Embed SDK changelog]. +For information about the new features and enhancements introduced in Visual Embed SDK version 1.46.0, see the xref:api-changelog.adoc[Visual Embed changelog]. --- [discrete] ==== REST API v2 -For information about REST API v2 enhancements in this release, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. +For information about REST API v2 enhancements, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. --- |=== == February 2026 - **Release version**: ThoughtSpot Cloud 26.2.0.cl + -*Upgrade notes*: No breaking changes in this release. + +*Upgrade notes*: ⚠️ Includes API parameter deprecations. Refer to xref:rest-apiv2-changelog.adoc[REST API changelog] and xref:deprecated-features.adoc[Deprecation announcements]. + *Recommended SDK versions*: Visual Embed SDK v1.45.0 and later + [.cl-table, cols="2,4", frame=none, grid=none] |=== a| @@ -428,33 +717,146 @@ a| *Version 26.2.0.cl* a| +[discrete] +==== SpotterCode extension for IDEs [earlyAccess eaBackground]#Early Access# + +ThoughtSpot introduces SpotterCode, an AI-powered Model Context Protocol (MCP) extension for Integrated Development Environments (IDEs) such as Cursor, Visual Studio Code, and Claude Code. When integrated, SpotterCode enables the AI agent in the IDE to access ThoughtSpot SDKs and API documentation resources and provide in-context coding assistance to developers embedding ThoughtSpot content within their applications. + +SpotterCode is available as an Early Access feature and can be integrated with development environments that support MCP servers and tools. For more information, see xref:spottercode.adoc[SpotterCode], xref:spottercode-integration.adoc[Integrating SpotterCode in IDEs], and xref:spottercode-prompt-guide.adoc[SpotterCode prompting guide]. + +--- + +[discrete] +==== Spotter 3 experience [earlyAccess eaBackground]#Early Access# +You can now embed the Spotter 3 experience, which introduces several new capabilities, agentic analytics, and an enhanced user experience. Spotter 3 is an Early Access feature and is disabled by default on ThoughtSpot embedded instances. + +For more information, see xref:embed-ai-analytics.adoc[Embed AI Search and Analytics] and xref:embed-spotter.adoc[Spotter embedding documentation]. + +--- + +[discrete] +==== Rate limits for REST APIs +To prevent excessive requests from reaching application servers and ensure API stability and service quality for REST API users, ThoughtSpot enforces rate limits on public API requests per client IP. These limits are applied globally at the cluster level for all public API requests, including calls to both REST API v1 and v2 endpoints. +//Administrators can adjust these limits for their ThoughtSpot deployments as needed. + +For more information, see xref:about-rest-apis.adoc#_rate_limits_for_api_requests[Rate limits for REST APIs]. + +--- + +[discrete] +==== Security settings via REST APIs +Security settings that ensure data security and a seamless embedded user experience can now be configured through REST APIs v2. Administrators and developers can configure allowlists for: + +* Content Security Policy (CSP) +* Cross-origin Resource Sharing (CORS) +* Authentication attributes +* Access control settings + +For more information, see xref:security-settings.adoc[Security Settings]. + +--- + +[discrete] +==== WebSocket support for external tools +ThoughtSpot supports secure WebSocket (`wss://`) endpoints for external tool script integrations, for example, tools that open WebSocket connections from the browser. + +To allow a WebSocket host, add the corresponding `wss://` URL to both your CSP allowlists. Only hosts explicitly listed with the `wss://` protocol are permitted. Existing `https://` entries in the allowlists remain unchanged and continue to function as expected. + +For more information, see xref:3rd-party-script.adoc#_allow_websocket_endpoints[External tools and script integration]. + +--- + + [discrete] ==== Visual Embed SDK -The Visual Embed SDK version 1.45.0 includes new features and enhancements. For more information, see the xref:api-changelog.adoc[Visual Embed SDK changelog]. +For information about the new features and enhancements introduced in Visual Embed SDK version 1.45.0, see the xref:api-changelog.adoc[Visual Embed changelog]. --- [discrete] ==== REST API v2 -For information about REST API v2 enhancements in this release, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. +For information about REST API v2 enhancements, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. --- - |=== + == January 2026 -**Release version**: ThoughtSpot Cloud 26.1.0.cl + -*Upgrade notes*: No breaking changes in this release. + +**Release version**: ThoughtSpot Cloud 10.15.0.cl + +*Upgrade notes*: No breaking changes. + *Recommended SDK versions*: Visual Embed SDK v1.44.0 and later + [.cl-table, cols="2,4", frame=none, grid=none] |=== a| [.cl-label] -*Version 26.1.0.cl* +*Version 10.15.0.cl* a| +[discrete] +==== Theme Builder +Theme Builder is now generally available (GA) and will be rolled out to all ThoughtSpot instances in customer deployments over the next few weeks. + +When this feature is enabled on your instance, you can access it from the *Develop* page in ThoughtSpot and use it to customize styles and UX themes directly within the product. + +For more information, see xref:theme-builder.adoc[Theme Builder]. + +--- + +[discrete] +==== V3 navigation and home page experience + +The new V3 navigation and home page experience is now generally available (GA) and can be enabled on ThoughtSpot embedded instances. + +The default UI experience in full application embedding remains the classic (V1) experience until further notice. Developers embedding the full ThoughtSpot application can enable the V3 experience in their applications by setting the appropriate configuration options in their embed code. + +For more information, see xref:full-app-customize.adoc[Customizing full application embedding]. + +--- + +[discrete] +==== Formula variables in RLS rules + +You can now create formula variables using the Variable REST API and use these variables in RLS rules for a specific data context and in ABAC token requests to dynamically assign security attributes to users. + +For more information, see xref:abac_rls-variables.adoc[ABAC via RLS with variables]. + +--- + +[discrete] +==== Spotter APIs + +ThoughtSpot introduces new REST APIs for the following Spotter workflows: + +* To send queries to a conversation session with the Spotter agent +* To set natural language (NL) instructions on a model to coach the Spotter system +* To fetch NL instructions configured on a model + +For more information, see xref:spotter-apis.adoc[Spotter APIs]. + +--- + +[discrete] +==== Embed events and parameters to intercept API calls +You can now intercept API calls from the embedded ThoughtSpot application using the `interceptUrls` attribute in the Visual Embed SDK. This feature lets you control API requests in your embedding application and use embed events to modify, block, or handle requests before they are sent to the backend. For more information, see xref:api-intercept.adoc[Intercept API calls and search requests]. + +--- + +[discrete] +==== Icon customization enhancements + +You can now replace or customize the chart switcher toggle and icons in the Charts drawer on an Answer or visualization page using SVG sprites. Previously, these icons were fixed to ThoughtSpot defaults and were not configurable. In the new version, these icons are available as SVG components and can be replaced by developers through the xref:customize-icons.adoc[icon customization framework] as needed. + +--- + +[discrete] +==== Mobile Embed SDK +The SDKs for embedding ThoughtSpot components in mobile apps are now Generally Available (GA). For more information about the SDKs and how to embed a ThoughtSpot component in a mobile app, see xref:mobile-embed.adoc[Mobile embed documentation]. + +--- + [discrete] ==== Visual Embed SDK For information about the new features and enhancements introduced in Visual Embed SDK version 1.44.0, see xref:api-changelog.adoc[Visual Embed changelog]. From 6db40941d616eec6e8ed443aee0b078bf39df0b6 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 17 Aug 2026 10:53:51 +0530 Subject: [PATCH 28/32] docs: add What's New blurb for 26.9.0.cl / aug.26.mt / SDK 1.52.0 New September 2026 section inserted above August 2026. All existing content preserved. Covers: overrideHistoryState (SCAL-317516), HomeLeftNavItem.Collections (SCAL-314461), Answer Export API GA (SCAL-306069), Snowflake Semantic View APIs (SCAL-309867), Spotter Memory GA (SCAL-306173), conversation sharing APIs, KPI isSparklineEnabled (SCAL-320899), Personalized Views TML portability GA (SCAL-307284) From 4ec9f6d8ddb26cc3a9218b873e2772defcce9f05 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 17 Aug 2026 10:54:16 +0530 Subject: [PATCH 29/32] docs: fix indentation in September 2026 What's New section --- modules/ROOT/pages/whats-new.adoc | 132 +++++++++++++++--------------- 1 file changed, 66 insertions(+), 66 deletions(-) diff --git a/modules/ROOT/pages/whats-new.adoc b/modules/ROOT/pages/whats-new.adoc index 73c23be30..1688c82dc 100644 --- a/modules/ROOT/pages/whats-new.adoc +++ b/modules/ROOT/pages/whats-new.adoc @@ -24,109 +24,109 @@ This page lists new features, enhancements, and deprecated functionality introdu // ============================================================ == September 2026 - **Release version**: ThoughtSpot Cloud 26.9.0.cl + - *Upgrade notes*: No breaking changes in this release. + - *Recommended SDK versions*: Visual Embed SDK v1.52.0 and later +**Release version**: ThoughtSpot Cloud 26.9.0.cl + +*Upgrade notes*: No breaking changes in this release. + +*Recommended SDK versions*: Visual Embed SDK v1.52.0 and later - [.cl-table, cols="2,4", frame=none, grid=none] - |=== - a| - [.cl-label] - *Version 26.9.0.cl* +[.cl-table, cols="2,4", frame=none, grid=none] +|=== +a| +[.cl-label] +*Version 26.9.0.cl* - a| - [discrete] - ==== Browser history management in full application embedding [.version-badge.new]#New# +a| +[discrete] +==== Browser history management in full application embedding [.version-badge.new]#New# - The Visual Embed SDK 1.52.0 introduces the `overrideHistoryState` configuration parameter for `AppEmbed`. When ThoughtSpot is embedded in a host application, every internal navigation event pushes a new entry onto the browser history stack, causing the browser *Back* button to step through ThoughtSpot's internal pages before returning to the host application. Setting `overrideHistoryState: true` converts ThoughtSpot's internal `pushState` calls to `replaceState`, preventing internal navigation from polluting the host application's browser history stack. For more information, see xref:full-app-embed.adoc[Full application embedding]. +The Visual Embed SDK 1.52.0 introduces the `overrideHistoryState` configuration parameter for `AppEmbed`. When ThoughtSpot is embedded in a host application, every internal navigation event pushes a new entry onto the browser history stack, causing the browser *Back* button to step through ThoughtSpot's internal pages before returning to the host application. Setting `overrideHistoryState: true` converts ThoughtSpot's internal `pushState` calls to `replaceState`, preventing internal navigation from polluting the host application's browser history stack. For more information, see xref:full-app-embed.adoc[Full application embedding]. - --- +--- - [discrete] - ==== Collections in embedded left navigation panel [.version-badge.new]#New# +[discrete] +==== Collections in embedded left navigation panel [.version-badge.new]#New# - The `HomeLeftNavItem.Collections` value is now available in the Visual Embed SDK 1.52.0. Embed developers can include *Collections* as a navigation option in the left navigation panel for full application embeds, enabling end users to navigate to *Collections* directly from the embedded experience. For more information, see xref:full-app-customize.adoc[Customize the embedded ThoughtSpot experience]. +The `HomeLeftNavItem.Collections` value is now available in the Visual Embed SDK 1.52.0. Embed developers can include *Collections* as a navigation option in the left navigation panel for full application embeds, enabling end users to navigate to *Collections* directly from the embedded experience. For more information, see xref:full-app-customize.adoc[Customize the embedded ThoughtSpot experience]. - --- +--- - [discrete] - ==== Answer Export API — General Availability [.version-badge.new]#New# +[discrete] +==== Answer Export API — General Availability [.version-badge.new]#New# - The Answer Export API (`POST /api/rest/2.0/report/answer`) is now generally available. This release introduces the following enhancements: +The Answer Export API (`POST /api/rest/2.0/report/answer`) is now generally available. This release introduces the following enhancements: - * *Pinned Answer export*: Export a pinned visualization from a Liveboard directly using the `viz_guid` parameter. - * *Personalized View support*: Export data from a specific Personalized View using `personalised_view_identifier`. - * *Spotter Answer export*: Export Spotter-generated answers in `XLSX` and `PDF` formats in addition to `CSV` and `PNG`. - * *Custom PNG dimensions*: Control PNG export dimensions using `x_resolution` and `y_resolution` parameters (600-3840 px). - * *Scaling control*: Adjust chart element size in PNG exports using `scaling_factor` (80-400). +* *Pinned Answer export*: Export a pinned visualization from a Liveboard directly using the `viz_guid` parameter. +* *Personalized View support*: Export data from a specific Personalized View using `personalised_view_identifier`. +* *Spotter Answer export*: Export Spotter-generated answers in `XLSX` and `PDF` formats in addition to `CSV` and `PNG`. +* *Custom PNG dimensions*: Control PNG export dimensions using `x_resolution` and `y_resolution` parameters (600-3840 px). +* *Scaling control*: Adjust chart element size in PNG exports using `scaling_factor` (80-400). - For more information, see xref:data-report-v2-api.adoc#answer-report[Answer Report API]. +For more information, see xref:data-report-v2-api.adoc#answer-report[Answer Report API]. - --- +--- - [discrete] - ==== Snowflake Semantic View integration APIs [.version-badge.new]#New# +[discrete] +==== Snowflake Semantic View integration APIs [.version-badge.new]#New# - ThoughtSpot introduces four new REST API v2.0 endpoints to manage Snowflake Semantic View integrations programmatically without using the ThoughtSpot UI: +ThoughtSpot introduces four new REST API v2.0 endpoints to manage Snowflake Semantic View integrations programmatically without using the ThoughtSpot UI: - * `POST /api/rest/2.0/semantic-integrations/create` - * `POST /api/rest/2.0/semantic-integrations/search` - * `POST /api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/import` - * `POST /api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/delete` +* `POST /api/rest/2.0/semantic-integrations/create` +* `POST /api/rest/2.0/semantic-integrations/search` +* `POST /api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/import` +* `POST /api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/delete` - Requires `ADMINISTRATION` or `DATAMANAGEMENT` privilege. For more information, see xref:semantic-integrations-api.adoc[Snowflake Semantic View integration APIs]. +Requires `ADMINISTRATION` or `DATAMANAGEMENT` privilege. For more information, see xref:semantic-integrations-api.adoc[Snowflake Semantic View integration APIs]. - --- +--- - [discrete] - ==== Spotter Memory — General Availability [.version-badge.new]#New# +[discrete] +==== Spotter Memory — General Availability [.version-badge.new]#New# - The Spotter memory feature is now generally available. The memory APIs (`POST /api/rest/2.0/ai/memory/import` and `POST /api/rest/2.0/ai/memory/export`) are enabled by default on all ThoughtSpot Cloud instances. Administrators can manage and audit Spotter's training data programmatically. For more information, see xref:spotter-agent-apis.adoc[Spotter agent APIs]. +The Spotter memory feature is now generally available. The memory APIs (`POST /api/rest/2.0/ai/memory/import` and `POST /api/rest/2.0/ai/memory/export`) are enabled by default on all ThoughtSpot Cloud instances. Administrators can manage and audit Spotter's training data programmatically. For more information, see xref:spotter-agent-apis.adoc[Spotter agent APIs]. - --- +--- - [discrete] - ==== Spotter conversation sharing APIs [.version-badge.new]#New# +[discrete] +==== Spotter conversation sharing APIs [.version-badge.new]#New# - ThoughtSpot introduces three new REST API v2.0 endpoints to share Spotter agent conversations programmatically: +ThoughtSpot introduces three new REST API v2.0 endpoints to share Spotter agent conversations programmatically: - * `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` -- Share a conversation with users or groups with `READ_ONLY` access. - * `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content` -- Retrieve the shared messages and answers in a conversation. - * `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info` -- Retrieve the list of principals a conversation is shared with and their access levels. +* `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` -- Share a conversation with users or groups with `READ_ONLY` access. +* `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content` -- Retrieve the shared messages and answers in a conversation. +* `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info` -- Retrieve the list of principals a conversation is shared with and their access levels. - For more information, see xref:spotter-agent-apis.adoc#_sharing_spotter_conversations[Sharing Spotter conversations]. +For more information, see xref:spotter-agent-apis.adoc#_sharing_spotter_conversations[Sharing Spotter conversations]. - --- +--- - [discrete] - ==== KPI sparkline setting in metadata search response [.version-badge.new]#New# +[discrete] +==== KPI sparkline setting in metadata search response [.version-badge.new]#New# - The `POST /api/rest/2.0/metadata/search` response now includes the `isSparklineEnabled` field in the `AnswerSpecHeader` object for KPI chart type answers. This boolean field indicates whether the sparkline trend line is enabled for a given KPI visualization. +The `POST /api/rest/2.0/metadata/search` response now includes the `isSparklineEnabled` field in the `AnswerSpecHeader` object for KPI chart type answers. This boolean field indicates whether the sparkline trend line is enabled for a given KPI visualization. - --- +--- - [discrete] - ==== Personalized Views TML portability — General Availability [.version-badge.new]#New# +[discrete] +==== Personalized Views TML portability — General Availability [.version-badge.new]#New# - The Personalized Views TML portability feature introduced in Early Access in 26.8.0.cl is now generally available. The `author` and `obj_id` fields are fully supported in exported and imported Personalized View TML. Smart merge import logic is applied by default. For more information, see xref:tml.adoc#personalized-views-portability[Personalized Views portability]. +The Personalized Views TML portability feature introduced in Early Access in 26.8.0.cl is now generally available. The `author` and `obj_id` fields are fully supported in exported and imported Personalized View TML. Smart merge import logic is applied by default. For more information, see xref:tml.adoc#personalized-views-portability[Personalized Views portability]. - --- +--- - [discrete] - ==== Visual Embed SDK - The Visual Embed SDK version 1.52.0 introduces `overrideHistoryState` for browser history management in `AppEmbed` and `HomeLeftNavItem.Collections` for embedded left navigation. For more information, see the xref:api-changelog.adoc[Visual Embed SDK changelog]. +[discrete] +==== Visual Embed SDK +The Visual Embed SDK version 1.52.0 introduces `overrideHistoryState` for browser history management in `AppEmbed` and `HomeLeftNavItem.Collections` for embedded left navigation. For more information, see the xref:api-changelog.adoc[Visual Embed SDK changelog]. - --- +--- - [discrete] - ==== REST API v2 - For information about REST API v2 enhancements in this release, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. +[discrete] +==== REST API v2 +For information about REST API v2 enhancements in this release, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. - --- +--- - |=== +|=== - == August 2026 +== August 2026 **Release version**: ThoughtSpot Cloud 26.8.0.cl + *Upgrade notes*: ⚠️ Includes breaking changes and deprecations. Refer to feature details in this page and xref:deprecated-features.adoc[Deprecation announcements]. + From 18bb058de6404238c3059a5dadec44f0ffbacc8a Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 17 Aug 2026 10:54:18 +0530 Subject: [PATCH 30/32] docs: fix indentation in September 2026 What's New section From de530e85db2fe5bd3b0765dc98b35ec146979fc8 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Mon, 17 Aug 2026 10:55:11 +0530 Subject: [PATCH 31/32] formatting fixes --- modules/ROOT/pages/api-changelog.adoc | 126 +++++++++++++------------- 1 file changed, 64 insertions(+), 62 deletions(-) diff --git a/modules/ROOT/pages/api-changelog.adoc b/modules/ROOT/pages/api-changelog.adoc index afdb900bf..110feaf28 100644 --- a/modules/ROOT/pages/api-changelog.adoc +++ b/modules/ROOT/pages/api-changelog.adoc @@ -10,84 +10,86 @@ This page documents the changes introduced in each release of the Visual Embed S == Version 1.52.x, September 2026 - [width="100%" cols="1,4"] - |==== - |[tag greenBackground]#NEW FEATURE# a| - - [discrete] - ===== Browser history management in full application embedding - - // SOURCE: SCAL-317516 - // SOURCE: thoughtspot/visual-embed-sdk/src/types.ts (master) - - ThoughtSpot 26.9.0.cl introduces the `overrideHistoryState` configuration parameter for `AppEmbed`. When embedding ThoughtSpot in a host application, every internal ThoughtSpot navigation event (for example, switching between Liveboards or Answers) pushes a new entry onto the browser's history stack. This causes the browser *Back* button to step through ThoughtSpot's internal navigation before returning to the host application's prior page. - - Setting `overrideHistoryState: true` converts all ThoughtSpot internal `pushState` calls to `replaceState`, preventing ThoughtSpot navigation from polluting the host application's browser history stack. +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| - [source,JavaScript] - ---- - import { AppEmbed, init, AuthType } from '@thoughtspot/visual-embed-sdk'; +[discrete] +===== Browser history management in full application embedding - init({ - thoughtSpotHost: 'https://.thoughtspot.cloud', - authType: AuthType.TrustedAuthToken, - getAuthToken: () => fetch('/ts-token').then(r => r.json()).then(d => d.token), - }); +// SOURCE: SCAL-317516 +// SOURCE: thoughtspot/visual-embed-sdk/src/types.ts (master) - const embed = new AppEmbed('#embed-container', { - frameParams: { width: '100%', height: '100%' }, - overrideHistoryState: true, // <1> - }); +ThoughtSpot 26.9.0.cl introduces the `overrideHistoryState` configuration parameter for `AppEmbed`. When embedding ThoughtSpot in a host application, every internal ThoughtSpot navigation event (for example, switching between Liveboards or Answers) pushes a new entry onto the browser's history stack. This causes the browser *Back* button to step through ThoughtSpot's internal navigation before returning to the host application's prior page. - embed.render(); - ---- - <1> When set to `true`, ThoughtSpot replaces rather than pushes browser history entries during internal navigation. +Setting `overrideHistoryState: true` converts all ThoughtSpot internal `pushState` calls to `replaceState`, preventing ThoughtSpot navigation from polluting the host application's browser history stack. - [NOTE] - ==== - `overrideHistoryState` is available on `AppEmbed` only. It is not supported on `LiveboardEmbed`, `SearchEmbed`, or `SpotterEmbed`. Validate behavior across Chrome, Firefox, and Safari before enabling in production. - ==== +//// +[source,JavaScript] +---- +import { AppEmbed, init, AuthType } from '@thoughtspot/visual-embed-sdk'; - For more information, see xref:full-app-embed.adoc[Full application embedding]. +init({ + thoughtSpotHost: 'https://.thoughtspot.cloud', + authType: AuthType.TrustedAuthToken, + getAuthToken: () => fetch('/ts-token').then(r => r.json()).then(d => d.token), +}); - |[tag greenBackground]#NEW FEATURE# a| +const embed = new AppEmbed('#embed-container', { + frameParams: { width: '100%', height: '100%' }, + overrideHistoryState: true, // <1> +}); - [discrete] - ===== Collections in left navigation panel +embed.render(); +---- +<1> When set to `true`, ThoughtSpot replaces rather than pushes browser history entries during internal navigation. +//// - // SOURCE: SCAL-314461 +[NOTE] +==== +`overrideHistoryState` is available on `AppEmbed` only. It is not supported on `LiveboardEmbed`, `SearchEmbed`, or `SpotterEmbed`. Validate behavior across Chrome, Firefox, and Safari before enabling in production. +==== - The `HomeLeftNavItem.Collections` enum value is now available in the Visual Embed SDK. Embed developers can include *Collections* as a selectable navigation option in the embedded left navigation panel for full application embeds. When enabled, end users of the embedded application can navigate to *Collections* from the left navigation panel. +For more information, see xref:full-app-embed.adoc[Full application embedding]. - [source,JavaScript] - ---- - import { AppEmbed, HomeLeftNavItem, init, AuthType } from '@thoughtspot/visual-embed-sdk'; +|[tag greenBackground]#NEW FEATURE# a| - init({ - thoughtSpotHost: 'https://.thoughtspot.cloud', - authType: AuthType.TrustedAuthToken, - getAuthToken: () => fetch('/ts-token').then(r => r.json()).then(d => d.token), - }); +[discrete] +===== Collections in left navigation panel - const embed = new AppEmbed('#embed-container', { - frameParams: { width: '100%', height: '100%' }, - leftNavOrder: [ - HomeLeftNavItem.Home, - HomeLeftNavItem.Liveboards, - HomeLeftNavItem.Answers, - HomeLeftNavItem.Collections, // <1> - ], - }); +// SOURCE: SCAL-314461 - embed.render(); - ---- - <1> Include `HomeLeftNavItem.Collections` in the `leftNavOrder` array to show Collections in the embedded left navigation panel. +The `HomeLeftNavItem.Collections` enum value is now available in the Visual Embed SDK. Embed developers can include *Collections* as a selectable navigation option in the embedded left navigation panel for full application embeds. When enabled, end users of the embedded application can navigate to *Collections* from the left navigation panel. +//// +[source,JavaScript] +---- +import { AppEmbed, HomeLeftNavItem, init, AuthType } from '@thoughtspot/visual-embed-sdk'; + +init({ + thoughtSpotHost: 'https://.thoughtspot.cloud', + authType: AuthType.TrustedAuthToken, + getAuthToken: () => fetch('/ts-token').then(r => r.json()).then(d => d.token), +}); + +const embed = new AppEmbed('#embed-container', { + frameParams: { width: '100%', height: '100%' }, + leftNavOrder: [ + HomeLeftNavItem.Home, + HomeLeftNavItem.Liveboards, + HomeLeftNavItem.Answers, + HomeLeftNavItem.Collections, // <1> + ], +}); + +embed.render(); +---- +<1> Include `HomeLeftNavItem.Collections` in the `leftNavOrder` array to show Collections in the embedded left navigation panel. +//// +For more information, see xref:full-app-customize.adoc[Customize full application embedding]. - For more information, see xref:full-app-customize.adoc[Customize full application embedding]. +|==== - |==== - == Version 1.51.x, August 2026 [width="100%" cols="1,4"] @@ -1999,4 +2001,4 @@ Users with edit permissions can view and access the *Edit* action. The *Download When a user accesses the embedded application from a web browser that has third-party cookies disabled, the Visual Embed SDK emits the `NoCookieAccess` event to notify the developer. Cookies are disabled by default in Safari. Users can enable third-party cookies in Safari’s Preferences setting page or use another web browser. To know how to enable this setting by default on Safari for a ThoughtSpot embedded instance, contact ThoughtSpot Support. -|==== \ No newline at end of file +|==== From 1091302cb59222bee62f76adc973cb22b4c260b3 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Thu, 20 Aug 2026 07:43:31 +0530 Subject: [PATCH 32/32] API updates --- modules/ROOT/pages/api-changelog.adoc | 41 +---------------- .../ROOT/pages/semantic-integrations-api.adoc | 45 +++---------------- modules/ROOT/pages/whats-new.adoc | 5 +-- 3 files changed, 9 insertions(+), 82 deletions(-) diff --git a/modules/ROOT/pages/api-changelog.adoc b/modules/ROOT/pages/api-changelog.adoc index 110feaf28..7b61550e8 100644 --- a/modules/ROOT/pages/api-changelog.adoc +++ b/modules/ROOT/pages/api-changelog.adoc @@ -16,13 +16,8 @@ This page documents the changes introduced in each release of the Visual Embed S [discrete] ===== Browser history management in full application embedding +To override the browser history behavior for embedding application users and prevent users from getting trapped in back-button loops inside the embedded iframe environment, you can now set `overrideHistoryState` in the Visual Embed SDK. -// SOURCE: SCAL-317516 -// SOURCE: thoughtspot/visual-embed-sdk/src/types.ts (master) - -ThoughtSpot 26.9.0.cl introduces the `overrideHistoryState` configuration parameter for `AppEmbed`. When embedding ThoughtSpot in a host application, every internal ThoughtSpot navigation event (for example, switching between Liveboards or Answers) pushes a new entry onto the browser's history stack. This causes the browser *Back* button to step through ThoughtSpot's internal navigation before returning to the host application's prior page. - -Setting `overrideHistoryState: true` converts all ThoughtSpot internal `pushState` calls to `replaceState`, preventing ThoughtSpot navigation from polluting the host application's browser history stack. //// [source,JavaScript] @@ -45,46 +40,12 @@ embed.render(); <1> When set to `true`, ThoughtSpot replaces rather than pushes browser history entries during internal navigation. //// -[NOTE] -==== -`overrideHistoryState` is available on `AppEmbed` only. It is not supported on `LiveboardEmbed`, `SearchEmbed`, or `SpotterEmbed`. Validate behavior across Chrome, Firefox, and Safari before enabling in production. -==== - -For more information, see xref:full-app-embed.adoc[Full application embedding]. - |[tag greenBackground]#NEW FEATURE# a| [discrete] ===== Collections in left navigation panel - -// SOURCE: SCAL-314461 - The `HomeLeftNavItem.Collections` enum value is now available in the Visual Embed SDK. Embed developers can include *Collections* as a selectable navigation option in the embedded left navigation panel for full application embeds. When enabled, end users of the embedded application can navigate to *Collections* from the left navigation panel. -//// -[source,JavaScript] ----- -import { AppEmbed, HomeLeftNavItem, init, AuthType } from '@thoughtspot/visual-embed-sdk'; -init({ - thoughtSpotHost: 'https://.thoughtspot.cloud', - authType: AuthType.TrustedAuthToken, - getAuthToken: () => fetch('/ts-token').then(r => r.json()).then(d => d.token), -}); - -const embed = new AppEmbed('#embed-container', { - frameParams: { width: '100%', height: '100%' }, - leftNavOrder: [ - HomeLeftNavItem.Home, - HomeLeftNavItem.Liveboards, - HomeLeftNavItem.Answers, - HomeLeftNavItem.Collections, // <1> - ], -}); - -embed.render(); ----- -<1> Include `HomeLeftNavItem.Collections` in the `leftNavOrder` array to show Collections in the embedded left navigation panel. -//// For more information, see xref:full-app-customize.adoc[Customize full application embedding]. |==== diff --git a/modules/ROOT/pages/semantic-integrations-api.adoc b/modules/ROOT/pages/semantic-integrations-api.adoc index 4fc5ead75..0a9f80a9e 100644 --- a/modules/ROOT/pages/semantic-integrations-api.adoc +++ b/modules/ROOT/pages/semantic-integrations-api.adoc @@ -6,14 +6,9 @@ :page-pageid: semantic-integrations-api :page-description: Use the ThoughtSpot REST API v2.0 endpoints to create, search, import, and delete Snowflake Semantic View integration configurations programmatically. -// SOURCE: SCAL-309867 -// SOURCE: scaligent/prism/src/public-apis/semantic-integrations.graphql (master) -// SOURCE: scaligent/prism/src/public-apis/docs/descriptions/semantic-integrations/ (master) - -ThoughtSpot 26.9.0.cl introduces REST API v2.0 endpoints for managing Snowflake Semantic View integrations. These APIs allow administrators and data managers to create, search, import, and delete semantic integration configurations programmatically, without using the ThoughtSpot UI. +ThoughtSpot provides the Semantic View integrations REST API v2.0 endpoints to create, search, import, and delete semantic integration configurations programmatically. == Overview - Snowflake Semantic Views provide a governed semantic layer for data in Snowflake, including named measures, dimensions, and business-logic formulas. When you create a semantic integration in ThoughtSpot, the platform reads the semantic view definition from Snowflake and generates a corresponding ThoughtSpot data model (Worksheet). The model inherits the column names, descriptions, and formula definitions from the Snowflake Semantic View. You can use the semantic integration APIs to automate the following tasks: @@ -36,10 +31,7 @@ To use these APIs, the authenticated user must have one of the following privile * `ADMINISTRATION` (*Can administer ThoughtSpot*) * `DATAMANAGEMENT` (*Can manage data*) -If Role-Based Access Control (RBAC) is enabled on your instance, the user must also have: - -* `CAN_CREATE_OR_EDIT_CONNECTIONS` (*Can create/edit Connections*) -* *Can manage data models* +If Role-Based Access Control (RBAC) is enabled on your instance, the user requires `CAN_CREATE_OR_EDIT_CONNECTIONS` (*Can create/edit Connections*) privilege. == API endpoints @@ -55,14 +47,8 @@ If Role-Based Access Control (RBAC) is enabled on your instance, the user must a [#create-semantic-integration] == Create a semantic integration +To create a new semantic integration by reading the specified Snowflake Semantic View and generating a corresponding ThoughtSpot data model, use the `/api/rest/2.0/semantic-integrations/create` API endpoint. On success, the response includes the integration GUID, the generated model GUID, and a per-formula import report. -`POST /api/rest/2.0/semantic-integrations/create` - -Creates a new semantic integration by reading the specified Snowflake Semantic View and generating a corresponding ThoughtSpot data model. On success, the response includes the integration GUID, the generated model GUID, and a per-formula import report. - -=== Required privileges - -`ADMINISTRATION` or `DATAMANAGEMENT`. If RBAC is enabled: `CAN_CREATE_OR_EDIT_CONNECTIONS` and *Can manage data models*. === Request parameters @@ -179,13 +165,7 @@ curl -X POST \ [#search-semantic-integrations] == Search semantic integrations -`POST /api/rest/2.0/semantic-integrations/search` - -Returns a paginated list of semantic integrations matching the specified criteria. Returns all integrations if no filters are specified. - -=== Required privileges - -`ADMINISTRATION` or `DATAMANAGEMENT`. If RBAC is enabled: `CAN_CREATE_OR_EDIT_CONNECTIONS` and *Can manage data models*. +To fetch a paginated list of semantic integrations matching the specified criteria, use the `/api/rest/2.0/semantic-integrations/search` API endpoint. Returns all integrations if no filters are specified. === Request parameters @@ -258,10 +238,7 @@ curl -X POST \ [#import-semantic-integration] == Import a semantic integration - -`POST /api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/import` - -Re-imports semantic updates from the Snowflake CDW source for an existing integration, and rebuilds the corresponding ThoughtSpot data model. Use this endpoint after the source Snowflake Semantic View has been updated (formulas added, removed, or modified) to bring the ThoughtSpot model back in line with the CDW definition. +To re-import semantic updates from the Snowflake CDW source for an existing integration, and rebuild the corresponding ThoughtSpot data model, send a `POST` request to the `/api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/import` API endpoint. Send this API request, after the source Snowflake Semantic View has been updated (formulas added, removed, or modified) to bring the ThoughtSpot model back in line with the CDW definition. [NOTE] ==== @@ -273,9 +250,6 @@ The import operation: * Preserves the integration GUID, name, and `model_id`. Only the formula set is refreshed. * Returns the same `semantic_report` response as create, with an additional `change_status` per formula indicating whether each formula is `NEW`, `UPDATED`, or `UNCHANGED` since the previous import. -=== Required privileges - -`ADMINISTRATION` or `DATAMANAGEMENT`. If RBAC is enabled: `CAN_CREATE_OR_EDIT_CONNECTIONS` and *Can manage data models*. === Path parameters @@ -353,20 +327,13 @@ curl -X POST \ [#delete-semantic-integration] == Delete a semantic integration - -`POST /api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/delete` - -Permanently deletes the specified semantic integration and its generated ThoughtSpot data model from the system. +To permanently delete the specified semantic integration and its generated ThoughtSpot data model from the system, use the `/api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/delete` API endpoint. [WARNING] ==== Deletion is permanent and cannot be undone. If you need to restore the integration, use the `create` endpoint to re-import the Snowflake Semantic View. ==== -=== Required privileges - -`ADMINISTRATION` or `DATAMANAGEMENT`. If RBAC is enabled: `CAN_CREATE_OR_EDIT_CONNECTIONS` and *Can manage data models*. - === Path parameters [width="100%"] diff --git a/modules/ROOT/pages/whats-new.adoc b/modules/ROOT/pages/whats-new.adoc index 1688c82dc..255551f87 100644 --- a/modules/ROOT/pages/whats-new.adoc +++ b/modules/ROOT/pages/whats-new.adoc @@ -36,9 +36,8 @@ a| a| [discrete] -==== Browser history management in full application embedding [.version-badge.new]#New# - -The Visual Embed SDK 1.52.0 introduces the `overrideHistoryState` configuration parameter for `AppEmbed`. When ThoughtSpot is embedded in a host application, every internal navigation event pushes a new entry onto the browser history stack, causing the browser *Back* button to step through ThoughtSpot's internal pages before returning to the host application. Setting `overrideHistoryState: true` converts ThoughtSpot's internal `pushState` calls to `replaceState`, preventing internal navigation from polluting the host application's browser history stack. For more information, see xref:full-app-embed.adoc[Full application embedding]. +==== Browser history management in full application embedding +When ThoughtSpot is embedded in a host application, internal navigation pushes new entries onto the browser history stack, causing the browser *Back* button to step through ThoughtSpot's internal pages before returning to the host application. To override the browser history behavior for embedding application users and prevent users from getting trapped in back-button loops inside the embedded iframe environment, set `overrideHistoryState` in the Visual Embed SDK. ---