diff --git a/modules/ROOT/pages/common/nav-rest-api.adoc b/modules/ROOT/pages/common/nav-rest-api.adoc index d492ee863..a0220ffb6 100644 --- a/modules/ROOT/pages/common/nav-rest-api.adoc +++ b/modules/ROOT/pages/common/nav-rest-api.adoc @@ -12,23 +12,25 @@ REST APIs * link:{{navprefix}}/api-authv2[REST API v2.0 authentication] * link:{{navprefix}}/rest-v2-changelog[REST API v2 changelog] * link:{{navprefix}}/restV2-playground?apiResourceId=http%2Fgetting-started%2Fintroduction[REST API v2 Playground] -* link:{{navprefix}}/api-user-management[Users and group privileges] -* link:{{navprefix}}/rbac[Role-based access control] -* link:{{navprefix}}/rest-apiv2-search[Search API endpoints] -** link:{{navprefix}}/rest-apiv2-users-search[Search users] -** link:{{navprefix}}/rest-apiv2-groups-search[Search groups] -** link:{{navprefix}}/rest-apiv2-metadata-search[Search metadata] -* link:{{navprefix}}/fetch-data-and-report-apis[Data and Report APIs] -* link:{{navprefix}}/spotter-api[Spotter APIs] -** link:{{navprefix}}/spotter-agent-apis[AI APIs (Spotter Agent and Spotter 3)] -** link:{{navprefix}}/spotter-apis-classic[AI APIs (Spotter Classic) ^BETA^] -** link:{{navprefix}}/spotter-coaching-apis[Spotter coaching APIs ^BETA^] -* link:{{navprefix}}/audit-logs[Audit logs] -* link:{{navprefix}}/tml[TML] -* link:{{navprefix}}/collections[Collections ^BETA^] -* link:{{navprefix}}/connections[Connections] -* link:{{navprefix}}/connection-config[Connection configuration] -* link:{{navprefix}}/runtime-sort[Runtime sorting] +* link:{{navprefix}}/rest-apiv2-reference[REST API v2.0 Reference] +** link:{{navprefix}}/api-user-management[Users and group privileges] +** link:{{navprefix}}/rbac[Role-based access control] +** link:{{navprefix}}/rest-apiv2-search[Search API endpoints] +*** link:{{navprefix}}/rest-apiv2-users-search[Search users] +*** link:{{navprefix}}/rest-apiv2-groups-search[Search groups] +*** link:{{navprefix}}/rest-apiv2-metadata-search[Search metadata] +** link:{{navprefix}}/fetch-data-and-report-apis[Data and Report APIs] +** link:{{navprefix}}/spotter-api[Spotter APIs] +*** link:{{navprefix}}/spotter-agent-apis[AI APIs (Spotter Agent and Spotter 3)] +*** link:{{navprefix}}/spotter-apis-classic[AI APIs (Spotter Classic) ^BETA^] +*** link:{{navprefix}}/spotter-coaching-apis[Spotter coaching APIs ^BETA^] +** link:{{navprefix}}/style-customization-apis[Style customization APIs] +** link:{{navprefix}}/audit-logs[Audit logs] +** link:{{navprefix}}/tml[TML] +** link:{{navprefix}}/collections[Collections ^BETA^] +** link:{{navprefix}}/connections[Connections] +** link:{{navprefix}}/connection-config[Connection configuration] +** link:{{navprefix}}/runtime-sort[Runtime sorting] [.sidebar-title] diff --git a/modules/ROOT/pages/customize-style-api.adoc b/modules/ROOT/pages/customize-style-api.adoc new file mode 100644 index 000000000..1298a6028 --- /dev/null +++ b/modules/ROOT/pages/customize-style-api.adoc @@ -0,0 +1,340 @@ += Style customization APIs +:toc: true +:toclevels: 2 + +:page-title: Customize styles and layout through REST APIs +:page-pageid: style-customization-apis +:page-description: Customize styles, design, and layout of embedded ThoughtSpot app using REST APIs + +// SOURCE: SCAL-293070, SCAL-293071 + + +ThoughtSpot provides REST API v2.0 endpoints to manage style customization settings programmatically. These APIs expose the same branding and theming controls available in the *Develop* > *Customizations* > *Styles* page, enabling you to automate branding and white-labeling — including across multiple Orgs — without logging in to the ThoughtSpot UI. + +[NOTE] +==== +All style customization API endpoints require administrator or developer privileges. +==== + +=== Style configuration + +Use the following endpoints to search and update style settings at the cluster or Org scope. + +==== Search style configuration +To get the current style configuration for the cluster and the active Org send an API request to `POST /api/rest/2.0/customization/styles/search` endpoint. +When called from the Primary Org (Org 0), the response returns one record with `"scope": "CLUSTER"` and one with `"scope": "ORG"`. + +==== Update style configuration +To update the style settings send an API request to `POST /api/rest/2.0/customization/styles/update` endpoint. + +Request parameters:: + +[cols="2,1,4"] +|===== +|Parameter|Required|Description +|`scope`|Yes|`CLUSTER` or `ORG`. +//|`org_identifier`|Conditional|Required when `scope` is `ORG`. +|`operation`|Yes|`REPLACE` overwrites existing settings. `RESET` reverts specific fields to defaults. +|`navigation_panel`|No|Top navigation panel color. Use `"theme": "CUSTOM"` with a valid hex value in `"base_color"`. +|`chart_color_palette`|No|Array of hex color values for charts. When provided with `REPLACE`, exactly 8 color entries must be specified in colors. +|`embedded_footer_text`|No|Footer text for embedded content. +|`visualization_fonts`|No|Font assignments for visualization elements. Provide only the areas to update; omitted areas remain unchanged. +|`default_logo`|No|Binary image file for the square application logo. +|`wide_logo`|No|Binary image file for the wide logo (email and PDF exports). +|`reset_options`|No|Resets specified settings to ThoughtSpot defaults. +|===== + +Example API request:: To set a custom navigation panel color at cluster scope + + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/customization/styles/update' \ + -H 'Authorization: Bearer {access-token}'\ + -H 'Accept: application/json'\ + -H 'Content-Type: application/json' \ + --data-raw '{ + "scope": "CLUSTER", + "operation": "REPLACE", + "navigation_panel": { + "theme": "CUSTOM", + "base_color": "#2359B6" + } +} +---- + +Example API request:: To update chart color palette for a specific Org (REPLACE) + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/customization/styles/update' \ + -H 'Authorization: Bearer {access-token}'\ + -H 'Accept: application/json'\ + -H 'Content-Type: application/json' \ + --data-raw '{ + "scope": "ORG", + "org_identifier": "Sales Org", + "operation": "REPLACE", + "chart_color_palette": { + "colors": [ + {"color": "#FF6B35"}, + {"color": "#004E89"}, + {"color": "#1A936F"}, + {"color": "#C6D8D3"}, + {"color": "#F18F01"}, + {"color": "#8B4513"}, + {"color": "#6A0572"}, + {"color": "#2E8B57"} + ], + "disable_color_rotation": false + } +} +---- + +=== Custom fonts + +==== Upload a custom font +To upload a font file (multipart/form-data) send an API request to `POST /api/rest/2.0/customization/styles/fonts/upload` endpoint. + +Request parameters:: + +[cols="2,1,4"] +|===== +|Parameter|Required|Description + +|`name` +|Yes +|Display name for the font. Must be unique within the target scope. + +|`file_content` +|Yes +|Binary font file. Accepted formats: WOFF and WOFF2 only. + +|`scope` +|No +|Scope of the font library. Valid values: `CLUSTER`, `ORG`. +Defaults to `ORG` when Orgs are enabled; defaults to `CLUSTER` when Orgs are disabled. + +|`weight` +|No +|Font weight. Valid values: `NORMAL`, `LIGHT`, `BOLD`. + +|`style` +|No +|Font style. Valid values: `NORMAL`, `ITALIC`, `OBLIQUE`. + +|`color` +|No +|Default color for the font as a 6-digit hex string. Example: `#333333`. + +|===== + +Example API request:: +[source,cURL] +---- +curl -X POST 'https://{ThoughtSpot-Host}/api/rest/2.0/customization/styles/fonts/upload' \ +-H 'Authorization: Bearer {token}' \ +-H 'Accept: application/json' \ +-F 'name=Acme Sans' \ +-F 'weight=BOLD' \ +-F 'style=NORMAL' \ +-F 'color=#333333' \ +-F 'file_content=@/path/to/acme-sans-bold.woff2' +---- + + +==== Search custom fonts +To get custom fonts uploaded to the instance or the Org, send an API request to the `POST /api/rest/2.0/customization/styles/fonts/search` endpoint. + +Request parameter:: +[cols="2,1,4"] +|===== +|Parameter|Required|Description + +|`scope` +|Yes +|Scope of the font library. Valid values: `CLUSTER`, `ORG`. + + +|`font_identifier` +|No +|Filter by exact font GUID or exact display name (case-insensitive). +Cannot be used together with `name_pattern`. + +|`name_pattern` +|No +|Filter by partial, case-insensitive substring match on font display name. +Cannot be used together with `font_identifier`. + +|`include_font_assignments` +|No +|If `true`, each font in the response includes the visualization areas it is assigned to. +Default: `false`. + +|===== + +//// +|`org_identifier` +|Conditional +|Unique ID or name of the Org. Applicable only when `scope` is `ORG`. +Defaults to the caller's active Org if omitted. +//// + + +Example API request:: +Return all fonts with their visualization assignments + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/customization/styles/fonts/search' \ + -H 'Authorization: Bearer {access-token}'\ + -H 'Accept: application/json'\ + -H 'Content-Type: application/json' \ + --data-raw '{ + "scope": "CLUSTER", + "include_font_assignments": true +} +---- +Example API request:: Filter by name pattern +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/customization/styles/fonts/search' \ + -H 'Authorization: Bearer {access-token}'\ + -H 'Accept: application/json'\ + -H 'Content-Type: application/json' \ + --data-raw '{ + "scope": "ORG", + "org_identifier": "Sales Org", + "name_pattern": "acme", + "include_font_assignments": false +} +---- + +==== Update a custom font +To update an existing font's display name, weight, style, or color send an API request to the `POST /api/rest/2.0/customization/styles/fonts/{font_identifier}/update` endpoint. + +Request parameters:: + +[cols="2,1,4"] +|===== +|Parameter|Required|Description + +|`font_identifier` +|Yes +|GUID or display name of the font to update. Passed as a path parameter. + +|`scope` +|Yes +|Scope of the font library. Valid values: `CLUSTER`, `ORG`. + +|`name` +|No +|New display name for the font. Omit to leave unchanged. + +|`weight` +|No +|Updated font weight. Valid values: `NORMAL`, `LIGHT`, `BOLD`. +Omit to leave unchanged. + +|`style` +|No +|Updated font style. Valid values: `NORMAL`, `ITALIC`, `OBLIQUE`. +Omit to leave unchanged. + +|`color` +|No +|Updated default color as a 6-digit hex string. Example: `#333333`. +Omit to leave unchanged. + +|===== + +Example API request:: + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/customization/styles/fonts/a1b2c3d4-e5f6-7890-abcd-ef1234567890/update' \ + -H 'Authorization: Bearer {access-token}'\ + -H 'Accept: application/json'\ + -H 'Content-Type: application/json' \ + --data-raw '{ + "scope": "CLUSTER", + "name": "Acme Sans Revised", + "weight": "BOLD", + "color": "#111111" + } + +---- + +==== Delete custom fonts +To delete one or more custom fonts from the font library send an API request to the `POST /api/rest/2.0/customization/styles/fonts/delete` endpoint. + +Request parameter:: +[cols="2,1,4"] +|===== +|Parameter|Required|Description + +|`scope` +|Yes +|Scope of the font library. Valid values: `CLUSTER`, `ORG`. + + +|`font_identifiers` +|Yes +|List of font GUIDs or display names to delete. +Duplicate values are deduplicated automatically. + +|`dry_run` +|No +|If `true`, returns the list of affected visualization assignments without deleting any fonts. When a font is deleted, all visualization areas that used it are automatically reset to the system default font. Set to `false` to commit the deletion. +Default: `true`. + +|===== + +//// +|`org_identifier` +|Conditional +|Unique ID or name of the Org. Applicable only when `scope` is `ORG`. +Defaults to the caller's active Org if omitted. +//// + + +Example API request:: + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/customization/styles/fonts/delete' \ + -H 'Authorization: Bearer {access-token}'\ + -H 'Accept: application/json'\ + -H 'Content-Type: application/json' \ + --data-raw '{ + "scope": "CLUSTER", + "font_identifiers": [ + "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "b2c3d4e5-f6a7-8901-bcde-f12345678901" + ], + "dry_run": true +} +---- + +=== Logo export +To get the configured logos at the requested scope as a ZIP archive containing the default and wide logo images, send an API request to the `POST /api/rest/2.0/customization/styles/logos/export` endpoint. + +Example API request:: + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/customization/styles/logos/export' \ + -H 'Authorization: Bearer {access-token}'\ + -H 'Accept: application/json'\ + -H 'Content-Type: application/json' \ + --data-raw '{ + "scope": "CLUSTER" +} +---- \ 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 7c9ecbe95..c3208d880 100644 --- a/modules/ROOT/pages/rest-apiv2-changelog.adoc +++ b/modules/ROOT/pages/rest-apiv2-changelog.adoc @@ -8,6 +8,50 @@ 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.7.0.cl, July 2026 + +=== Style customization APIs + +// SOURCE: SCAL-293070, SCAL-293071 + +ThoughtSpot introduces REST API v2.0 endpoints to manage style customization settings programmatically. + +Style configuration:: + +* `POST /api/rest/2.0/customization/styles/search` + +Returns the current style configuration at the `CLUSTER` or active `ORG` scope. + +* `POST /api/rest/2.0/customization/styles/update` + +Updates style settings at the `CLUSTER` or `ORG` scope. + +//// +Supports updating the navigation panel color, chart color palette, logos, embedded footer text, and visualization font assignments. +Use `operation: REPLACE` to overwrite existing settings, or `operation: MERGE` to apply only the fields specified in the request. +//// + +Custom fonts:: + +* `POST /api/rest/2.0/customization/styles/fonts/upload` + +Uploads a custom font file to ThoughtSpot. + +* `POST /api/rest/2.0/customization/styles/fonts/search` + +Returns custom fonts uploaded to the instance. +//Use the `include_font_assignments` parameter to include information about which visualization elements each font is assigned to. + +* `PUT /api/rest/2.0/customization/styles/fonts/{font_identifier}/update` + +Updates the display name, weight, style, or color of an existing custom font. + +* `POST /api/rest/2.0/customization/styles/fonts/delete` + +Deletes one or more custom fonts from the font library. + + +Logo export:: + +* `POST /api/rest/2.0/customization/styles/logos/export` + +Exports the current logo files as a ZIP archive containing the default logo and the wide logo. + +For more information, see xref:customize-style-api.adoc[Style customization APIs]. + == Version 26.6.0.cl, June 2026 === Spotter AI APIs diff --git a/modules/ROOT/pages/style-customization.adoc b/modules/ROOT/pages/style-customization.adoc index 0816f9ac1..6fd53a71e 100644 --- a/modules/ROOT/pages/style-customization.adoc +++ b/modules/ROOT/pages/style-customization.adoc @@ -20,12 +20,15 @@ You can customize key UI components, such as your application logo, favicon, fon Custom CSS changes take precedence and override the style customization settings applied via UI. ==== +Style customization through the REST APIs:: +You can manage style customization settings programmatically by using the ThoughtSpot REST APIs. +These endpoints expose all branding and theming controls available in the ThoughtSpot UI. For more information, see xref:xref:customize-style-api.adoc[Customize UI layout and styles through REST APIs] + Advanced style customization with custom CSS:: Custom CSS allows developers to override the default styles and UI element specifications in their deployments. Custom CSS provides granular control over the UI appearance and allows you to modify design elements such as buttons, labels, text styles, and typography. This feature is available only with the ThoughtSpot Embedded Edition license. + To customize themes and variables in the CSS file, developers must know the basics of HTML and CSS framework and how to build custom themes. For more information, see xref:css-customization.adoc[Advanced customization with custom CSS]. - A xref:style-customization_tutorial.adoc[hands-on tutorial] is also available to learn how to test style customization capabilities using Visual Embed Playground. == Scope of customization diff --git a/modules/ROOT/pages/whats-new.adoc b/modules/ROOT/pages/whats-new.adoc index 6320f0913..b18e195b1 100644 --- a/modules/ROOT/pages/whats-new.adoc +++ b/modules/ROOT/pages/whats-new.adoc @@ -23,6 +23,27 @@ This page lists new features, enhancements, and deprecated functionality introdu // *Affects:* Developers, Administrators, End Users // ============================================================ +== July 2026 + +**Release version**: ThoughtSpot Cloud 26.7.0.cl + +*Upgrade notes*: No breaking changes. + +*Recommended SDK versions*: Visual Embed SDK v1.50.0 and later + +[.cl-table, cols="2,4", frame=none, grid=none] +|===== +a| +[.cl-label] +*Version 26.7.0.cl* + +a| +[discrete] +==== REST API v2 +This release introduces new API endpoints for style customization. For information about REST API v2 enhancements, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. + +--- + +|===== + == June 2026 **Release version**: ThoughtSpot Cloud 26.6.0.cl +