diff --git a/modules/ROOT/pages/.write-test b/modules/ROOT/pages/.write-test new file mode 100644 index 000000000..0e808f9c2 --- /dev/null +++ b/modules/ROOT/pages/.write-test @@ -0,0 +1 @@ +write access test - delete me \ No newline at end of file diff --git a/modules/ROOT/pages/api-changelog.adoc b/modules/ROOT/pages/api-changelog.adoc index 0619c8767..7b61550e8 100644 --- a/modules/ROOT/pages/api-changelog.adoc +++ b/modules/ROOT/pages/api-changelog.adoc @@ -8,6 +8,49 @@ This page documents the changes introduced in each release of the Visual Embed SDK. For information about the REST API v2.0 changes, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. +== Version 1.52.x, September 2026 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| + +[discrete] +===== Browser history management in full application embedding +To override the browser history behavior for embedding application users and prevent users from getting trapped in back-button loops inside the embedded iframe environment, you can now set `overrideHistoryState` in the Visual Embed SDK. + + +//// +[source,JavaScript] +---- +import { AppEmbed, init, AuthType } from '@thoughtspot/visual-embed-sdk'; + +init({ + thoughtSpotHost: 'https://.thoughtspot.cloud', + authType: AuthType.TrustedAuthToken, + getAuthToken: () => fetch('/ts-token').then(r => r.json()).then(d => d.token), +}); + +const embed = new AppEmbed('#embed-container', { + frameParams: { width: '100%', height: '100%' }, + overrideHistoryState: true, // <1> +}); + +embed.render(); +---- +<1> When set to `true`, ThoughtSpot replaces rather than pushes browser history entries during internal navigation. +//// + +|[tag greenBackground]#NEW FEATURE# a| + +[discrete] +===== Collections in left navigation panel +The `HomeLeftNavItem.Collections` enum value is now available in the Visual Embed SDK. Embed developers can include *Collections* as a selectable navigation option in the embedded left navigation panel for full application embeds. When enabled, end users of the embedded application can navigate to *Collections* from the left navigation panel. + +For more information, see xref:full-app-customize.adoc[Customize full application embedding]. + +|==== + + == Version 1.51.x, August 2026 [width="100%" cols="1,4"] @@ -1919,4 +1962,4 @@ Users with edit permissions can view and access the *Edit* action. The *Download When a user accesses the embedded application from a web browser that has third-party cookies disabled, the Visual Embed SDK emits the `NoCookieAccess` event to notify the developer. Cookies are disabled by default in Safari. Users can enable third-party cookies in Safari’s Preferences setting page or use another web browser. To know how to enable this setting by default on Safari for a ThoughtSpot embedded instance, contact ThoughtSpot Support. -|==== \ No newline at end of file +|==== diff --git a/modules/ROOT/pages/common/nav-in-product-help.adoc b/modules/ROOT/pages/common/nav-in-product-help.adoc index 73d3dedd9..46f7187b8 100644 --- a/modules/ROOT/pages/common/nav-in-product-help.adoc +++ b/modules/ROOT/pages/common/nav-in-product-help.adoc @@ -224,6 +224,11 @@ REST APIs ** link:{{navprefix}}/fetch-data-and-report-apis[Data and Report APIs] ** link:{{navprefix}}/spotter-api[Spotter APIs] *** link:{{navprefix}}/spotter-agent-apis[AI APIs (Spotter Agent and Spotter 3)] +*** link:{{navprefix}}/spotter-agent-conversation-apis[Spotter agent conversation APIs] +*** link:{{navprefix}}/spotter-agent-streaming-apis[Spotter agent streaming APIs] +*** link:{{navprefix}}/spotter-agent-process-results-apis[Process Spotter agent conversation results] +*** link:{{navprefix}}/spotter-agent-data-literacy-apis[Spotter agent data literacy APIs] +*** link:{{navprefix}}/spotter-agent-sharing-apis[Spotter agent conversation sharing APIs] *** link:{{navprefix}}/spotter-agent-instructions[Spotter AI agent instructions] *** link:{{navprefix}}/spotter-agent-conversation-mgmt-apis[APIs for managing saved conversations] *** link:{{navprefix}}/spotter-memory-migration[Spotter memory migration API] diff --git a/modules/ROOT/pages/common/nav-rest-api.adoc b/modules/ROOT/pages/common/nav-rest-api.adoc index 3ab94642e..d18328927 100644 --- a/modules/ROOT/pages/common/nav-rest-api.adoc +++ b/modules/ROOT/pages/common/nav-rest-api.adoc @@ -23,6 +23,11 @@ REST APIs ** link:{{navprefix}}/runtime-sort[Runtime sorting] ** link:{{navprefix}}/spotter-api[Spotter APIs] *** link:{{navprefix}}/spotter-agent-apis[AI APIs (Spotter Agent and Spotter 3)] +*** link:{{navprefix}}/spotter-agent-conversation-apis[Spotter agent conversation APIs] +*** link:{{navprefix}}/spotter-agent-streaming-apis[Spotter agent streaming APIs] +*** link:{{navprefix}}/spotter-agent-process-results-apis[Process Spotter agent conversation results] +*** link:{{navprefix}}/spotter-agent-data-literacy-apis[Spotter agent data literacy APIs] +*** link:{{navprefix}}/spotter-agent-sharing-apis[Spotter agent conversation sharing APIs] *** link:{{navprefix}}/spotter-agent-instructions[Spotter AI agent instructions] *** link:{{navprefix}}/spotter-agent-conversation-mgmt-apis[APIs for managing saved conversations] *** link:{{navprefix}}/spotter-memory-migration[Spotter memory migration API] diff --git a/modules/ROOT/pages/data-report-v2-api.adoc b/modules/ROOT/pages/data-report-v2-api.adoc index a73d16087..f1ed36d8e 100644 --- a/modules/ROOT/pages/data-report-v2-api.adoc +++ b/modules/ROOT/pages/data-report-v2-api.adoc @@ -687,4 +687,109 @@ To sort columns on a Liveboard or Answer, define runtime sort properties in `run For more information, see xref:runtime-sort.adoc#_rest_api_v2_0[Runtime sorting of columns]. - + [#answer-report] + === Answer Report API + + // SOURCE: SCAL-306069 + + The `POST /api/rest/2.0/report/answer` endpoint is generally available from 26.9.0.cl. Use this endpoint to export Answer data in CSV, XLSX, PDF, or PNG format. The endpoint supports saved Answers, pinned Answers (visualizations on a Liveboard), and Spotter-generated (ad hoc) Answers. + + ==== Prerequisites + + To download Answer data, the user must have at least *View* access to the Answer or Liveboard. If RBAC is enabled: + + * `DATADOWNLOADING` (Can download Data) — required for all export formats. + * `CAN_DOWNLOAD_DETAILED_DATA` (Can download detailed data) — required for CSV and XLSX. + * `CAN_DOWNLOAD_VISUALS` (Can download visuals) — required for PNG. + + ==== Request parameters + + [width="100%" cols="2,1,4"] + [options="header"] + |===== + | Parameter | Required | Description + | `metadata_identifier` | Conditional | GUID or name of the saved Answer. For pinned Answer exports, use the parent Liveboard GUID or name and pass `viz_guid` separately. + | `file_format` | Yes | Export format. Accepted values: `CSV`, `XLSX`, `PDF`, `PNG`. + | `viz_guid` | No | GUID of a pinned visualization on a Liveboard. When specified, `metadata_identifier` must identify the parent Liveboard. + | `personalised_view_identifier` | No | GUID or name of a Personalized View. When specified, the export uses data from that view. + | `runtime_filter` | No | Runtime filter overrides to apply to the export. + | `runtime_sort` | No | Runtime sort overrides to apply to the export. + | `runtime_param_override` | No | Runtime parameter overrides to apply to the export. + | `x_resolution` | No | Width of the PNG export in pixels. Range: 600–3840. Applies only when `file_format` is `PNG`. Default: 2254. + | `y_resolution` | No | Height of the PNG export in pixels. Range: 600–3840. Applies only when `file_format` is `PNG`. Default: 1588. + | `scaling_factor` | No | Scaling percentage for chart elements in PNG exports. Range: 80–400. Does not crop the image. Applies only when `file_format` is `PNG`. + |===== + + ==== Export a saved Answer + + [source,cURL] + ---- + curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/octet-stream' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "metadata_identifier": "my-saved-answer", + "file_format": "CSV" + }' \ + --output answer.csv + ---- + + ==== Export a pinned Answer + + [source,cURL] + ---- + curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/octet-stream' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "metadata_identifier": "", + "viz_guid": "", + "file_format": "PDF" + }' \ + --output pinned-answer.pdf + ---- + + ==== Export a Spotter Answer + + [source,cURL] + ---- + curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/octet-stream' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "metadata_identifier": "", + "file_format": "XLSX" + }' \ + --output spotter-answer.xlsx + ---- + + [NOTE] + ==== + Pass the answer ID from the Spotter API response as `metadata_identifier`. XLSX and PDF formats are supported for Spotter Answers from 26.9.0.cl. + ==== + + ==== Export a PNG with custom dimensions + + [source,cURL] + ---- + curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/octet-stream' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "metadata_identifier": "my-saved-answer", + "file_format": "PNG", + "x_resolution": 3840, + "y_resolution": 2160, + "scaling_factor": 150 + }' \ + --output answer-4k.png + ---- + \ No newline at end of file diff --git a/modules/ROOT/pages/rest-apiv2-changelog.adoc b/modules/ROOT/pages/rest-apiv2-changelog.adoc index 22e0cfcaf..dbf3eca3b 100644 --- a/modules/ROOT/pages/rest-apiv2-changelog.adoc +++ b/modules/ROOT/pages/rest-apiv2-changelog.adoc @@ -8,6 +8,127 @@ This changelog lists the features and enhancements introduced in REST API v2.0. For information about new features and enhancements available for embedded analytics, see xref:whats-new.adoc[What's New]. +== Version 26.9.0.cl, September 2026 + + === Answer Export API enhancements — General Availability + + // SOURCE: SCAL-306069 + + The `POST /api/rest/2.0/report/answer` endpoint is generally available from 26.9.0.cl. The `isAnswerExportV2Enabled` flag is enabled by default on all ThoughtSpot Cloud instances. The following enhancements are included in this release: + + Pinned Answer export:: + Pass `viz_guid` to export a pinned Answer (a visualization on a Liveboard) directly. Liveboard-level filters and runtime overrides are applied automatically. The `metadata_identifier` must be the parent Liveboard GUID or name. + + Personalized View support:: + Pass `personalised_view_identifier` to export data from a specific Personalized View of a Liveboard. + + Spotter Answer export:: + XLSX and PDF export formats are now supported for Spotter-generated (ad hoc) Answers, in addition to CSV and PNG. + + Custom PNG dimensions:: + Use `x_resolution` and `y_resolution` parameters to specify custom pixel dimensions for PNG exports. Accepted range: 600–3840 px per axis. Default: 2254 × 1588. + + Display scaling:: + Use `scaling_factor` (range: 80–400) to adjust the relative size of chart elements in a PNG export without cropping the image. + + Dynamic file naming:: + Exported files are automatically named based on the Answer title with the correct file extension (`.png`, `.pdf`, `.csv`, `.xlsx`) appended. + + For more information, see xref:data-report-v2-api.adoc#answer-report[Answer Report API]. + + === Snowflake Semantic View integration APIs + + // SOURCE: SCAL-309867 + + ThoughtSpot 26.9.0.cl introduces REST API v2.0 endpoints for managing Snowflake Semantic View integrations programmatically. These APIs allow administrators and data managers to create, search, import, and delete semantic integration configurations without using the ThoughtSpot UI. + + [width="100%"] + [options="header"] + |===== + | Method | Endpoint | Description + | `POST` | `/api/rest/2.0/semantic-integrations/create` | Creates a new semantic integration by reading a Snowflake Semantic View and generating a ThoughtSpot data model. + | `POST` | `/api/rest/2.0/semantic-integrations/search` | Returns a list of semantic integrations matching the specified filter criteria. + | `POST` | `/api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/import` | Re-imports semantic updates from Snowflake and refreshes the associated ThoughtSpot data model. + | `POST` | `/api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/delete` | Deletes a semantic integration and its generated ThoughtSpot data model. + |===== + + Required privilege: `ADMINISTRATION` or `DATAMANAGEMENT`. If RBAC is enabled, the user also requires the `CAN_CREATE_OR_EDIT_CONNECTIONS` privilege and permission to manage data models. + + For more information, see xref:semantic-integrations-api.adoc[Snowflake Semantic View integration APIs]. + + === Spotter Memory — General Availability + + // SOURCE: SCAL-306173 + + The Spotter Memory feature is generally available from 26.9.0.cl. The memory APIs introduced in 26.8.0.cl (`POST /api/rest/2.0/ai/memory/import` and `POST /api/rest/2.0/ai/memory/export`) are enabled by default on all ThoughtSpot Cloud instances. Administrators can manage and audit Spotter training data programmatically without enabling a feature flag. + + For more information, see xref:spotter-ai-memory-api.adoc[Spotter memory APIs]. + + === Spotter Agent — Conversation sharing APIs + + // SOURCE: SCAL-306173 (aug.26.mt) + + ThoughtSpot 26.9.0.cl introduces REST API v2.0 endpoints for sharing saved Spotter agent conversations with other users or groups. Shared conversations are always `READ_ONLY`. + + [width="100%"] + [options="header"] + |===== + | Method | Endpoint | Description + | `POST` | `/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` | Shares a saved Spotter conversation with specified principals. Use `grant` and `revoke` arrays to manage access. + | `GET` | `/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content` | Returns the content of a shared Spotter conversation — messages, data sources, and answer details. + | `GET` | `/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info` | Returns sharing metadata — the list of principals the conversation is shared with and their access levels. The `is_shared_content_outdated` flag indicates if the shared snapshot is stale. + |===== + + For more information, see xref:spotter-agent-sharing-apis.adoc[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 @@ -169,7 +290,7 @@ Stop in-progress agent response:: * `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response` + Stops a Spotter agent response that is currently in progress for a given conversation session. -For more information, see xref:spotter-agent-apis.adoc#_stop_an_in_progress_agent_response[Stop an in-progress agent response]. +For more information, see xref:spotter-agent-conversation-apis.adoc#_stop_an_in_progress_agent_response[Stop an in-progress agent response]. === Authentication The following new endpoints allow searching for the authentication configuration at the cluster or Org level, and also allow enabling and disabling authentication. These endpoints currently support only trusted authentication. diff --git a/modules/ROOT/pages/semantic-integrations-api.adoc b/modules/ROOT/pages/semantic-integrations-api.adoc new file mode 100644 index 000000000..0a9f80a9e --- /dev/null +++ b/modules/ROOT/pages/semantic-integrations-api.adoc @@ -0,0 +1,376 @@ += Snowflake Semantic View integration APIs +:toc: true +:toclevels: 3 + +:page-title: Snowflake Semantic View integration APIs +:page-pageid: semantic-integrations-api +:page-description: Use the ThoughtSpot REST API v2.0 endpoints to create, search, import, and delete Snowflake Semantic View integration configurations programmatically. + +ThoughtSpot provides the Semantic View integrations REST API v2.0 endpoints to create, search, import, and delete semantic integration configurations programmatically. + +== Overview +Snowflake Semantic Views provide a governed semantic layer for data in Snowflake, including named measures, dimensions, and business-logic formulas. When you create a semantic integration in ThoughtSpot, the platform reads the semantic view definition from Snowflake and generates a corresponding ThoughtSpot data model (Worksheet). The model inherits the column names, descriptions, and formula definitions from the Snowflake Semantic View. + +You can use the semantic integration APIs to automate the following tasks: + +* Create a semantic integration that links a Snowflake Semantic View to a ThoughtSpot data model. +* Search and list existing semantic integrations. +* Re-import a semantic integration to refresh the ThoughtSpot model after the source Snowflake Semantic View has changed. +* Delete a semantic integration and its generated ThoughtSpot model. + +[NOTE] +==== +The semantic integration APIs are available on ThoughtSpot Cloud instances from 26.9.0.cl. +Snowflake is the only supported CDW connector type (`RDBMS_SNOWFLAKE`). +==== + +== Prerequisites + +To use these APIs, the authenticated user must have one of the following privileges: + +* `ADMINISTRATION` (*Can administer ThoughtSpot*) +* `DATAMANAGEMENT` (*Can manage data*) + +If Role-Based Access Control (RBAC) is enabled on your instance, the user requires `CAN_CREATE_OR_EDIT_CONNECTIONS` (*Can create/edit Connections*) privilege. + +== API endpoints + +[width="100%"] +[options="header"] +|===== +| Method | Endpoint | Description +| `POST` | `/api/rest/2.0/semantic-integrations/create` | Creates a new semantic integration by reading a Snowflake Semantic View and generating a ThoughtSpot data model. +| `POST` | `/api/rest/2.0/semantic-integrations/search` | Returns a list of semantic integrations matching the specified filter criteria. +| `POST` | `/api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/import` | Re-imports semantic updates from the CDW source and refreshes the associated ThoughtSpot data model. +| `POST` | `/api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/delete` | Deletes a semantic integration and its generated ThoughtSpot data model. +|===== + +[#create-semantic-integration] +== Create a semantic integration +To create a new semantic integration by reading the specified Snowflake Semantic View and generating a corresponding ThoughtSpot data model, use the `/api/rest/2.0/semantic-integrations/create` API endpoint. On success, the response includes the integration GUID, the generated model GUID, and a per-formula import report. + + +=== Request parameters + +[width="100%"] +[options="header"] +|===== +| Parameter | Type | Required | Description +| `connection_identifier` | String | Yes | GUID or name of the Snowflake connection in ThoughtSpot. +| `name` | String | Yes | Display name for the semantic integration. Must be unique. +| `database_name` | String | Yes | Database name in the Snowflake CDW that contains the semantic view. +| `schema_name` | String | Yes | Schema name in the Snowflake CDW that contains the semantic view. +| `semantic_view_name` | String | Yes | Name of the Snowflake Semantic View to integrate. +| `type` | String | Yes | CDW connector type. Only accepted value: `RDBMS_SNOWFLAKE`. +| `description` | String | No | Optional description for the semantic integration. +| `tags` | Array | No | Tag GUIDs or names to associate with the integration. +|===== + +=== Response fields + +[width="100%"] +[options="header"] +|===== +| Field | Type | Description +| `id` | String | GUID of the newly created semantic integration. +| `name` | String | Display name of the semantic integration. +| `model_id` | String | GUID of the ThoughtSpot data model generated for this integration. +| `model_name` | String | Display name of the generated ThoughtSpot data model. +| `semantic_report` | Object | Per-formula import report. See <<_semantic_report_fields>>. +|===== + +[#semantic-report-fields] +=== Semantic report fields + +The `semantic_report` object contains a summary and a list of per-formula import results. + +`summary` fields: + +[width="100%"] +[options="header"] +|===== +| Field | Type | Description +| `total` | Integer | Total number of formulas in the Snowflake Semantic View. +| `imported` | Integer | Number of formulas successfully imported. +| `failed` | Integer | Number of formulas that failed to import. +| `skipped` | Integer | Number of formulas that were skipped. +|===== + +`formulas` array — each entry contains: + +[width="100%"] +[options="header"] +|===== +| Field | Type | Description +| `id` | String | Formula GUID in the generated ThoughtSpot model. +| `name` | String | Formula name. +| `description` | String | Formula description. +| `source_expression` | String | Original CDW expression. +| `translated_formula` | String | Equivalent ThoughtSpot formula expression. +| `import_status` | String | One of `IMPORTED`, `FAILED`, or `SKIPPED`. +| `change_status` | String | One of `NEW`, `UPDATED`, or `UNCHANGED`. Null on initial create (populated by import). +|===== + +=== Example request + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/semantic-integrations/create' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "connection_identifier": "", + "name": "Sales Semantic View", + "database_name": "SALES_DB", + "schema_name": "PUBLIC", + "semantic_view_name": "SALES_SEMANTIC_VIEW", + "type": "RDBMS_SNOWFLAKE", + "description": "Semantic integration for the Sales Snowflake Semantic View" +}' +---- + +=== Example response + +[source,JSON] +---- +{ + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Sales Semantic View", + "model_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", + "model_name": "Sales Semantic View", + "semantic_report": { + "summary": { + "total": 5, + "imported": 4, + "failed": 0, + "skipped": 1 + }, + "formulas": [ + { + "id": "formula-guid-001", + "name": "Total Revenue", + "description": "Sum of all revenue", + "source_expression": "SUM(revenue)", + "translated_formula": "sum(revenue)", + "import_status": "IMPORTED", + "change_status": null + } + ] + } +} +---- + +[#search-semantic-integrations] +== Search semantic integrations + +To fetch a paginated list of semantic integrations matching the specified criteria, use the `/api/rest/2.0/semantic-integrations/search` API endpoint. Returns all integrations if no filters are specified. + +=== Request parameters + +[width="100%"] +[options="header"] +|===== +| Parameter | Type | Required | Description +| `pattern` | String | No | Substring filter to narrow search results by integration name. +| `author_identifiers` | Array | No | Filter by the GUID or username of the user who created the integration. +| `connection_identifiers` | Array | No | Filter by the GUID or name of the Snowflake connection associated with the integration. +| `sort_options` | Object | No | Sort configuration. See <<_sort_options>>. +| `record_offset` | Integer | No | Number of records to skip for pagination. Minimum: 0. Default: 0. +| `record_size` | Integer | No | Maximum number of records to return. Use `0` to return all records. Default: 10. +|===== + +[#sort-options] +==== Sort options + +[width="100%"] +[options="header"] +|===== +| Field | Type | Description +| `field_name` | String | Sort field. One of: `NAME`, `AUTHOR`, `CREATED_TIME`, `MODIFIED_TIME`. +| `order` | String | Sort direction. `ASC` for ascending, `DESC` for descending. +|===== + +=== Response fields + +Returns an array of objects, each with the following fields: + +[width="100%"] +[options="header"] +|===== +| Field | Type | Description +| `id` | String | GUID of the semantic integration. +| `name` | String | Display name of the semantic integration. +| `description` | String | Description of the semantic integration. Null if not set. +| `model_id` | String | GUID of the associated ThoughtSpot data model. +| `model_name` | String | Display name of the associated ThoughtSpot data model. +| `import_type` | String | How the semantic definition was sourced. `CDW` for Snowflake Semantic View; `FILE` for file upload. +| `type` | String | CDW connector type. Currently always `RDBMS_SNOWFLAKE`. +| `connection_id` | String | GUID of the Snowflake connection. +| `connection_name` | String | Display name of the Snowflake connection. +| `author_id` | String | GUID of the user who created the integration. +| `author_name` | String | Username of the user who created the integration. +| `creation_time_in_millis` | Float | Creation time in Unix epoch milliseconds. +| `modification_time_in_millis` | Float | Last modification time in Unix epoch milliseconds. +| `tags` | Array | Tags associated with the integration, each with `id` and `name`. +|===== + +=== Example request + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/semantic-integrations/search' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "connection_identifiers": [""], + "sort_options": { + "field_name": "MODIFIED_TIME", + "order": "DESC" + }, + "record_size": 20, + "record_offset": 0 +}' +---- + +[#import-semantic-integration] +== Import a semantic integration +To re-import semantic updates from the Snowflake CDW source for an existing integration, and rebuild the corresponding ThoughtSpot data model, send a `POST` request to the `/api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/import` API endpoint. Send this API request, after the source Snowflake Semantic View has been updated (formulas added, removed, or modified) to bring the ThoughtSpot model back in line with the CDW definition. + +[NOTE] +==== +Importing updates is not supported for integrations created using the file upload option in the ThoughtSpot UI. To refresh a file-upload-based integration, use the ThoughtSpot UI. +==== + +The import operation: + +* Preserves the integration GUID, name, and `model_id`. Only the formula set is refreshed. +* Returns the same `semantic_report` response as create, with an additional `change_status` per formula indicating whether each formula is `NEW`, `UPDATED`, or `UNCHANGED` since the previous import. + + +=== Path parameters + +[width="100%"] +[options="header"] +|===== +| Parameter | Type | Required | Description +| `semantic_integration_identifier` | String | Yes | GUID or name of the semantic integration to re-import. +|===== + +=== Response fields + +Same as <>, with the addition of the `change_status` field in each formula entry: + +[width="100%"] +[options="header"] +|===== +| `change_status` value | Description +| `NEW` | Formula is new since the previous import. +| `UPDATED` | Formula definition changed since the previous import. +| `UNCHANGED` | Formula is unchanged since the previous import. +|===== + +=== Example request + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/semantic-integrations/Sales%20Semantic%20View/import' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + --data-raw '{}' +---- + +=== Example response + +[source,JSON] +---- +{ + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Sales Semantic View", + "model_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", + "model_name": "Sales Semantic View", + "semantic_report": { + "summary": { + "total": 6, + "imported": 5, + "failed": 0, + "skipped": 1 + }, + "formulas": [ + { + "id": "formula-guid-001", + "name": "Total Revenue", + "description": "Sum of all revenue", + "source_expression": "SUM(revenue)", + "translated_formula": "sum(revenue)", + "import_status": "IMPORTED", + "change_status": "UNCHANGED" + }, + { + "id": "formula-guid-002", + "name": "Net Profit", + "description": "Revenue minus costs", + "source_expression": "SUM(revenue) - SUM(costs)", + "translated_formula": "sum(revenue) - sum(costs)", + "import_status": "IMPORTED", + "change_status": "NEW" + } + ] + } +} +---- + +[#delete-semantic-integration] +== Delete a semantic integration +To permanently delete the specified semantic integration and its generated ThoughtSpot data model from the system, use the `/api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/delete` API endpoint. + +[WARNING] +==== +Deletion is permanent and cannot be undone. If you need to restore the integration, use the `create` endpoint to re-import the Snowflake Semantic View. +==== + +=== Path parameters + +[width="100%"] +[options="header"] +|===== +| Parameter | Type | Required | Description +| `semantic_integration_identifier` | String | Yes | GUID or name of the semantic integration to delete. +|===== + +=== Example request + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/semantic-integrations/Sales%20Semantic%20View/delete' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + --data-raw '{}' +---- + +A successful delete returns HTTP `200` with an empty response body. + +== Error responses + +[width="100%"] +[options="header"] +|===== +| Code | Description +| 400 | Bad Request — required parameter missing or invalid value (for example, unsupported `type`). +| 401 | Unauthorized — authentication token missing, expired, or invalid. +| 403 | Forbidden — the caller lacks the required privilege. +| 404 | Not Found — no semantic integration exists with the given identifier. +|===== + +== Related resources + +* xref:connections.adoc[Data connections] +* xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog] +* xref:rest-api-v2-reference.adoc[REST API v2.0 reference] diff --git a/modules/ROOT/pages/spotter-agent-apis.adoc b/modules/ROOT/pages/spotter-agent-apis.adoc index 5ea2587af..383af675b 100644 --- a/modules/ROOT/pages/spotter-agent-apis.adoc +++ b/modules/ROOT/pages/spotter-agent-apis.adoc @@ -19,48 +19,60 @@ The key capabilities of the Spotter APIs include the following: * Recommending relevant datasets or data sources * Decomposing complex user queries -== API endpoints - -The AI REST API endpoints listed in the following table provide all the functionality necessary to implement a Spotter 3 conversational experience in your application, from data source discovery through to streaming query responses. +== Supported API endpoints The API endpoints introduced for Spotter 2 also support Spotter 3 capabilities as of version 26.2.0.cl. Some of these API endpoints are deprecated in 26.5.0.cl; ThoughtSpot recommends using the new API endpoints instead. Initialize session:: -Call the create agent conversation API (`/api/rest/2.0/ai/agent/conversation/create`) with a data source ID to establish the session context. When auto mode is enabled, and no data source ID is specified in the API request, Spotter will automatically identify the appropriate data source. +Call the create agent conversation API (`/api/rest/2.0/ai/agent/conversation/create`) with a data source ID to establish the session context. When auto mode is enabled, and no data source ID is specified in the API request, Spotter will automatically identify the appropriate data source. See xref:spotter-agent-conversation-apis.adoc[Spotter agent conversation APIs]. Execute queries:: -To execute queries and generate a standard response synchronously, use the Send agent conversation message API (`/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send`). The send agent message API (`/api/rest/2.0/ai/agent/{conversation_identifier}/converse`) is deprecated in 26.5.0.cl and later versions. +To execute queries and generate a standard response synchronously, use the Send agent conversation message API (`/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send`). The send agent message API (`/api/rest/2.0/ai/agent/{conversation_identifier}/converse`) is deprecated in 26.5.0.cl and later versions. See xref:spotter-agent-conversation-apis.adoc[Spotter agent conversation APIs]. Real-time output (streaming):: -To stream responses to the application UI in real-time, use the `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream`. The legacy streaming API (`/api/rest/2.0/ai/agent/converse/sse`) is deprecated in 26.5.0.cl and later versions. +To stream responses to the application UI in real-time, use the `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream`. The legacy streaming API (`/api/rest/2.0/ai/agent/converse/sse`) is deprecated in 26.5.0.cl and later versions. See xref:spotter-agent-streaming-apis.adoc[Spotter agent streaming APIs]. + +Share a conversation:: +Share a saved Spotter conversation with other users or groups as read-only content. See xref:spotter-agent-sharing-apis.adoc[Spotter agent conversation sharing APIs]. -=== Supported API endpoints [width="100%" cols="1"] |===== a|`POST /api/rest/2.0/ai/agent/conversation/create` + -xref:spotter-agent-apis.adoc#_create_a_conversation_session_with_spotter_agent[Creates a conversation session with the Spotter agent] to generate Answers for the specified data context. +xref:spotter-agent-conversation-apis.adoc#_create_a_conversation_session_with_spotter_agent[Creates a conversation session with the Spotter agent] to generate Answers for the specified data context. __Available on ThoughtSpot Cloud instances from 10.13.0.cl onwards. Breaking changes introduced in 26.5.0.cl.__ a| `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send` [.version-badge.new]#New# + -xref:spotter-agent-apis.adoc#_send_queries_to_a_conversation_session[Sends natural language messages] to an existing Spotter agent conversation and returns the complete response synchronously. +xref:spotter-agent-conversation-apis.adoc#_send_queries_to_a_conversation_session[Sends natural language messages] to an existing Spotter agent conversation and returns the complete response synchronously. __Replaces /api/rest/2.0/ai/agent/{conversation_identifier}/converse__. a|`POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream` [.version-badge.new]#New# + -xref:spotter-agent-apis.adoc#_send_a_query_to_agent_and_get_streaming_responses[Sends one or more natural language messages] to an existing Spotter agent conversation and returns the response as a real-time Server-Sent Events (SSE) stream. +xref:spotter-agent-streaming-apis.adoc[Sends one or more natural language messages] to an existing Spotter agent conversation and returns the response as a real-time Server-Sent Events (SSE) stream. __Replaces /api/rest/2.0/ai/agent/converse/sse__. a|`POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response` [.version-badge.new]#New# + -xref:spotter-agent-apis.adoc#_stop_an_in_progress_agent_response[Stops an in-progress Spotter agent response] for a given conversation session. The conversation session remains active after the response stops. + +xref:spotter-agent-conversation-apis.adoc#_stop_an_in_progress_agent_response[Stops an in-progress Spotter agent response] for a given conversation session. The conversation session remains active after the response stops. + __Available on ThoughtSpot Cloud instances from 26.6.0.cl onwards.__ a| `POST /api/rest/2.0/ai/data-source-suggestions` [beta betaBackground]^Beta^ + -xref:spotter-agent-apis.adoc#_get_data_source_suggestions[Returns a list of relevant data sources], such as Models, based on a query and thus helping users and agents choose the most appropriate data source for analytics. + +xref:spotter-agent-data-literacy-apis.adoc#_get_data_source_suggestions[Returns a list of relevant data sources], such as Models, based on a query and thus helping users and agents choose the most appropriate data source for analytics. + __Available on ThoughtSpot Cloud instances from 10.15.0.cl onwards__. a| `POST /api/rest/2.0/ai/relevant-questions/` [beta betaBackground]^Beta^ + -xref:spotter-agent-apis.adoc#_get_relevant_questions[Decomposes a user query] into relevant sub-questions. Guides users to explore data more deeply for a comprehensive analysis. + +xref:spotter-agent-data-literacy-apis.adoc#_get_relevant_questions[Decomposes a user query] into relevant sub-questions. Guides users to explore data more deeply for a comprehensive analysis. + __Available on ThoughtSpot Cloud instances from 10.13.0.cl onwards__. +a| `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` [.version-badge.new]#New# + +xref:spotter-agent-sharing-apis.adoc#_share_a_conversation[Shares a saved Spotter conversation] with one or more users or groups. Use `grant` and `revoke` arrays to manage access. Shared conversations are `READ_ONLY`. + +__Available on ThoughtSpot Cloud instances from 26.9.0.cl onwards.__ + +a| `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content` [.version-badge.new]#New# + +xref:spotter-agent-sharing-apis.adoc#_get_shared_content[Returns the shared content] of a Spotter conversation, including messages and associated answers. + +__Available on ThoughtSpot Cloud instances from 26.9.0.cl onwards.__ + +a| `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info` [.version-badge.new]#New# + +xref:spotter-agent-sharing-apis.adoc#_get_share_information[Returns sharing metadata] for a Spotter conversation — the list of principals it is shared with 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__. @@ -70,1223 +82,19 @@ Legacy API endpoint to send natural language queries to a conversation session w __Deprecated in 26.5.0.cl__. |===== -== Create a conversation session with Spotter Agent - -The `/api/rest/2.0/ai/agent/conversation/create` API endpoint creates a new conversation session with Spotter Agent for a specific or multi-data context and returns a conversation ID. - -=== Request parameters -The request body must include the `metadata_context`. REST API clients must have at least view access to the data source objects specified in the API request to create a conversation session and use it for subsequent queries. - -[width="100%" cols="2,4"] -[options='header'] -|===== -|Form parameter| Description -|`metadata_context` a| Defines the data context for the conversation. - -* `type` + -Metadata context type. The context type is mandatory. Select one of the following values: - -** `AUTO_MODE` to allow Spotter Agent to automatically discover and select the most relevant datasets for users' queries. -** `DATA_SOURCE` to set a specific data source as the data context. You must specify `data_source_context` and data source IDs. + -To set a specific data source object, use `data_source_identifier`. + -To set multi-data context, use `data_source_identifiers`. -** `data_source` [.version-badge.deprecated]#Deprecated# + -This option is deprecated in 26.5.0.cl. ThoughtSpot recommends using the `DATA_SOURCE` with `data_source_context` and data source IDs instead. - -|`conversation_settings` a|__Optional__. Defines additional parameters for the conversation context. You can set any of the following attributes as needed: - -* `enable_contextual_change_analysis` + -__Boolean__. When enabled, Spotter analyzes how context changes over time, that is, comparing results from different queries. Enabled by default in 26.2.0.cl and later versions. -* `enable_natural_language_answer_generation` + -__Boolean__. Allows sending natural language queries to the conversation session. Enabled by default in 26.2.0.cl and later versions. -* `enable_reasoning` + -__Boolean__. Allows Spotter to use reasoning for deep analysis and precise responses. Enabled by default in 26.2.0.cl and later versions. -* `enable_save_chat` + -When set to `true`, adds the conversation to chat history. -|===== - -=== Example request - -With AUTO_MODE for metadata context:: - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/create' \ - -H 'Accept: application/json' \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {AUTH_TOKEN}' \ - --data-raw '{ - "metadata_context": { - "type": "AUTO_MODE" - }, - "conversation_settings": { - "enable_save_chat": true - } -}' ----- - -For a single data source as the data context:: - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/create' \ - -H 'Accept: application/json' \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {AUTH_TOKEN}' \ - --data-raw '{ - "metadata_context": { - "type": "DATA_SOURCE", - "data_source_context": { - "data_source_identifier": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" - } - }, - "conversation_settings": {} -}' ----- - -For multi-data source context:: - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/create' \ - -H 'Accept: application/json' \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {AUTH_TOKEN}' \ - --data-raw '{ - "metadata_context": { - "type": "DATA_SOURCE", - "data_source_context": { - "data_source_identifiers": [ - "a1b2c3d4-e5f6-7890-abcd-ef1234567890", - "b2c3d4e5-f6a7-8901-bcde-f12345678901" - ] - } - }, - "conversation_settings": { - "enable_save_chat": true - } -}' ----- - -=== API response - -If the API request is successful, the API returns the conversation ID and identifier in the response body. - -[source,JSON] ----- -{ - "conversation_id": "wwHQ5j8O8dQC", - "conversation_identifier": "wwHQ5j8O8dQC" -} ----- - -* `conversation_identifier` + -Use this for all subsequent message calls. -* `conversation_id` [.version-badge.deprecated]#Deprecated# + -Returns the same value as `conversation_identifier`. - -== Send queries to a conversation session - -To send queries to an ongoing conversation session with the Spotter agent and receive a response synchronously, use the `/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send` API endpoint. - -This API operation requires the conversation ID obtained from the conversation creation API endpoint (`/api/rest/2.0/ai/agent/conversation/create`). The user making the API request must have access to the conversation session. The API request body must include at least one message in natural language format. - -=== Request parameters - -[width="100%" cols="2,2,4"] -[options='header'] -|===== -|Parameter|Type| Description -|`conversation_identifier`|Path parameter|__String__. Required. Specify the conversation ID received from the xref:spotter-agent-apis.adoc#_create_a_conversation_session_with_spotter_agent[POST /api/rest/2.0/ai/agent/conversation/create] API call. -|`messages`|Form parameter|_Array of strings_. Required. Specify at least one query in natural language. For example, `total sales of jackets last month`. -|===== - - -//// -|`settings` |__Optional__. Defines additional parameters for the conversation context. You can set any of the following attributes as needed: - -* `enable_contextual_change_analysis` + -__Boolean__. When enabled, Spotter analyzes how the context changes over time, that is comparing results from different queries. -* `enable_natural_language_answer_generation` + -__Boolean__. Allows sending natural language queries to the conversation session. -* `enable_reasoning` + -__Boolean__. Allows Spotter to use reasoning for deep analysis and precise responses. -//// - -=== Request and response examples - -The following example sends a data comparison query to a conversation session. The conversation ID is specified in the request URL as a path parameter. - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send' \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {AUTH_TOKEN}' \ - --data-raw '{ - "messages": [ - "Sales in 2025 vs 2024" - ] -}' ----- - -If the request is successful, the API returns an array of objects in the response. The messages in the API response include the following parts: - -[source,JSON] ----- -[ - { - "type": "text", - "text": "\n\nI'll compare sales between 2025 and 2024. First, let me get the dataset context.", - "metadata": {}, - "internal": {}, - "agent_context": "" - }, - { - "type": "text", - "text": "```json\n{\"dataset_name\":\"(Sample) Retail - Apparel\",\"columns\":[{\"name\":\"sales\",\"type\":\"MEASURE\"},{\"name\":\"date\",\"type\":\"ATTRIBUTE\"}]}\n```", - "metadata": {}, - "internal": {}, - "agent_context": "" - }, - { - "type": "answer", - "title": "Compare total sales for 2025 vs 2024", - "description": "", - "session_id": "842bb67a-e08e-4861-97e8-8db9538db51d", - "gen_no": 2, - "sage_query": "[sales] [date] = '2025' vs [date] = '2024'", - "tml_tokens": ["[sales]", "[date] = '2025' vs [date] = '2024'"], - "formulas": [], - "parameters": [], - "subqueries": [], - "viz_suggestion": "CAEQIBomEiQ2NjE5NzI0Yy1kMjVlLTU4MDItOWNjOC1jNDA3MWY3OWY5MzAoATIA", - "metadata": { - "output": "", - "worksheet_id": "cd252e5c-b552-49a8-821d-3eadaa049cca", - "chart_type": "KPI", - "interrupted": false, - "data_awareness_enabled": true - }, - "internal": {} - }, - { - "type": "text", - "text": "\n\nThe visualization shows year-over-year comparison. You can identify growth or decline trends.", - "metadata": {}, - "internal": {}, - "agent_context": "" - } -] ----- - -The following example sends a follow-up question to the same conversation session. - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send' \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {AUTH_TOKEN}' \ - --data-raw '{ - "messages": [ - "Now break that down by product category" - ] -}' ----- - -If the request is successful, the agent returns the response for the follow-up question: - -[source,JSON] ----- -[{ - "type": "text", - "text": "I'll add product category to the comparison.", - "metadata": {}, - "internal": {}, - "agent_context": "" - }, - { - "type": "answer", - "title": "Sales by Product Category: 2025 vs 2024", - "session_id": "9abc1234-0000-0000-0000-000000000005", - "gen_no": 3, - "sage_query": "[sales] [product category] [date] = '2025' vs [date] = '2024'", - "tml_tokens": ["[sales]", "[product category]", "[date] = '2025' vs [date] = '2024'"], - "formulas": [], - "parameters": [], - "subqueries": [], - "viz_suggestion": "", - "metadata": { - "chart_type": "BAR", - "worksheet_id": "cd252e5c-b552-49a8-821d-3eadaa049cca" - }, - "internal": {} - }] ----- - -In each response, the agent returns the following information: - -* `type` + -Type of the message, such as text, answer, or error. -* `text` + -Response message generated for the query. -* `metadata` + -Additional information based on the message type. For example, answer metadata, chart type, or the data source ID. -* `tml_tokens` + -Query string broken down as TML tokens. - -In case of errors, the response returns the error details: - -[source,JSON] ----- -[{ - "type": "error", - "message": "The conversation session has expired. Please create a new conversation.", - "code": "SESSION_EXPIRED" -}] ----- - - - -//// -The following example shows the response text contents for the `answer` message type. - -[source,JSON] ----- -[ - { - "id": "r24X7D99SROD", - "type": "answer", - "group_id": "o8dQ9SAWdtrL", - "metadata": { - "sage_query": "[sales] [item type] = [item type].'jackets'", - "session_id": "b321b404-cbf1-4905-9b0c-b93ad4eedf89", - "gen_no": 1, - "transaction_id": "6874259d-13b1-478c-83cb-b3ed52628850", - "generation_number": 1, - "warning_details": null, - "ambiguous_phrases": null, - "query_intent": null, - "assumptions": "You want to see the total sales amount for jackets item type.", - "tml_phrases": [ - "[sales]", - "[item type] = [item type].'jackets'" - ], - "cached": false, - "sub_queries": null, - "title": "Net sales of Jackets", - "worksheet_id": "cd252e5c-b552-49a8-821d-3eadaa049cca" - }, - "title": "Net sales of Jackets" - } -] ----- - -The session ID and generation number serve as the data context for the Answer. You can use this information to create a new conversation session using `/api/rest/2.0/ai/agent/conversation/create`, or download the answer via the `/api/rest/2.0/report/answer` API endpoint. - - -* The tokens and TML phrases returned in the response can be used as inputs for the search data API call to get an Answer. -//// - -== Send a query to agent and get streaming responses - -To send queries to an ongoing conversation session with Spotter agent and receive streaming responses, use the `/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream` API endpoint. This API endpoint uses the SSE protocol to deliver data incrementally in real time, rather than waiting for the entire response to be generated before sending it to the client. - -The `/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream` API can be used as an integrated tool for real-time streaming of conversational interactions between agents and the ThoughtSpot backend. - -=== Request parameters - -[width="100%" cols="2,4"] -[options='header'] -|===== -|Parameter| Description -|`conversation_identifier` |__String__. Specify the conversation ID received from the xref:spotter-agent-apis.adoc#_create_a_conversation_session_with_spotter_agent[POST /api/rest/2.0/ai/agent/conversation/create] API call. -|`messages`|_Array of strings_. Include at least one natural language query. For example, `Sales data for Jackets`, `Top performing products in the west coast`. -|===== - -=== Example request - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream' \ - -H 'Accept: application/json' \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {AUTH_TOKEN}' \ - --data-raw '{ - "conversation_identifier": "h2I_pTGaRQof", - "messages": [ - "Net sales of Jackets" - ] -}' ----- - -=== API response - -If the API request is successful, the response includes a stream of events, each containing a partial or complete message from the AI agent, rather than a single JSON object. - -Each event is a simple text-based message in a specific format, `data: \n\n`; `\n\n` means that each message sent from the server to the client is prefixed with the `data:` keyword, followed by the actual payload (``), and ends with two newline characters (`\n\n`). - -The API uses this format so that the clients can reconstruct the AI-generated response as it streams in, chunk by chunk, and show the responses in real-time. In agentic workflows, the receiving client or agent listens to the SSE stream, parses each event, and assembles the full response for its users. - -==== Example response -If the request is valid, the API returns SSE streams. Each line has the form `data: [{"type": "...", ...}]`, a JSON array of event objects. - -[source,JSON] ----- -data: [{"type":"ack","node_id":"aGxzcFVrtom8"}] - -data: [{"type":"conv_title","title":"Sales 2025 vs 2024","conv_id":"-XIi04l5rrof"}] - -data: [{"type":"notification","group_id":"cDEsAQbSnd3J","metadata":{"type":"thinking","tool_title":"Analyzing Sales Performance: 2025 vs 2024"},"code":"TOOL_CALL_NOTIFICATION"}] - -data: [{"id":"mNAdvy-NK2l6","type":"text-chunk","group_id":"cDEsAQbSnd3J","metadata":{"format":"markdown","type":"thinking"},"content":"\n\nI need to compare sales performance between 2025 and 2024."}] - -data: [{"type":"notification","group_id":"m1MTvttEUa7o","code":"nls_start"}] - -data: [{"id":"hxWMDP-pgR3B","type":"answer","group_id":"m1MTvttEUa7o","metadata":{"sage_query":"[sales] [date] = '2025' vs [date] = '2024'","session_id":"431adcf9-1328-4d8c-81a1-0faa7fa37ba6","title":"Compare sales for 2025 vs 2024"},"title":"Compare sales for 2025 vs 2024"}] - -data: [{"type":"notification","code":"FINAL_RESPONSE_NOTIFICATION"}] ----- -For the complete response in one payload, use the xref:spotter-agent-apis.adoc#_send_queries_to_a_conversation_session[`/send` endpoint] instead. - -//// -[source,] ----- -data: [{"type": "ack", "node_id": "BRxCtJ-aGt8l"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": "I"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " understand"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " you're"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " interested"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " in"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " the"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " net"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " sales"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " of"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " Jackets"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": "."}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " I'll"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " retrieve"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " the"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " relevant"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " data"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " for"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " you"}] - -data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": "."}] - -data: [{"type": "notification", "group_id": "o8dQ9SAWdtrL", "metadata": {"title": "Net sales of Jackets"}, "code": "nls_start"}] - -data: [{"type": "notification", "group_id": "o8dQ9SAWdtrL", "code": "QH", "message": "Fetching Worksheet Data"}] - -data: [{"type": "notification", "group_id": "o8dQ9SAWdtrL", "code": "TML_GEN", "message": "Translating your query with the Reasoning Engine"}] - -data: [{"type": "notification", "group_id": "o8dQ9SAWdtrL", "code": "ANSWER_GEN", "message": "Verifying results with the Trust Layer"}] - -data: [{"id": "r24X7D99SROD", "type": "answer", "group_id": "o8dQ9SAWdtrL", "metadata": {"sage_query": "[sales] [item type] = [item type].'jackets'", "session_id": "b321b404-cbf1-4905-9b0c-b93ad4eedf89", "gen_no": 1, "transaction_id": "6874259d-13b1-478c-83cb-b3ed52628850", "generation_number": 1, "warning_details": null, "ambiguous_phrases": null, "query_intent": null, "assumptions": "You want to see the total sales amount for jackets item type.", "tml_phrases": ["[sales]", "[item type] = [item type].'jackets'"], "cached": false, "sub_queries": null, "title": "Net sales of Jackets", "worksheet_id": "cd252e5c-b552-49a8-821d-3eadaa049cca"}, "title": "Net sales of Jackets"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "The"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " net"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " sales"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " for"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " Jackets"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " have"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " been"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " visual"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "ized"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " for"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " you"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "."}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " This"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " analysis"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " specifically"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " filtered"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " for"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " the"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " item"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " type"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "jackets"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "\""}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " and"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " calculated"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " the"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " total"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " sales"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " amount"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " associated"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " with"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " those"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " products"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ".\n\n"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "**"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "Summary"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " &"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " Insights"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ":"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "**\n"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "-"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " The"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " visualization"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " shows"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " the"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " total"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " net"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " sales"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " for"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " all"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " jacket"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " transactions"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " in"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " your"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " apparel"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " dataset"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ".\n"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "-"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " The"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " calculation"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " uses"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " only"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " sales"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " amounts"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " where"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " the"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " item"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " type"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " is"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " \""}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "J"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "ackets"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ".\"\n"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "-"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " This"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " information"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " is"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " useful"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " for"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " understanding"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " the"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " revenue"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " contribution"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " of"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " jackets"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " within"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " your"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " product"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " mix"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ".\n\n"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "If"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " you'd"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " like"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " to"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " see"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " a"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " breakdown"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " by"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " region"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ","}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " state"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ","}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " time"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " period"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ","}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " or"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " compare"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " jacket"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " sales"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " to"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " other"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " product"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " types"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ","}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " please"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " let"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " me"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " know"}] - -data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "!"}] ----- -//// - -==== SSE event types -The SSE event types streamed in the API response include: - -* `ack` + -Confirms receipt of the request. For example, the type in the first message `data: [{"type": "ack", "node_id": "BRxCtJ-aGt8l"}]`, which indicates that the server has received the client's request and is acknowledging it. -* `conv_title` + -A conversation title (`title`, `conv_id`). -* `notification` + -Progress or status update (`group_id`, `metadata`, `code`). For example, `TOOL_CALL_NOTIFICATION`, `nls_start`, `FINAL_RESPONSE_NOTIFICATION`. -* `type` + -Type can be `thinking`, `text`. -* `text` + -Complete text block in markdown format. -* `text-chunk` + -Text fragments in incremental streaming, often in markdown (`id`, `group_id`, `metadata` with `format`) -* `content` + -The actual text content sent incrementally. For example, `"I"`, `"understand"`, `"you're"`, `"interested"`, `"in"`, `"the"`, `"net"`, `"sales"`, and so on. -* `text` + -Full text block with same structure as text-chunk. -* `answer` + -Structured answer with metadata (`id`, `group_id`, `metadata` with `sage_query`, `session_id`, `title` and more) -* `error` + -In case of failures. -* `*-interrupt` + -If the generation was stopped mid-stream. -* `group_id` + -Groups related chunks together. - -For more information and examples, see xref:spotter-agent-apis.adoc#_sse_event_payload_reference[SSE event payload reference]. - -=== Thinking versus output events -Spotter responses have two phases: - -* A *thinking phase*, where the AI reasons through the query and calls internal tools, followed by an *output phase* containing the final response delivered to the user. + - -Events in the thinking phase carry `"metadata": { "type": "thinking" }`. All other events are final output. - -Every event includes a `group_id`. Events sharing the same `group_id` belong together. During the thinking phase, each tool call gets its own `group_id`. A `FINAL_RESPONSE_NOTIFICATION` notification marks the boundary between the thinking and output phases. - -[listing] ----- -THINKING PHASE -─────────────────────────────────────────────────────────── -ack - -┌─ group_id: g1 ── Tool Call 1 ("Searching data") ─────────┐ -│ notification (thinking, TOOL_CALL_NOTIFICATION) │ -│ text-chunk (thinking) │ -│ answer (thinking) │ -└──────────────────────────────────────────────────────────┘ - -┌─ group_id: g2 ── Tool Call 2 ("Running code") ───────────┐ -│ notification (thinking, TOOL_CALL_NOTIFICATION) │ -│ text-chunk (thinking) │ -│ text-chunk (thinking) │ -└──────────────────────────────────────────────────────────┘ - -notification (FINAL_RESPONSE_NOTIFICATION) ←── boundary -──────────────────────────────────────────────────────────── - -OUTPUT PHASE -──────────────────────────────────────────────────────────── -┌─ group_id: g3 ────────────────────────────────────────────┐ -│ text "Here are the results:" │ -│ answer (final visualization) │ -└───────────────────────────────────────────────────────────┘ -[stream closes] ----- - -==== Notification codes reference - -[width="100%" cols="2,4"] -[options='header'] -|===== -|Code| When it appears -|`QH`|Query handling started -|`TML_GEN` / `TML_GEN_RETRY`|Generating or retrying TML -|`ANSWER_GEN`|Generating an answer -|`IDENTIFYING_ATTRIBUTES`|Identifying data attributes -|`PERFORMING_CHANGE_ANALYSIS`|Running change analysis -|`PERFORMING_FORECASTING_ANALYSIS`|Running forecasting -|`SUMMARIZING_RESULTS`|Summarizing results -|`TOOL_CALL_NOTIFICATION`|Tool invocation (during thinking phase) -|`FINAL_RESPONSE_NOTIFICATION`|Marks the transition from thinking to output -|`search_datasets_start` / `search_datasets_end`|Data source discovery in progress or complete -|`approval_required`|An external tool requires user permission before proceeding -|===== - -=== SSE event payload reference - -==== ack - -[source,JSON] ----- -data: { - "type": "ack", - "group_id": "a1b2c3", - "id": "evt-001", - "node_id": "resp-node-abc" -} ----- - -==== notification (thinking — tool call) - -[source,JSON] ----- -data: { - "type": "notification", - "group_id": "g1", - "id": "evt-002", - "code": "TOOL_CALL_NOTIFICATION", - "message": "Searching for relevant data", - "metadata": { - "type": "thinking", - "tool_title": "Searching sales data", - "tool_code": "RUNNING_CODE_EXECUTION", - "tool_name": "code_interpreter" - } -} ----- - -==== notification (thinking - external tool with MCP integration) - -[source,JSON] ----- -data: { - "type": "notification", - "group_id": "g2", - "id": "evt-003", - "code": "TOOL_CALL_NOTIFICATION", - "message": "Querying Salesforce", - "metadata": { - "type": "thinking", - "tool_title": "Salesforce: Get Opportunities", - "tool_name": "get_opportunities", - "integration_id": "int-sf-123", - "integration_name": "Salesforce" - } -} ----- - -==== notification (approval required) -Sent when an external MCP tool requires explicit user permission before proceeding. Your application should prompt the user to approve or deny the action before continuing. - -[source,JSON] ----- -data: { - "type": "notification", - "group_id": "g2", - "id": "evt-005", - "code": "approval_required", - "metadata": { - "request_id": "perm-req-789", - "integration_id": "int-sf-123", - "integration_name": "Salesforce", - "tool_name": "get_opportunities", - "annotated_title": "Access Salesforce Opportunities" - } -} ----- - -==== notification (FINAL_RESPONSE_NOTIFICATION) - -[source,JSON] ----- -data: { - "type": "notification", - "group_id": "g1", - "id": "evt-004", - "code": "FINAL_RESPONSE_NOTIFICATION", - "message": "" -} ----- - -==== text - -[source,JSON] ----- -data: { - "type": "text", - "group_id": "g3", - "id": "evt-007", - "content": "Here is the total revenue breakdown by region for Q4 2025:\n\n- **North America:** $4.2M\n- **EMEA:** $2.8M\n- **APAC:** $1.5M" -} ----- - -==== text-chunk -Multiple chunks sharing the same `id` should be appended together to reconstruct the full text item. - -[source,JSON] ----- -data: { "type": "text-chunk", "group_id": "g3", "id": "evt-009", "content": "Based on the analysis, " } -data: { "type": "text-chunk", "group_id": "g3", "id": "evt-009", "content": "revenue grew 12% quarter-over-quarter." } ----- - -==== answer -When an `answer` event is received, the `session_id` and `gen_no` fields are returned. You can export the visualization data using the Export Answer Report API to process the results. This allows users to download the answer as a PDF, PNG, CSV, or XLSX file. - -[source,JSON] ----- -data: { - "type": "answer", - "group_id": "g3", - "id": "evt-010", - "title": "Revenue by Region Q4 2025", - "metadata": { - "session_id": "sess-abc-123", - "gen_no": 1, - "transaction_id": "txn-456", - "worksheet_id": "ws-def-789", - "cached": false, - "is_hidden": false - } -} ----- - -==== search_datasets -Emitted as a start/end pair during Auto mode data source discovery. - - -[source,JSON] ----- -data: { "type": "search_datasets", "group_id": "g0", "id": "evt-012", "code": "search_datasets_start", "metadata": {} } - -data: { - "type": "search_datasets", - "group_id": "g0", - "id": "evt-013", - "code": "search_datasets_end", - "metadata": { - "data_sources": [ - { "worksheet_id": "ws-1", "worksheet_name": "Sales Data", "confidence": "high", "reasoning": "Contains revenue columns" }, - { "worksheet_id": "ws-2", "worksheet_name": "Marketing Data", "confidence": "low", "reasoning": "No revenue columns" } - ], - "auto_selected": { "worksheet_id": "ws-1", "worksheet_name": "Sales Data", "confidence": "high", "reasoning": "Best match" } - } -} ----- -==== file - -[source,JSON] ----- -data: { - "type": "file", - "group_id": "g3", - "id": "evt-014", - "files": [ - { "ts_file_id": "file-abc-001", "display_name": "quarterly_report.csv", "file_type": "csv", "created_at": "2025-11-15T10:30:00Z" }, - { "ts_file_id": "file-abc-002", "display_name": "chart.png", "file_type": "png", "created_at": "2025-11-15T10:30:01Z" } - ], - "metadata": { "conv_id": "conv-123" } -} ----- -==== conv_title - -[source,JSON] ----- -data: { - "type": "conv_title", - "group_id": "g0", - "id": "evt-015", - "title": "Revenue Analysis Q4 2025", - "conv_id": "conv-123" -} ----- - -==== error - -[source,JSON] ----- -data: { - "type": "error", - "group_id": "g3", - "id": "evt-016", - "code": "RATE_LIMIT_EXCEEDED", - "message": "Too many requests", - "display_message": "You've exceeded the rate limit. Please try again in a few minutes." -} ----- -==== agent-interrupt - -[source,JSON] ----- -Sent when generation is stopped mid-stream. -data: { - "type": "notification", - "group_id": "g3", - "id": "evt-017", - "code": "agent-interrupt", - "message": "Generation stopped" -} ----- - -[#_stop_an_in_progress_agent_response] -== Stop an in-progress agent response - -The `/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response` API endpoint stops a Spotter agent response that is currently in progress for a given conversation session. - -Use this endpoint when you want to cancel a long-running Spotter response before it completes. The conversation session remains active after you stop a response, so you can send a new query to the same session immediately. - -=== Request parameters - -[width="100%", cols="2,2,4"] -[options='header'] -|===== -|Parameter|Type| Description -|`conversation_identifier`|Path parameter|__String__. Required. The identifier of the active conversation session. Use the value returned by the xref:spotter-agent-apis.adoc#_create_a_conversation_session_with_spotter_agent[create conversation] API endpoint. -|===== - -This endpoint does not require a request body. - -=== Example request - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response' \ - -H 'Accept: application/json' \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {AUTH_TOKEN}' ----- - -=== Example response - -If the API request is successful, ThoughtSpot stops the in-progress response and returns a 204 response code. - -If the conversation session is not found or has expired, the API returns an error: - -[source,JSON] ----- -{ - "error_code": "CONVERSATION_NOT_FOUND", - "message": "The specified conversation session does not exist or has expired." -} ----- - -[#process_results] -== Process results generated from a conversation session -To export or download the Answer data generated by the Spotter APIs, use the xref:data-report-v2-api.adoc#exportSpotterData[Answer report] API. - -The `session_id` and `gen_no` values from the `answer` event metadata are required to identify the answer to export. - -NOTE: Requires at least view access to the Answer. - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \ - -H 'Authorization: Bearer {Bearer_token}' \ - -H 'Accept: application/octet-stream' \ - -H 'Content-Type: application/json' \ - --data-raw '{ - "session_identifier": "sess-abc-123", - "generation_number": 1, - "file_format": "CSV" -}' ----- -The `file_format` parameter accepts `PDF`, `PNG`, `CSV`, or `XLSX`. - -[NOTE] -==== -Using tokens generated by the Spotter API in a xref:data-report-v2-api.adoc#_search_data_api[Search Data API] request can return invalid column errors, because these tokens may reference formulas or columns not present in the data model. Instead, use the xref:data-report-v2-api.adoc#exportSpotterData[Answer report] API and include the session ID and generation number obtained from the Spotter API in your API request to retrieve the data. -==== - - -== Data literacy and query assistance -The query assistance APIs help users find the appropriate dataset for a given query string, suggest what questions can be asked, and return example questions. These APIs are specifically designed to improve data literacy for users who may not be familiar with the underlying data, making it easier for them to explore and analyze data effectively. - -=== Get data source suggestions - -The `POST /api/rest/2.0/ai/data-source-suggestions` API provides relevant data source recommendations for a user-submitted natural language query. To use this API, you must have at least view access to the underlying metadata object referenced in the response. - -==== Request parameters - -[width="100%" cols="2,4"] -[options='header'] -|==== -|Parameter| Description -|`metadata_context` a| Required. Specify one of the following attributes to set the metadata context: - -* `data_source_identifiers` + -__Array of strings__. IDs of the data source object such as Models. -* `answer_identifiers` + -__Array of strings__. GUIDs of the Answer objects that you want to use as metadata. -* `conversation_identifier` + -__String__. ID of the conversation session. -* `liveboard_identifiers` + -__Array of strings__. GUIDs of the Liveboards that you want to use as metadata. - -| `query` |__String__. Required parameter. Specify the query string that needs to be decomposed into smaller, analytical sub-questions. -|`limit_relevant_questions` + -__Optional__ | __Integer__. Sets a limit on the number of sub-questions to return in the response. Default is 5. -|`bypass_cache` + -__Optional__| __Boolean__. When set to `true`, disables cache and forces fresh computation. -|`ai_context` + -__Optional__. a| Additional context to guide the response. Define the following attributes as needed: -|==== - -==== Example request - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/data-source-suggestions' \ - -H 'Accept: application/json' \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {AUTH_TOKEN}' \ - --data-raw '{ - "metadata_context": { - "data_source_identifiers": [ - "cd252e5c-b552-49a8-821d-3eadaa049cca" - ] - }, - "query": "Net sales of Jackets in west coast", - "limit_relevant_questions": 3 -}' ----- - -==== API response -If the API request is successful, ThoughtSpot returns a ranked list of data sources, each annotated with relevant reasoning. - -[source,JSON] ----- -{ - "relevant_questions": [ - { - "query": "What is the trend of sales by type over time?", - "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", - "data_source_name": "(Sample) Retail - Apparel" - }, - { - "query": "Sales by item", - "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", - "data_source_name": "(Sample) Retail - Apparel" - }, - { - "query": "Sales across regions", - "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", - "data_source_name": "(Sample) Retail - Apparel" - } - ] -} ----- - -The returned results include metadata such as: - -* `confidence` + -A float indicating the Model's confidence in the relevance of each recommendation. -* `details` + -The data source ID, name, and description for each recommended data source. -* `reasoning` + -Reason provided by the LLM to explain why each data source was recommended. - -=== Get relevant questions - -The `/api/rest/2.0/ai/relevant-questions/` API endpoint breaks down a user-submitted query into relevant sub-questions. It accepts the original query and optional additional context, then generates a set of related questions to help users explore their data comprehensively. - -During agentic interactions, this API can be used as an integrated tool to decompose user queries and suggest relevant questions for a specific data context. REST clients can also call this API directly to fetch relevant questions via a `POST` request. - -==== Request parameters - -[width="100%" cols="2,4"] -[options='header'] -|===== -|Parameter| Description -|`metadata_context` a| Required. Specify one of the following attributes to set the metadata context: - -* `data_source_identifiers` + -__Array of strings__. IDs of the data source object such as Models. -* `answer_identifiers` + -__Array of strings__. GUIDs of the Answer objects that you want to use as metadata. -* `conversation_identifier` + -__String__. ID of the conversation session. -* `liveboard_identifiers` + -__Array of strings__. GUIDs of the Liveboards that you want to use as metadata. - -| `query` |__String__. Required parameter. Specify the query string that needs to be decomposed into smaller, analytical sub-questions. -|`limit_relevant_questions` + -__Optional__ | __Integer__. Sets a limit on the number of sub-questions to return in the response. Default is 5. -|`bypass_cache` + -__Optional__| __Boolean__. When set to `true`, disables cache and forces fresh computation. -|`ai_context` + -__Optional__. a| Additional context to guide the response. Define the following attributes as needed: - -* `instructions` + -__Array of strings__. Custom user instructions to influence how the AI interprets and processes the query. -* `content` + -__Array of strings__. Additional input such as raw text or CSV-formatted data to enhance context and answer quality. -|===== - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/relevant-questions/' \ - -H 'Accept: application/json' \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {AUTH_TOKEN}' \ - --data-raw '{ - "metadata_context": { - "data_source_identifiers": [ - "cd252e5c-b552-49a8-821d-3eadaa049cca" - ] - }, - "query": "Net sales of Jackets in west coast", - "limit_relevant_questions": 3 -}' ----- - -==== Example response -If the request is successful, the API returns a set of questions related to the query and metadata context in the `relevant_questions` array. Each object in the `relevant_questions` array contains the following fields: - -* `query` + -A string containing the natural language (NL) sub-question. -* `data_source_identifier` + -GUID of the data source object. -* `data_source_name` + -Name of the associated data source object. - -[source,JSON] ----- -{ - "relevant_questions": [ - { - "query": "What is the trend of sales by type over time?", - "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", - "data_source_name": "(Sample) Retail - Apparel" - }, - { - "query": "Sales by item", - "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", - "data_source_name": "(Sample) Retail - Apparel" - }, - { - "query": "Sales across regions", - "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", - "data_source_name": "(Sample) Retail - Apparel" - } - ] -} ----- - == Additional resources +* xref:spotter-agent-conversation-apis.adoc[Spotter agent conversation APIs] + +Create conversation sessions, send synchronous queries, and stop in-progress responses. +* xref:spotter-agent-streaming-apis.adoc[Spotter agent streaming APIs] + +Send queries and receive real-time Server-Sent Events (SSE) responses from the Spotter agent. +* xref:spotter-agent-process-results-apis.adoc[Process Spotter agent conversation results] + +Export or download Answers generated by a Spotter agent conversation session. +* xref:spotter-agent-data-literacy-apis.adoc[Spotter agent data literacy APIs] + +Get data source suggestions and decompose a user query into relevant sub-questions. +* xref:spotter-agent-sharing-apis.adoc[Spotter agent conversation sharing APIs] + +Share saved Spotter conversations with other users and groups. +* xref:spotter-agent-conversation-mgmt-apis.adoc[APIs for managing saved conversations] + +Retrieve, update, and delete saved Spotter 3 conversations and their messages. * Visit the +++REST API v2.0 Playground+++ to view the API endpoints and verify the request and response workflows. * For information about MCP tools, see xref:mcp-integration.adoc[MCP server integration]. diff --git a/modules/ROOT/pages/spotter-agent-conversation-apis.adoc b/modules/ROOT/pages/spotter-agent-conversation-apis.adoc new file mode 100644 index 000000000..1e094a6aa --- /dev/null +++ b/modules/ROOT/pages/spotter-agent-conversation-apis.adoc @@ -0,0 +1,385 @@ += Spotter agent conversation APIs +:toc: true +:toclevels: 2 + +:page-title: Spotter agent conversation APIs +:page-pageid: spotter-agent-conversation-apis +:page-description: Use the Spotter agent conversation REST APIs to create conversation sessions, send natural language queries, and stop in-progress responses. + +ThoughtSpot's Spotter agent conversation APIs allow you to create a conversation session with the Spotter agent, send natural language queries to it, and stop an in-progress response. + +For information about receiving responses as a real-time event stream, see xref:spotter-agent-streaming-apis.adoc[Spotter agent streaming APIs]. For information about exporting Answers generated by a conversation, see xref:spotter-agent-process-results-apis.adoc[Process Spotter agent conversation results]. For information about the data source and question suggestion APIs, see xref:spotter-agent-data-literacy-apis.adoc[Spotter agent data literacy APIs]. For information about sharing saved conversations, see xref:spotter-agent-sharing-apis.adoc[Spotter agent conversation sharing APIs]. + +== Create a conversation session with Spotter Agent + +The `/api/rest/2.0/ai/agent/conversation/create` API endpoint creates a new conversation session with Spotter Agent for a specific or multi-data context and returns a conversation ID. + +=== Request parameters +The request body must include the `metadata_context`. REST API clients must have at least view access to the data source objects specified in the API request to create a conversation session and use it for subsequent queries. + +[width="100%" cols="2,4"] +[options='header'] +|===== +|Form parameter| Description +|`metadata_context` a| Defines the data context for the conversation. + +* `type` + +Metadata context type. The context type is mandatory. Select one of the following values: + +** `AUTO_MODE` to allow Spotter Agent to automatically discover and select the most relevant datasets for users' queries. +** `DATA_SOURCE` to set a specific data source as the data context. You must specify `data_source_context` and data source IDs. + +To set a specific data source object, use `data_source_identifier`. + +To set multi-data context, use `data_source_identifiers`. +** `data_source` [.version-badge.deprecated]#Deprecated# + +This option is deprecated in 26.5.0.cl. ThoughtSpot recommends using the `DATA_SOURCE` with `data_source_context` and data source IDs instead. + +|`conversation_settings` a|__Optional__. Defines additional parameters for the conversation context. You can set any of the following attributes as needed: + +* `enable_contextual_change_analysis` + +__Boolean__. When enabled, Spotter analyzes how context changes over time, that is, comparing results from different queries. Enabled by default in 26.2.0.cl and later versions. +* `enable_natural_language_answer_generation` + +__Boolean__. Allows sending natural language queries to the conversation session. Enabled by default in 26.2.0.cl and later versions. +* `enable_reasoning` + +__Boolean__. Allows Spotter to use reasoning for deep analysis and precise responses. Enabled by default in 26.2.0.cl and later versions. +* `enable_save_chat` + +When set to `true`, adds the conversation to chat history. +|===== + +=== Example request + +With AUTO_MODE for metadata context:: + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/create' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "metadata_context": { + "type": "AUTO_MODE" + }, + "conversation_settings": { + "enable_save_chat": true + } +}' +---- + +For a single data source as the data context:: + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/create' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "metadata_context": { + "type": "DATA_SOURCE", + "data_source_context": { + "data_source_identifier": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + } + }, + "conversation_settings": {} +}' +---- + +For multi-data source context:: + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/create' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "metadata_context": { + "type": "DATA_SOURCE", + "data_source_context": { + "data_source_identifiers": [ + "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "b2c3d4e5-f6a7-8901-bcde-f12345678901" + ] + } + }, + "conversation_settings": { + "enable_save_chat": true + } +}' +---- + +=== API response + +If the API request is successful, the API returns the conversation ID and identifier in the response body. + +[source,JSON] +---- +{ + "conversation_id": "wwHQ5j8O8dQC", + "conversation_identifier": "wwHQ5j8O8dQC" +} +---- + +* `conversation_identifier` + +Use this for all subsequent message calls. +* `conversation_id` [.version-badge.deprecated]#Deprecated# + +Returns the same value as `conversation_identifier`. + +== Send queries to a conversation session + +To send queries to an ongoing conversation session with the Spotter agent and receive a response synchronously, use the `/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send` API endpoint. + +This API operation requires the conversation ID obtained from the conversation creation API endpoint (`/api/rest/2.0/ai/agent/conversation/create`). The user making the API request must have access to the conversation session. The API request body must include at least one message in natural language format. + +=== Request parameters + +[width="100%" cols="2,2,4"] +[options='header'] +|===== +|Parameter|Type| Description +|`conversation_identifier`|Path parameter|__String__. Required. Specify the conversation ID received from the xref:spotter-agent-conversation-apis.adoc#_create_a_conversation_session_with_spotter_agent[POST /api/rest/2.0/ai/agent/conversation/create] API call. +|`messages`|Form parameter|_Array of strings_. Required. Specify at least one query in natural language. For example, `total sales of jackets last month`. +|===== + + +//// +|`settings` |__Optional__. Defines additional parameters for the conversation context. You can set any of the following attributes as needed: + +* `enable_contextual_change_analysis` + +__Boolean__. When enabled, Spotter analyzes how the context changes over time, that is comparing results from different queries. +* `enable_natural_language_answer_generation` + +__Boolean__. Allows sending natural language queries to the conversation session. +* `enable_reasoning` + +__Boolean__. Allows Spotter to use reasoning for deep analysis and precise responses. +//// + +=== Request and response examples + +The following example sends a data comparison query to a conversation session. The conversation ID is specified in the request URL as a path parameter. + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "messages": [ + "Sales in 2025 vs 2024" + ] +}' +---- + +If the request is successful, the API returns an array of objects in the response. The messages in the API response include the following parts: + +[source,JSON] +---- +[ + { + "type": "text", + "text": "\n\nI'll compare sales between 2025 and 2024. First, let me get the dataset context.", + "metadata": {}, + "internal": {}, + "agent_context": "" + }, + { + "type": "text", + "text": "```json\n{\"dataset_name\":\"(Sample) Retail - Apparel\",\"columns\":[{\"name\":\"sales\",\"type\":\"MEASURE\"},{\"name\":\"date\",\"type\":\"ATTRIBUTE\"}]}\n```", + "metadata": {}, + "internal": {}, + "agent_context": "" + }, + { + "type": "answer", + "title": "Compare total sales for 2025 vs 2024", + "description": "", + "session_id": "842bb67a-e08e-4861-97e8-8db9538db51d", + "gen_no": 2, + "sage_query": "[sales] [date] = '2025' vs [date] = '2024'", + "tml_tokens": ["[sales]", "[date] = '2025' vs [date] = '2024'"], + "formulas": [], + "parameters": [], + "subqueries": [], + "viz_suggestion": "CAEQIBomEiQ2NjE5NzI0Yy1kMjVlLTU4MDItOWNjOC1jNDA3MWY3OWY5MzAoATIA", + "metadata": { + "output": "", + "worksheet_id": "cd252e5c-b552-49a8-821d-3eadaa049cca", + "chart_type": "KPI", + "interrupted": false, + "data_awareness_enabled": true + }, + "internal": {} + }, + { + "type": "text", + "text": "\n\nThe visualization shows year-over-year comparison. You can identify growth or decline trends.", + "metadata": {}, + "internal": {}, + "agent_context": "" + } +] +---- + +The following example sends a follow-up question to the same conversation session. + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "messages": [ + "Now break that down by product category" + ] +}' +---- + +If the request is successful, the agent returns the response for the follow-up question: + +[source,JSON] +---- +[{ + "type": "text", + "text": "I'll add product category to the comparison.", + "metadata": {}, + "internal": {}, + "agent_context": "" + }, + { + "type": "answer", + "title": "Sales by Product Category: 2025 vs 2024", + "session_id": "9abc1234-0000-0000-0000-000000000005", + "gen_no": 3, + "sage_query": "[sales] [product category] [date] = '2025' vs [date] = '2024'", + "tml_tokens": ["[sales]", "[product category]", "[date] = '2025' vs [date] = '2024'"], + "formulas": [], + "parameters": [], + "subqueries": [], + "viz_suggestion": "", + "metadata": { + "chart_type": "BAR", + "worksheet_id": "cd252e5c-b552-49a8-821d-3eadaa049cca" + }, + "internal": {} + }] +---- + +In each response, the agent returns the following information: + +* `type` + +Type of the message, such as text, answer, or error. +* `text` + +Response message generated for the query. +* `metadata` + +Additional information based on the message type. For example, answer metadata, chart type, or the data source ID. +* `tml_tokens` + +Query string broken down as TML tokens. + +In case of errors, the response returns the error details: + +[source,JSON] +---- +[{ + "type": "error", + "message": "The conversation session has expired. Please create a new conversation.", + "code": "SESSION_EXPIRED" +}] +---- + + + +//// +The following example shows the response text contents for the `answer` message type. + +[source,JSON] +---- +[ + { + "id": "r24X7D99SROD", + "type": "answer", + "group_id": "o8dQ9SAWdtrL", + "metadata": { + "sage_query": "[sales] [item type] = [item type].'jackets'", + "session_id": "b321b404-cbf1-4905-9b0c-b93ad4eedf89", + "gen_no": 1, + "transaction_id": "6874259d-13b1-478c-83cb-b3ed52628850", + "generation_number": 1, + "warning_details": null, + "ambiguous_phrases": null, + "query_intent": null, + "assumptions": "You want to see the total sales amount for jackets item type.", + "tml_phrases": [ + "[sales]", + "[item type] = [item type].'jackets'" + ], + "cached": false, + "sub_queries": null, + "title": "Net sales of Jackets", + "worksheet_id": "cd252e5c-b552-49a8-821d-3eadaa049cca" + }, + "title": "Net sales of Jackets" + } +] +---- + +The session ID and generation number serve as the data context for the Answer. You can use this information to create a new conversation session using `/api/rest/2.0/ai/agent/conversation/create`, or download the answer via the `/api/rest/2.0/report/answer` API endpoint. + + +* The tokens and TML phrases returned in the response can be used as inputs for the search data API call to get an Answer. +//// + +[#_stop_an_in_progress_agent_response] +== Stop an in-progress agent response + +The `/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response` API endpoint stops a Spotter agent response that is currently in progress for a given conversation session. + +Use this endpoint when you want to cancel a long-running Spotter response before it completes. The conversation session remains active after you stop a response, so you can send a new query to the same session immediately. + +=== Request parameters + +[width="100%", cols="2,2,4"] +[options='header'] +|===== +|Parameter|Type| Description +|`conversation_identifier`|Path parameter|__String__. Required. The identifier of the active conversation session. Use the value returned by the xref:spotter-agent-conversation-apis.adoc#_create_a_conversation_session_with_spotter_agent[create conversation] API endpoint. +|===== + +This endpoint does not require a request body. + +=== Example request + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' +---- + +=== Example response + +If the API request is successful, ThoughtSpot stops the in-progress response and returns a 204 response code. + +If the conversation session is not found or has expired, the API returns an error: + +[source,JSON] +---- +{ + "error_code": "CONVERSATION_NOT_FOUND", + "message": "The specified conversation session does not exist or has expired." +} +---- + +== Additional resources + +* See also xref:spotter-agent-apis.adoc[Spotter Agent APIs] +* xref:spotter-agent-streaming-apis.adoc[Spotter agent streaming APIs] +* xref:spotter-agent-process-results-apis.adoc[Process Spotter agent conversation results] +* xref:spotter-agent-data-literacy-apis.adoc[Spotter agent data literacy APIs] +* xref:spotter-agent-sharing-apis.adoc[Spotter agent conversation sharing APIs] +* Visit the +++REST API v2.0 Playground+++ to view the API endpoints and verify the request and response workflows. diff --git a/modules/ROOT/pages/spotter-agent-conversation-mgmt-apis.adoc b/modules/ROOT/pages/spotter-agent-conversation-mgmt-apis.adoc index 371233233..b8b4a1dda 100644 --- a/modules/ROOT/pages/spotter-agent-conversation-mgmt-apis.adoc +++ b/modules/ROOT/pages/spotter-agent-conversation-mgmt-apis.adoc @@ -42,7 +42,7 @@ __Available on ThoughtSpot Cloud instances from 26.7.0.cl onwards.__ |===== == Saving a conversation -To save a conversation, set the `enable_save_chat` parameter to `true` when sending a xref:spotter-agent-apis.adoc#_create_a_conversation_session_with_spotter_agent[conversation create `POST` request] to the `/api/rest/2.0/ai/agent/conversation/create` API endpoint. +To save a conversation, set the `enable_save_chat` parameter to `true` when sending a xref:spotter-agent-conversation-apis.adoc#_create_a_conversation_session_with_spotter_agent[conversation create `POST` request] to the `/api/rest/2.0/ai/agent/conversation/create` API endpoint. === API request example @@ -308,7 +308,7 @@ Each item in `conversations` represents a saved conversation. [options="header"] |===== |Field|Description -|`conversation_identifier`|__String__. Unique identifier of the conversation. Use this value as input in your API requests to the xref:spotter-agent-apis.adoc#_send_queries_to_a_conversation_session[send message], xref:spotter-agent-conversation-mgmt-apis.adoc#update-conversation[update conversation], xref:spotter-agent-conversation-mgmt-apis.adoc#delete-conversation[delete conversation], xref:spotter-agent-apis.adoc#_stop_an_in_progress_agent_response[stop response], and xref:spotter-agent-conversation-mgmt-apis.adoc#load-answer[load answer] endpoints. +|`conversation_identifier`|__String__. Unique identifier of the conversation. Use this value as input in your API requests to the xref:spotter-agent-conversation-apis.adoc#_send_queries_to_a_conversation_session[send message], xref:spotter-agent-conversation-mgmt-apis.adoc#update-conversation[update conversation], xref:spotter-agent-conversation-mgmt-apis.adoc#delete-conversation[delete conversation], xref:spotter-agent-conversation-apis.adoc#_stop_an_in_progress_agent_response[stop response], and xref:spotter-agent-conversation-mgmt-apis.adoc#load-answer[load answer] endpoints. |`conversation_title` a|__String__. Display name of the conversation. |`created_at`|__String__. Timestamp of when the conversation was created. |`updated_at`|__String__. Timestamp of when the conversation was last updated. diff --git a/modules/ROOT/pages/spotter-agent-data-literacy-apis.adoc b/modules/ROOT/pages/spotter-agent-data-literacy-apis.adoc new file mode 100644 index 000000000..85ab15a91 --- /dev/null +++ b/modules/ROOT/pages/spotter-agent-data-literacy-apis.adoc @@ -0,0 +1,190 @@ += Spotter agent data literacy APIs +:toc: true +:toclevels: 2 + +:page-title: Spotter agent data literacy APIs +:page-pageid: spotter-agent-data-literacy-apis +:page-description: Use the Spotter data literacy REST APIs to get relevant data source suggestions and decompose a user query into relevant sub-questions. + +The query assistance APIs help users find the appropriate dataset for a given query string, suggest what questions can be asked, and return example questions. These APIs are specifically designed to improve data literacy for users who may not be familiar with the underlying data, making it easier for them to explore and analyze data effectively. + +For information about creating a conversation session, see xref:spotter-agent-conversation-apis.adoc[Spotter agent conversation APIs]. + +== Get data source suggestions + +The `POST /api/rest/2.0/ai/data-source-suggestions` API provides relevant data source recommendations for a user-submitted natural language query. To use this API, you must have at least view access to the underlying metadata object referenced in the response. + +=== Request parameters + +[width="100%" cols="2,4"] +[options='header'] +|==== +|Parameter| Description +|`metadata_context` a| Required. Specify one of the following attributes to set the metadata context: + +* `data_source_identifiers` + +__Array of strings__. IDs of the data source object such as Models. +* `answer_identifiers` + +__Array of strings__. GUIDs of the Answer objects that you want to use as metadata. +* `conversation_identifier` + +__String__. ID of the conversation session. +* `liveboard_identifiers` + +__Array of strings__. GUIDs of the Liveboards that you want to use as metadata. + +| `query` |__String__. Required parameter. Specify the query string that needs to be decomposed into smaller, analytical sub-questions. +|`limit_relevant_questions` + +__Optional__ | __Integer__. Sets a limit on the number of sub-questions to return in the response. Default is 5. +|`bypass_cache` + +__Optional__| __Boolean__. When set to `true`, disables cache and forces fresh computation. +|`ai_context` + +__Optional__. a| Additional context to guide the response. Define the following attributes as needed: +|==== + +=== Example request + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/data-source-suggestions' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "metadata_context": { + "data_source_identifiers": [ + "cd252e5c-b552-49a8-821d-3eadaa049cca" + ] + }, + "query": "Net sales of Jackets in west coast", + "limit_relevant_questions": 3 +}' +---- + +=== API response +If the API request is successful, ThoughtSpot returns a ranked list of data sources, each annotated with relevant reasoning. + +[source,JSON] +---- +{ + "relevant_questions": [ + { + "query": "What is the trend of sales by type over time?", + "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", + "data_source_name": "(Sample) Retail - Apparel" + }, + { + "query": "Sales by item", + "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", + "data_source_name": "(Sample) Retail - Apparel" + }, + { + "query": "Sales across regions", + "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", + "data_source_name": "(Sample) Retail - Apparel" + } + ] +} +---- + +The returned results include metadata such as: + +* `confidence` + +A float indicating the Model's confidence in the relevance of each recommendation. +* `details` + +The data source ID, name, and description for each recommended data source. +* `reasoning` + +Reason provided by the LLM to explain why each data source was recommended. + +== Get relevant questions + +The `/api/rest/2.0/ai/relevant-questions/` API endpoint breaks down a user-submitted query into relevant sub-questions. It accepts the original query and optional additional context, then generates a set of related questions to help users explore their data comprehensively. + +During agentic interactions, this API can be used as an integrated tool to decompose user queries and suggest relevant questions for a specific data context. REST clients can also call this API directly to fetch relevant questions via a `POST` request. + +=== Request parameters + +[width="100%" cols="2,4"] +[options='header'] +|===== +|Parameter| Description +|`metadata_context` a| Required. Specify one of the following attributes to set the metadata context: + +* `data_source_identifiers` + +__Array of strings__. IDs of the data source object such as Models. +* `answer_identifiers` + +__Array of strings__. GUIDs of the Answer objects that you want to use as metadata. +* `conversation_identifier` + +__String__. ID of the conversation session. +* `liveboard_identifiers` + +__Array of strings__. GUIDs of the Liveboards that you want to use as metadata. + +| `query` |__String__. Required parameter. Specify the query string that needs to be decomposed into smaller, analytical sub-questions. +|`limit_relevant_questions` + +__Optional__ | __Integer__. Sets a limit on the number of sub-questions to return in the response. Default is 5. +|`bypass_cache` + +__Optional__| __Boolean__. When set to `true`, disables cache and forces fresh computation. +|`ai_context` + +__Optional__. a| Additional context to guide the response. Define the following attributes as needed: + +* `instructions` + +__Array of strings__. Custom user instructions to influence how the AI interprets and processes the query. +* `content` + +__Array of strings__. Additional input such as raw text or CSV-formatted data to enhance context and answer quality. +|===== + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/relevant-questions/' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "metadata_context": { + "data_source_identifiers": [ + "cd252e5c-b552-49a8-821d-3eadaa049cca" + ] + }, + "query": "Net sales of Jackets in west coast", + "limit_relevant_questions": 3 +}' +---- + +=== Example response +If the request is successful, the API returns a set of questions related to the query and metadata context in the `relevant_questions` array. Each object in the `relevant_questions` array contains the following fields: + +* `query` + +A string containing the natural language (NL) sub-question. +* `data_source_identifier` + +GUID of the data source object. +* `data_source_name` + +Name of the associated data source object. + +[source,JSON] +---- +{ + "relevant_questions": [ + { + "query": "What is the trend of sales by type over time?", + "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", + "data_source_name": "(Sample) Retail - Apparel" + }, + { + "query": "Sales by item", + "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", + "data_source_name": "(Sample) Retail - Apparel" + }, + { + "query": "Sales across regions", + "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", + "data_source_name": "(Sample) Retail - Apparel" + } + ] +} +---- + +== Additional resources + +* See also xref:spotter-agent-apis.adoc[Spotter Agent APIs] +* xref:spotter-agent-conversation-apis.adoc[Spotter agent conversation APIs] +* xref:spotter-agent-process-results-apis.adoc[Process Spotter agent conversation results] diff --git a/modules/ROOT/pages/spotter-agent-process-results-apis.adoc b/modules/ROOT/pages/spotter-agent-process-results-apis.adoc new file mode 100644 index 000000000..751e578df --- /dev/null +++ b/modules/ROOT/pages/spotter-agent-process-results-apis.adoc @@ -0,0 +1,46 @@ += Process Spotter agent conversation results +:toc: true +:toclevels: 2 + +:page-title: Process Spotter agent conversation results +:page-pageid: spotter-agent-process-results-apis +:page-description: Export or download the Answer data generated by a Spotter agent conversation session using the Answer report API. + +After the Spotter agent generates an Answer in a conversation session, use the Answer report API to export or download that Answer. + +For information about sending queries to a conversation session, see xref:spotter-agent-conversation-apis.adoc[Spotter agent conversation APIs]. For information about the streaming response format, see xref:spotter-agent-streaming-apis.adoc[Spotter agent streaming APIs]. + +[#process_results] +== Process results generated from a conversation session +To export or download the Answer data generated by the Spotter APIs, use the xref:data-report-v2-api.adoc#exportSpotterData[Answer report] API. + +The `session_id` and `gen_no` values from the `answer` event metadata are required to identify the answer to export. + +NOTE: Requires at least view access to the Answer. + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \ + -H 'Authorization: Bearer {Bearer_token}' \ + -H 'Accept: application/octet-stream' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "session_identifier": "sess-abc-123", + "generation_number": 1, + "file_format": "CSV" +}' +---- +The `file_format` parameter accepts `PDF`, `PNG`, `CSV`, or `XLSX`. + +[NOTE] +==== +Using tokens generated by the Spotter API in a xref:data-report-v2-api.adoc#_search_data_api[Search Data API] request can return invalid column errors, because these tokens may reference formulas or columns not present in the data model. Instead, use the xref:data-report-v2-api.adoc#exportSpotterData[Answer report] API and include the session ID and generation number obtained from the Spotter API in your API request to retrieve the data. +==== + +== Additional resources + +* See also xref:spotter-agent-apis.adoc[Spotter Agent APIs] +* xref:spotter-agent-conversation-apis.adoc[Spotter agent conversation APIs] +* xref:spotter-agent-streaming-apis.adoc[Spotter agent streaming APIs] +* xref:spotter-agent-data-literacy-apis.adoc[Spotter agent data literacy APIs] diff --git a/modules/ROOT/pages/spotter-agent-sharing-apis.adoc b/modules/ROOT/pages/spotter-agent-sharing-apis.adoc new file mode 100644 index 000000000..3b80474b6 --- /dev/null +++ b/modules/ROOT/pages/spotter-agent-sharing-apis.adoc @@ -0,0 +1,155 @@ += Spotter agent conversation sharing APIs +:toc: true +:toclevels: 3 + +:page-title: Spotter agent conversation sharing APIs +:page-pageid: spotter-agent-sharing-apis +:page-description: Use the Spotter agent conversation sharing REST API v2.0 endpoints to share saved Spotter agent conversations with other users or groups. + +// SOURCE: SCAL-306173 (aug.26.mt) +// SOURCE: prism/src/public-apis/nl-to-answer.graphql (master) + +ThoughtSpot provides REST API v2.0 endpoints to share saved Spotter agent conversations with other users or groups. Shared conversations are always `READ_ONLY` — recipients can view conversation messages and associated answers but cannot send new queries or modify the conversation. + +For information about creating and saving a conversation, see xref:spotter-agent-conversation-apis.adoc[Spotter agent conversation APIs] and xref:spotter-agent-conversation-mgmt-apis.adoc[APIs for managing saved conversations]. + +== Supported endpoints + +[width="100%" cols="1"] +|===== +a| `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` [.version-badge.new]#New# + +xref:spotter-agent-sharing-apis.adoc#_share_a_conversation[Shares a saved Spotter conversation] with one or more users or groups. + +__Available on ThoughtSpot Cloud instances from 26.9.0.cl onwards.__ + +a| `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content` [.version-badge.new]#New# + +xref:spotter-agent-sharing-apis.adoc#_get_shared_content[Returns the shared content] of a Spotter conversation, including messages and associated answers. + +__Available on ThoughtSpot Cloud instances from 26.9.0.cl onwards.__ + +a| `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info` [.version-badge.new]#New# + +xref:spotter-agent-sharing-apis.adoc#_get_share_information[Returns sharing metadata] for a Spotter conversation — the list of principals it is shared with. + +__Available on ThoughtSpot Cloud instances from 26.9.0.cl onwards.__ +|===== + +[#_share_a_conversation] +== Share a conversation + +Use `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` to share a saved Spotter conversation with one or more principals. + +=== Path parameters + +[width="100%" cols="2,4"] +[options="header"] +|===== +| Parameter | Description +| `conversation_identifier` | The GUID of the saved Spotter conversation to share. +|===== + +=== Request body parameters + +[width="100%" cols="2,1,4"] +[options="header"] +|===== +| Parameter | Required | Description +| `grant` | No | Array of principal identifiers to grant access. Each entry is a `user_identifier` (username or GUID) or `group_identifier` (group name or GUID). All shared access is `READ_ONLY`. +| `revoke` | No | Array of principal identifiers to revoke access from. +| `refresh_shared_content` | No | Boolean. When `true`, regenerates the shared content snapshot. Default: `false`. +| `notify_on_share` | No | Boolean. When `true`, sends an in-app notification to principals receiving access. Default: `true`. Available from 26.10.0.cl. +|===== + +=== Example request + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "grant": [ + {"user_identifier": "user@example.com"}, + {"group_identifier": "analysts-group"} + ], + "revoke": [], + "refresh_shared_content": false +}' +---- + +[#_get_shared_content] +== Get shared content + +Use `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content` to retrieve the content of a shared Spotter conversation. + +=== Path parameters + +[width="100%" cols="2,4"] +[options="header"] +|===== +| Parameter | Description +| `conversation_identifier` | The GUID of the shared Spotter conversation. +|===== + +=== Response fields + +[width="100%" cols="2,4"] +[options="header"] +|===== +| Field | Description +| `conversation_id` | GUID of the original conversation. +| `shared_conversation_id` | GUID of the shared conversation snapshot. +| `messages` | Array of conversation messages included in the shared snapshot. +| `data_sources` | Array of data source identifiers used in the conversation. +| `code_execution_files` | Array of files generated by code execution steps, if any. +|===== + +=== Example request + +[source,cURL] +---- +curl -X GET \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/json' +---- + +[#_get_share_information] +== Get share information + +Use `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info` to retrieve sharing metadata for a Spotter conversation. + +=== Path parameters + +[width="100%" cols="2,4"] +[options="header"] +|===== +| Parameter | Description +| `conversation_identifier` | The GUID of the Spotter conversation. +|===== + +=== Response fields + +[width="100%" cols="2,4"] +[options="header"] +|===== +| Field | Description +| `is_shared_content_outdated` | Boolean. `true` if the shared content snapshot is stale. Use the share endpoint with `refresh_shared_content: true` to regenerate. +| `principals` | Array of principal objects the conversation is shared with. Each entry includes the principal identifier and their access level (always `READ_ONLY`). +|===== + +=== Example request + +[source,cURL] +---- +curl -X GET \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info' \ + -H 'Authorization: Bearer {access-token}' \ + -H 'Accept: application/json' +---- + +== Additional resources + +* See also xref:spotter-agent-apis.adoc[Spotter Agent APIs] +* xref:spotter-agent-conversation-apis.adoc[Spotter agent conversation APIs] +* xref:spotter-agent-process-results-apis.adoc[Process Spotter agent conversation results] +* xref:spotter-agent-data-literacy-apis.adoc[Spotter agent data literacy APIs] +* xref:spotter-agent-conversation-mgmt-apis.adoc[APIs for managing saved conversations] diff --git a/modules/ROOT/pages/spotter-agent-streaming-apis.adoc b/modules/ROOT/pages/spotter-agent-streaming-apis.adoc new file mode 100644 index 000000000..7c9f6b9b7 --- /dev/null +++ b/modules/ROOT/pages/spotter-agent-streaming-apis.adoc @@ -0,0 +1,664 @@ += Spotter agent streaming API +:toc: true +:toclevels: 3 + +:page-title: Spotter agent streaming APIs +:page-pageid: spotter-agent-streaming-apis +:page-description: Use the Spotter agent streaming REST API to receive real-time Server-Sent Events (SSE) responses for conversational queries sent to the Spotter agent. + +ThoughtSpot's Spotter agent streaming API lets you send natural language queries to an existing conversation session and receive the response as a real-time Server-Sent Events (SSE) stream, instead of waiting for the complete response. + +For information about creating a conversation session and sending queries to it, see xref:spotter-agent-conversation-apis.adoc[Spotter agent conversation APIs]. + +== Send a query to agent and get streaming responses + +To send queries to an ongoing conversation session with Spotter agent and receive streaming responses, use the `/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream` API endpoint. This API endpoint uses the SSE protocol to deliver data incrementally in real time, rather than waiting for the entire response to be generated before sending it to the client. + +The `/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream` API can be used as an integrated tool for real-time streaming of conversational interactions between agents and the ThoughtSpot backend. + +=== Request parameters + +[width="100%" cols="2,4"] +[options='header'] +|===== +|Parameter| Description +|`conversation_identifier` |__String__. Specify the conversation ID received from the xref:spotter-agent-conversation-apis.adoc#_create_a_conversation_session_with_spotter_agent[POST /api/rest/2.0/ai/agent/conversation/create] API call. +|`messages`|_Array of strings_. Include at least one natural language query. For example, `Sales data for Jackets`, `Top performing products in the west coast`. +|===== + +=== Example request + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "conversation_identifier": "h2I_pTGaRQof", + "messages": [ + "Net sales of Jackets" + ] +}' +---- + +=== API response + +If the API request is successful, the response includes a stream of events, each containing a partial or complete message from the AI agent, rather than a single JSON object. + +Each event is a simple text-based message in a specific format, `data: \n\n`; `\n\n` means that each message sent from the server to the client is prefixed with the `data:` keyword, followed by the actual payload (``), and ends with two newline characters (`\n\n`). + +The API uses this format so that the clients can reconstruct the AI-generated response as it streams in, chunk by chunk, and show the responses in real-time. In agentic workflows, the receiving client or agent listens to the SSE stream, parses each event, and assembles the full response for its users. + +==== Example response +If the request is valid, the API returns SSE streams. Each line has the form `data: [{"type": "...", ...}]`, a JSON array of event objects. + +[source,JSON] +---- +data: [{"type":"ack","node_id":"aGxzcFVrtom8"}] + +data: [{"type":"conv_title","title":"Sales 2025 vs 2024","conv_id":"-XIi04l5rrof"}] + +data: [{"type":"notification","group_id":"cDEsAQbSnd3J","metadata":{"type":"thinking","tool_title":"Analyzing Sales Performance: 2025 vs 2024"},"code":"TOOL_CALL_NOTIFICATION"}] + +data: [{"id":"mNAdvy-NK2l6","type":"text-chunk","group_id":"cDEsAQbSnd3J","metadata":{"format":"markdown","type":"thinking"},"content":"\n\nI need to compare sales performance between 2025 and 2024."}] + +data: [{"type":"notification","group_id":"m1MTvttEUa7o","code":"nls_start"}] + +data: [{"id":"hxWMDP-pgR3B","type":"answer","group_id":"m1MTvttEUa7o","metadata":{"sage_query":"[sales] [date] = '2025' vs [date] = '2024'","session_id":"431adcf9-1328-4d8c-81a1-0faa7fa37ba6","title":"Compare sales for 2025 vs 2024"},"title":"Compare sales for 2025 vs 2024"}] + +data: [{"type":"notification","code":"FINAL_RESPONSE_NOTIFICATION"}] +---- +For the complete response in one payload, use the xref:spotter-agent-conversation-apis.adoc#_send_queries_to_a_conversation_session[`/send` endpoint] instead. + +//// +[source,] +---- +data: [{"type": "ack", "node_id": "BRxCtJ-aGt8l"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": "I"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " understand"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " you're"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " interested"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " in"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " the"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " net"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " sales"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " of"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " Jackets"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": "."}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " I'll"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " retrieve"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " the"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " relevant"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " data"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " for"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " you"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": "."}] + +data: [{"type": "notification", "group_id": "o8dQ9SAWdtrL", "metadata": {"title": "Net sales of Jackets"}, "code": "nls_start"}] + +data: [{"type": "notification", "group_id": "o8dQ9SAWdtrL", "code": "QH", "message": "Fetching Worksheet Data"}] + +data: [{"type": "notification", "group_id": "o8dQ9SAWdtrL", "code": "TML_GEN", "message": "Translating your query with the Reasoning Engine"}] + +data: [{"type": "notification", "group_id": "o8dQ9SAWdtrL", "code": "ANSWER_GEN", "message": "Verifying results with the Trust Layer"}] + +data: [{"id": "r24X7D99SROD", "type": "answer", "group_id": "o8dQ9SAWdtrL", "metadata": {"sage_query": "[sales] [item type] = [item type].'jackets'", "session_id": "b321b404-cbf1-4905-9b0c-b93ad4eedf89", "gen_no": 1, "transaction_id": "6874259d-13b1-478c-83cb-b3ed52628850", "generation_number": 1, "warning_details": null, "ambiguous_phrases": null, "query_intent": null, "assumptions": "You want to see the total sales amount for jackets item type.", "tml_phrases": ["[sales]", "[item type] = [item type].'jackets'"], "cached": false, "sub_queries": null, "title": "Net sales of Jackets", "worksheet_id": "cd252e5c-b552-49a8-821d-3eadaa049cca"}, "title": "Net sales of Jackets"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "The"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " net"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " sales"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " for"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " Jackets"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " have"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " been"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " visual"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "ized"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " for"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " you"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "."}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " This"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " analysis"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " specifically"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " filtered"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " for"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " the"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " item"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " type"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "jackets"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "\""}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " and"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " calculated"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " the"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " total"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " sales"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " amount"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " associated"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " with"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " those"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " products"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ".\n\n"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "**"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "Summary"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " &"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " Insights"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ":"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "**\n"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "-"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " The"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " visualization"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " shows"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " the"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " total"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " net"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " sales"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " for"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " all"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " jacket"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " transactions"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " in"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " your"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " apparel"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " dataset"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ".\n"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "-"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " The"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " calculation"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " uses"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " only"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " sales"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " amounts"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " where"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " the"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " item"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " type"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " is"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " \""}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "J"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "ackets"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ".\"\n"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "-"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " This"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " information"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " is"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " useful"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " for"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " understanding"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " the"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " revenue"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " contribution"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " of"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " jackets"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " within"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " your"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " product"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " mix"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ".\n\n"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "If"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " you'd"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " like"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " to"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " see"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " a"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " breakdown"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " by"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " region"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ","}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " state"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ","}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " time"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " period"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ","}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " or"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " compare"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " jacket"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " sales"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " to"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " other"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " product"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " types"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ","}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " please"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " let"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " me"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " know"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "!"}] +---- +//// + +==== SSE event types +The SSE event types streamed in the API response include: + +* `ack` + +Confirms receipt of the request. For example, the type in the first message `data: [{"type": "ack", "node_id": "BRxCtJ-aGt8l"}]`, which indicates that the server has received the client's request and is acknowledging it. +* `conv_title` + +A conversation title (`title`, `conv_id`). +* `notification` + +Progress or status update (`group_id`, `metadata`, `code`). For example, `TOOL_CALL_NOTIFICATION`, `nls_start`, `FINAL_RESPONSE_NOTIFICATION`. +* `type` + +Type can be `thinking`, `text`. +* `text` + +Complete text block in markdown format. +* `text-chunk` + +Text fragments in incremental streaming, often in markdown (`id`, `group_id`, `metadata` with `format`) +* `content` + +The actual text content sent incrementally. For example, `"I"`, `"understand"`, `"you're"`, `"interested"`, `"in"`, `"the"`, `"net"`, `"sales"`, and so on. +* `text` + +Full text block with same structure as text-chunk. +* `answer` + +Structured answer with metadata (`id`, `group_id`, `metadata` with `sage_query`, `session_id`, `title` and more) +* `error` + +In case of failures. +* `*-interrupt` + +If the generation was stopped mid-stream. +* `group_id` + +Groups related chunks together. + +For more information and examples, see xref:spotter-agent-streaming-apis.adoc#_sse_event_payload_reference[SSE event payload reference]. + +=== Thinking versus output events +Spotter responses have two phases: + +* A *thinking phase*, where the AI reasons through the query and calls internal tools, followed by an *output phase* containing the final response delivered to the user. + + +Events in the thinking phase carry `"metadata": { "type": "thinking" }`. All other events are final output. + +Every event includes a `group_id`. Events sharing the same `group_id` belong together. During the thinking phase, each tool call gets its own `group_id`. A `FINAL_RESPONSE_NOTIFICATION` notification marks the boundary between the thinking and output phases. + +[listing] +---- +THINKING PHASE +─────────────────────────────────────────────────────────── +ack + +┌─ group_id: g1 ── Tool Call 1 ("Searching data") ─────────┐ +│ notification (thinking, TOOL_CALL_NOTIFICATION) │ +│ text-chunk (thinking) │ +│ answer (thinking) │ +└──────────────────────────────────────────────────────────┘ + +┌─ group_id: g2 ── Tool Call 2 ("Running code") ───────────┐ +│ notification (thinking, TOOL_CALL_NOTIFICATION) │ +│ text-chunk (thinking) │ +│ text-chunk (thinking) │ +└──────────────────────────────────────────────────────────┘ + +notification (FINAL_RESPONSE_NOTIFICATION) ←── boundary +──────────────────────────────────────────────────────────── + +OUTPUT PHASE +──────────────────────────────────────────────────────────── +┌─ group_id: g3 ────────────────────────────────────────────┐ +│ text "Here are the results:" │ +│ answer (final visualization) │ +└───────────────────────────────────────────────────────────┘ +[stream closes] +---- + +==== Notification codes reference + +[width="100%" cols="2,4"] +[options='header'] +|===== +|Code| When it appears +|`QH`|Query handling started +|`TML_GEN` / `TML_GEN_RETRY`|Generating or retrying TML +|`ANSWER_GEN`|Generating an answer +|`IDENTIFYING_ATTRIBUTES`|Identifying data attributes +|`PERFORMING_CHANGE_ANALYSIS`|Running change analysis +|`PERFORMING_FORECASTING_ANALYSIS`|Running forecasting +|`SUMMARIZING_RESULTS`|Summarizing results +|`TOOL_CALL_NOTIFICATION`|Tool invocation (during thinking phase) +|`FINAL_RESPONSE_NOTIFICATION`|Marks the transition from thinking to output +|`search_datasets_start` / `search_datasets_end`|Data source discovery in progress or complete +|`approval_required`|An external tool requires user permission before proceeding +|===== + +=== SSE event payload reference + +==== ack + +[source,JSON] +---- +data: { + "type": "ack", + "group_id": "a1b2c3", + "id": "evt-001", + "node_id": "resp-node-abc" +} +---- + +==== notification (thinking — tool call) + +[source,JSON] +---- +data: { + "type": "notification", + "group_id": "g1", + "id": "evt-002", + "code": "TOOL_CALL_NOTIFICATION", + "message": "Searching for relevant data", + "metadata": { + "type": "thinking", + "tool_title": "Searching sales data", + "tool_code": "RUNNING_CODE_EXECUTION", + "tool_name": "code_interpreter" + } +} +---- + +==== notification (thinking - external tool with MCP integration) + +[source,JSON] +---- +data: { + "type": "notification", + "group_id": "g2", + "id": "evt-003", + "code": "TOOL_CALL_NOTIFICATION", + "message": "Querying Salesforce", + "metadata": { + "type": "thinking", + "tool_title": "Salesforce: Get Opportunities", + "tool_name": "get_opportunities", + "integration_id": "int-sf-123", + "integration_name": "Salesforce" + } +} +---- + +==== notification (approval required) +Sent when an external MCP tool requires explicit user permission before proceeding. Your application should prompt the user to approve or deny the action before continuing. + +[source,JSON] +---- +data: { + "type": "notification", + "group_id": "g2", + "id": "evt-005", + "code": "approval_required", + "metadata": { + "request_id": "perm-req-789", + "integration_id": "int-sf-123", + "integration_name": "Salesforce", + "tool_name": "get_opportunities", + "annotated_title": "Access Salesforce Opportunities" + } +} +---- + +==== notification (FINAL_RESPONSE_NOTIFICATION) + +[source,JSON] +---- +data: { + "type": "notification", + "group_id": "g1", + "id": "evt-004", + "code": "FINAL_RESPONSE_NOTIFICATION", + "message": "" +} +---- + +==== text + +[source,JSON] +---- +data: { + "type": "text", + "group_id": "g3", + "id": "evt-007", + "content": "Here is the total revenue breakdown by region for Q4 2025:\n\n- **North America:** $4.2M\n- **EMEA:** $2.8M\n- **APAC:** $1.5M" +} +---- + +==== text-chunk +Multiple chunks sharing the same `id` should be appended together to reconstruct the full text item. + +[source,JSON] +---- +data: { "type": "text-chunk", "group_id": "g3", "id": "evt-009", "content": "Based on the analysis, " } +data: { "type": "text-chunk", "group_id": "g3", "id": "evt-009", "content": "revenue grew 12% quarter-over-quarter." } +---- + +==== answer +When an `answer` event is received, the `session_id` and `gen_no` fields are returned. You can export the visualization data using the Export Answer Report API to process the results. This allows users to download the answer as a PDF, PNG, CSV, or XLSX file. + +[source,JSON] +---- +data: { + "type": "answer", + "group_id": "g3", + "id": "evt-010", + "title": "Revenue by Region Q4 2025", + "metadata": { + "session_id": "sess-abc-123", + "gen_no": 1, + "transaction_id": "txn-456", + "worksheet_id": "ws-def-789", + "cached": false, + "is_hidden": false + } +} +---- + +==== search_datasets +Emitted as a start/end pair during Auto mode data source discovery. + + +[source,JSON] +---- +data: { "type": "search_datasets", "group_id": "g0", "id": "evt-012", "code": "search_datasets_start", "metadata": {} } + +data: { + "type": "search_datasets", + "group_id": "g0", + "id": "evt-013", + "code": "search_datasets_end", + "metadata": { + "data_sources": [ + { "worksheet_id": "ws-1", "worksheet_name": "Sales Data", "confidence": "high", "reasoning": "Contains revenue columns" }, + { "worksheet_id": "ws-2", "worksheet_name": "Marketing Data", "confidence": "low", "reasoning": "No revenue columns" } + ], + "auto_selected": { "worksheet_id": "ws-1", "worksheet_name": "Sales Data", "confidence": "high", "reasoning": "Best match" } + } +} +---- +==== file + +[source,JSON] +---- +data: { + "type": "file", + "group_id": "g3", + "id": "evt-014", + "files": [ + { "ts_file_id": "file-abc-001", "display_name": "quarterly_report.csv", "file_type": "csv", "created_at": "2025-11-15T10:30:00Z" }, + { "ts_file_id": "file-abc-002", "display_name": "chart.png", "file_type": "png", "created_at": "2025-11-15T10:30:01Z" } + ], + "metadata": { "conv_id": "conv-123" } +} +---- +==== conv_title + +[source,JSON] +---- +data: { + "type": "conv_title", + "group_id": "g0", + "id": "evt-015", + "title": "Revenue Analysis Q4 2025", + "conv_id": "conv-123" +} +---- + +==== error + +[source,JSON] +---- +data: { + "type": "error", + "group_id": "g3", + "id": "evt-016", + "code": "RATE_LIMIT_EXCEEDED", + "message": "Too many requests", + "display_message": "You've exceeded the rate limit. Please try again in a few minutes." +} +---- +==== agent-interrupt + +[source,JSON] +---- +Sent when generation is stopped mid-stream. +data: { + "type": "notification", + "group_id": "g3", + "id": "evt-017", + "code": "agent-interrupt", + "message": "Generation stopped" +} +---- + +== Additional resources + +* See also xref:spotter-agent-apis.adoc[Spotter Agent APIs] +* xref:spotter-agent-conversation-apis.adoc[Spotter agent conversation APIs] +* xref:spotter-agent-process-results-apis.adoc[Process Spotter agent conversation results] +* xref:spotter-agent-sharing-apis.adoc[Spotter agent conversation sharing APIs] diff --git a/modules/ROOT/pages/spotter-apis.adoc b/modules/ROOT/pages/spotter-apis.adoc index a7ebfc290..4d988b4a0 100644 --- a/modules/ROOT/pages/spotter-apis.adoc +++ b/modules/ROOT/pages/spotter-apis.adoc @@ -25,6 +25,11 @@ For information about supported API operations, see the following pages: * xref:spotter-classic-apis.adoc[APIs for Spotter classic workflow] * xref:spotter-agent-apis.adoc[APIs for Spotter agent workflows] +* xref:spotter-agent-conversation-apis.adoc[APIs for Spotter agent conversations] +* xref:spotter-agent-streaming-apis.adoc[APIs for Spotter agent streaming responses] +* xref:spotter-agent-process-results-apis.adoc[APIs for processing Spotter agent conversation results] +* xref:spotter-agent-data-literacy-apis.adoc[APIs for Spotter agent data literacy] +* xref:spotter-agent-sharing-apis.adoc[APIs for sharing Spotter conversations] * xref:spotter-agent-conversation-mgmt-apis.adoc[APIs for Spotter conversation management] * xref:spotter-nl-instructions.adoc[APIs for Spotter coaching and NL instructions] * xref:spotter-agent-instructions.adoc[APIs for Spotter agent instructions] diff --git a/modules/ROOT/pages/whats-new.adoc b/modules/ROOT/pages/whats-new.adoc index 56a89557d..f8004e1c8 100644 --- a/modules/ROOT/pages/whats-new.adoc +++ b/modules/ROOT/pages/whats-new.adoc @@ -22,6 +22,109 @@ This page lists new features, enhancements, and deprecated functionality introdu // *Status:* Current / Supported / Deprecated // *Affects:* Developers, Administrators, End Users // ============================================================ +== September 2026 + +**Release version**: ThoughtSpot Cloud 26.9.0.cl + +*Upgrade notes*: No breaking changes in this release. + +*Recommended SDK versions*: Visual Embed SDK v1.52.0 and later + +[.cl-table, cols="2,4", frame=none, grid=none] +|=== +a| +[.cl-label] +*Version 26.9.0.cl* + +a| +[discrete] +==== Browser history management in full application embedding +When ThoughtSpot is embedded in a host application, internal navigation pushes new entries onto the browser history stack, causing the browser *Back* button to step through ThoughtSpot's internal pages before returning to the host application. To override the browser history behavior for embedding application users and prevent users from getting trapped in back-button loops inside the embedded iframe environment, set `overrideHistoryState` in the Visual Embed SDK. + +--- + +[discrete] +==== Collections in embedded left navigation panel [.version-badge.new]#New# + +The `HomeLeftNavItem.Collections` value is now available in the Visual Embed SDK 1.52.0. Embed developers can include *Collections* as a navigation option in the left navigation panel for full application embeds, enabling end users to navigate to *Collections* directly from the embedded experience. For more information, see xref:full-app-customize.adoc[Customize the embedded ThoughtSpot experience]. + +--- + +[discrete] +==== Answer Export API — General Availability [.version-badge.new]#New# + +The Answer Export API (`POST /api/rest/2.0/report/answer`) is now generally available. This release introduces the following enhancements: + +* *Pinned Answer export*: Export a pinned visualization from a Liveboard directly using the `viz_guid` parameter. +* *Personalized View support*: Export data from a specific Personalized View using `personalised_view_identifier`. +* *Spotter Answer export*: Export Spotter-generated answers in `XLSX` and `PDF` formats in addition to `CSV` and `PNG`. +* *Custom PNG dimensions*: Control PNG export dimensions using `x_resolution` and `y_resolution` parameters (600-3840 px). +* *Scaling control*: Adjust chart element size in PNG exports using `scaling_factor` (80-400). + +For more information, see xref:data-report-v2-api.adoc#answer-report[Answer Report API]. + +--- + +[discrete] +==== Snowflake Semantic View integration APIs [.version-badge.new]#New# + +ThoughtSpot introduces four new REST API v2.0 endpoints to manage Snowflake Semantic View integrations programmatically without using the ThoughtSpot UI: + +* `POST /api/rest/2.0/semantic-integrations/create` +* `POST /api/rest/2.0/semantic-integrations/search` +* `POST /api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/import` +* `POST /api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/delete` + +Requires `ADMINISTRATION` or `DATAMANAGEMENT` privilege. For more information, see xref:semantic-integrations-api.adoc[Snowflake Semantic View integration APIs]. + +--- + +[discrete] +==== Spotter Memory — General Availability [.version-badge.new]#New# + +The Spotter memory feature is now generally available. The memory APIs (`POST /api/rest/2.0/ai/memory/import` and `POST /api/rest/2.0/ai/memory/export`) are enabled by default on all ThoughtSpot Cloud instances. Administrators can manage and audit Spotter's training data programmatically. For more information, see xref:spotter-agent-apis.adoc[Spotter agent APIs]. + +--- + +[discrete] +==== Spotter conversation sharing APIs [.version-badge.new]#New# + +ThoughtSpot introduces three new REST API v2.0 endpoints to share Spotter agent conversations programmatically: + +* `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` -- Share a conversation with users or groups with `READ_ONLY` access. +* `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content` -- Retrieve the shared messages and answers in a conversation. +* `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info` -- Retrieve the list of principals a conversation is shared with and their access levels. + +For more information, see xref:spotter-agent-sharing-apis.adoc[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 + @@ -263,7 +366,7 @@ This release introduces the following enhancements for Spotter AI workflows and Spotter now includes data literacy skills that help users understand the underlying data model. Users can ask Spotter to explain available data sources, fields, and relationships in plain language within a conversation session. * Spotter AI APIs: + //** New REST API endpoints to configure and retrieve persistent behavioral xref:spotter-agent-instructions.adoc[instructions for the Spotter agent]. - New API endpoint xref:spotter-agent-apis.adoc#_stop_an_in_progress_agent_response[stop and cancel a long-running Spotter response]. + New API endpoint xref:spotter-agent-conversation-apis.adoc#_stop_an_in_progress_agent_response[stop and cancel a long-running Spotter response]. ---