REST API v2.0 changelog

REST API v2.0 changelog

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 What’s New.

Version 10.4.0.cl, November 2024🔗

New API endpoints🔗

Spotter AI APIs Beta

  • POST /api/rest/2.0/ai/conversation/create
    Creates a conversation session.

  • POST /api/rest/2.0/ai/conversation/{conversation_identifier}/converse
    Generates responses for user queries and follow-up questions.

  • POST /api/rest/2.0/ai/answer/create
    Generate an Answer from a Natural Language Search query

Authentication

The /api/rest/2.0/auth/token/custom API endpoint is now available to generate an authentication token with custom rules and filter conditions for a user.

ThoughtSpot recommends using the custom token API endpoint to generate tokens for the Attribute-Based Access Control (ABAC) implementation. For more information, see REST API v2 authentication and ABAC via tokens.

Connections

The following new API endpoints are available for updating and deleting a connection object:

  • POST /api/rest/2.0/connections/{connection_identifier}/update

  • POST /api/rest/2.0/connections/{connection_identifier}/delete

ThoughtSpot recommends using these APIs instead of POST /api/rest/2.0/connection/update and POST /api/rest/2.0/connection/update.

TML

The following API endpoints are available for asynchronous TML import:

  • POST /api/rest/2.0/metadata/tml/async/import
    Validates and imports TML objects asynchronously. Use this API endpoint when importing large metadata objects.

  • POST /api/rest/2.0/metadata/tml/async/status
    Fetches task status for the async TML import operations.

For more information, see Import TML objects asynchronously.

API enhancements🔗

User session

  • The 200 API response for the /api/rest/2.0/auth/session/user and /api/rest/2.0/users/search is modified to show access_control_properties.

  • You can now manage account activation status for IAMv2 users using the following API endpoints:

    • POST /api/rest/2.0/users/create

    • POST /api/rest/2.0/users/{user_identifier}/update

TML import API

You can specify the following attributes in TML import requests to /api/rest/2.0/metadata/tml/import:

  • skip_cdw_validation_for_tables
    Indicates if the Cloud Data Warehouse (CDW) validation for table imports should be skipped.

Report API

The POST /api/rest/2.0/report/answer API endpoint supports downloading an Answer generated by the Spotter AI APIs:

  • session_identifier
    Session ID returned in API response by the /api/rest/2.0/ai/answer/create or /api/rest/2.0/ai/conversation/create endpoint.

  • generation_number
    Number assigned to the Answer session with Spotter.

    If you are downloading an Answer generated by Spotter, you must specify the session ID. The metadata_identifier property is not required.

Deprecated features🔗

Connection APIs

The following connection API endpoints are deprecated:

  • POST /api/rest/2.0/connection/delete

  • POST /api/rest/2.0/connection/update

Use POST /api/rest/2.0/connections/{connection_identifier}/update and POST /api/rest/2.0/connections/{connection_identifier}/delete APIs to update and delete a connection object respectively.

Authentication

The user_parameters property in /api/rest/2.0/auth/token/full and /api/rest/2.0/auth/token/object APIs is deprecated.

ThoughtSpot recommends using /api/rest/2.0/auth/token/custom API endpoint with filter_rules and parameter_values to configure user properties for ABAC via tokens.

Version 10.3.0.cl, October 2024🔗

New API endpoint🔗

You can now create a copy of a Liveboard or Answer object using /api/rest/2.0/metadata/copyobject API endpoint.

Version 10.1.0.cl, August 2024🔗

New API endpoints🔗

  • POST /api/rest/2.0/metadata/tml/export/batch
    Exports a batch of TML for user, user group, or Role objects.

Security APIs🔗

The /api/rest/2.0/security/metadata/fetch-permissions API endpoint supports the following parameters:

  • record_offset
    Specifies the starting record number from which the records for each metadata type will be included in the API response.

  • record_size
    Specifies the number of records that should be included for each metadata type in the API response.

  • permission_type
    Specifies the type of permission. Valid values are:

    • EFFECTIVE - If user permission to the metadata objects is granted by the privileges assigned to the groups to which they belong.

    • DEFINED - If a user or user group received access to metadata objects via object sharing by another user.

Version 10.0.0.cl, July 2024🔗

Roles🔗

You can now assign the CAN_MANAGE_VERSION_CONTROL role using any of the following API endpoints:

  • POST /api/rest/2.0/roles/create

  • POST /api/rest/2.0/roles/{role_identifier}/update

The CAN_MANAGE_VERSION_CONTROL Role privilege is required for Git integration with ThoughtSpot.

Version 9.12.0.cl, May 2024🔗

New features🔗

Authentication API

  • /api/rest/2.0/auth/token/validate
    Validates the authentication token of the logged-in user.

TML API

The export TML API requests now support the following parameters:

  • export_schema_version
    Specifies the schema version for datasets during TML export. By default, the API request uses v1 schema for Worksheet TML export. For Models, set export_schema_version to v2.

  • export_dependent
    Allows exporting dependent Tables while exporting a Connection.

  • export_connection_as_dependent
    Specifies if a Connection can be exported as a dependent object when exporting a Table, Worksheet, Answer, or Liveboard. This parameter works only when export_associated is set to true in the API request.

Deprecated features🔗

Token authentication APIs

The jwt_user_options object property in /api/rest/2.0/auth/token/full and /api/rest/2.0/auth/token/object is deprecated. Use the user_parameters property to define security entitlements to a user session. For more information, see ABAC via tokenBeta.

Version 9.10.5.cl, April 2024🔗

New features🔗

Authentication

The /api/rest/2.0/auth/token/full and /api/rest/2.0/auth/token/object API endpoints support generating JWT token for Attribute-Based Access Control. The user_parameters object allows you to define security entitlements for a given user.

For more information, see ABAC via tokens.

Roles

The /api/rest/2.0/roles/create and /api/rest/2.0/roles/{role_identifier}/update API endpoints support assigning the following privileges to a Role for granular data access control and management:

  • CAN_MANAGE_CUSTOM_CALENDAR

  • CAN_CREATE_OR_EDIT_CONNECTIONS

  • CAN_MANAGE_WORKSHEET_VIEWS_TABLES

DBT

You can now use file_content to upload DBT Manifest and Catalog artifact files as a ZIP file in your API requests to the /api/rest/2.0/dbt/dbt-connection, /api/rest/2.0/dbt/generate-tml, /api/rest/2.0/dbt/generate-sync-tml, and /api/rest/2.0/dbt/update-dbt-connection endpoints. Required if the import_type parameter is set to 'ZIP_FILE.

Connections

  • /api/rest/2.0/connections/fetch-connection-diff-status/{connection_identifier}
    Validates the differences in Connection metadata between Cloud Data Warehouse and ThoughtSpot.

  • /api/rest/2.0/connections/download-connection-metadata-changes/{connection_identifier}
    Downloads the connection metadata differences identified between Cloud Data Warehouse and ThoughtSpot.

Logs

The /api/rest/2.0/logs/fetch API endpoint allows fetching all logs in a single API request. To get all logs, set get_all_logs to true.

Share metadata

The /api/rest/2.0/security/metadata/share API supports the following new properties:

  • notify_on_share
    Sends a share notification to the email addresses specified in the API request.

  • has_lenient_discoverability
    Sets the shared metadata object as a discoverable object. Applies to Saved Answers and Liveboards only.

Users

The trigger_activation_email property allows you to specify if an activation email must be sent to the user’s email address in the user creation request to the /api/rest/2.0/users/create endpoint.

Deprecated features🔗

Version Control APIs

The following parameters in the /api/rest/2.0/vcs/git/config/create and /api/rest/2.0/vcs/git/config/update are deprecated from 9.10.5.cl onwards:

  • default_branch_name
    Replaced by commit_branch_name

  • guid_mapping_branch_name
    Replaced by configuration_branch_name

For more information, see Git integration and version control.

Version 9.10.0.cl, March 2024🔗

New API endpoints🔗

DBT

  • POST /api/rest/2.0/dbt/dbt-connection
    Creates a DBT connection.

  • POST /api/rest/2.0/dbt/generate-tml
    Generates Worksheets and Tables for a given DBT connection.

  • POST /api/rest/2.0/dbt/generate-sync-tml
    Synchronizes the existing TML of data models and Worksheets and import them to Thoughtspot.

  • POST /api/rest/2.0/dbt/search
    Gets a list of DBT connection objects for a given user or Org.

  • POST /api/rest/2.0/dbt/{dbt_connection_identifier}
    Updates a DBT connection.

System

GET api/rest/2.0/system/banner
Gets cluster maintenance status and banner text.

For more information, see Cluster maintenance and upgrade.

Version 9.8.0.cl, January 2024🔗

The deploy_policy property in the /api/rest/2.0/vcs/git/commits/deploy endpoint now supports the VALIDATE_ONLY option, which allows you to compare and validate TML content on the destination environment against the content in the main branch before deploying commits.

Version 9.7.0, November 2023🔗

Version Control APIs🔗

This release introduces the following enhancements to the Version Control API endpoints:

Git connection creation and update APIs🔗

The POST /api/rest/2.0/vcs/git/config/create and POST /api/rest/2.0/vcs/git/config/update API endpoints include the following enhancements:

New parameters

  • commit_branch_name
    Allows configuring a commit branch for Git connections on your ThoughtSpot instance. ThoughtSpot recommends using commit_branch_name instead of default_branch_name in the API calls to prevent users from committing changes to the default deployment branch.

  • configuration_branch_name
    Allows configuring a separate Git branch for storing and maintaining configuration files, such as GUID mapping and commit tracking files. If the configuration_branch_name property is defined, the guid_mapping_branch_name parameter is not required.

Modified parameters

The enable_guid_mapping parameter is enabled by default.

Separate branches for Orgs

If you are using Orgs and want to move content between these Orgs using version control APIs, ensure that you set a separate Git branch for each Org. If two Orgs are connected to the same Git repository_url, the POST /api/rest/2.0/vcs/git/config/create and POST /api/rest/2.0/vcs/git/config/update API endpoints do not support configuring the same branch name for these Orgs.

Deprecation notice

The default_branch_name and guid_mapping_branch_name parameters will be deprecated from version 10.0.0.cl and later releases.

For more information, see Connect your ThoughtSpot environment to the Git repository.

Commit API🔗

The POST /api/rest/2.0/vcs/git/branches/commit API endpoint allows the following new attribute in the request body:

  • delete_aware

    When set to true, the system runs a check between the objects and files in the Git branch and destination environment or Org. If an object exists in the Git branch, but not the destination environment or Org, it will be deleted from the Git branch during the commit operation.

For more information, see Commit files.

Deploy API🔗

Note the following changes:

  • The branch_name attribute is now mandatory in the POST /api/rest/2.0/vcs/git/commits/deploy API requests. Ensure that you specify the name of the Git branch from which the commits can be picked and deployed on the destination environment or Org.

  • After a successful deployment, a tracking file is generated with the commit_id and saved in the Git branch that is used for storing configuration files. The commit_id recorded in the tracking file is used for comparing changes when new commits are pushed in the subsequent API calls.

For more information, see Deploy commits.

User API🔗

The following new API endpoints are introduced for user account management:

  • POST /api/rest/2.0/users/activate
    Activates an inactive user account.

  • POST /api/rest/2.0/users/deactivate
    Deactivates a user account.

Support for sorting of columns at runtime🔗

The following data API endpoints now support runtime sorting of columns:

  • POST /api/rest/2.0/searchdata

  • POST /api/rest/2.0/metadata/liveboard/data

  • POST /api/rest/2.0/metadata/answer/data

For more information, see Runtime sorting of columns.

Version 9.6.0.cl, October 2023🔗

New API endpoints🔗

  • POST /api/rest/2.0/customization/custom-actions/search
    Gets custom action objects

  • POST /api/rest/2.0/customization/custom-actions
    Creates a custom action

  • POST /api/rest/2.0/customization/custom-actions/{custom_action_identifier}/update
    Updates the properties of a custom action object.

  • POST /api/rest/2.0/customization/custom-actions/{custom_action_identifier}/delete
    Deletes a custom action

SDK for TypeScript🔗

ThoughtSpot provides TypeScript SDK to help client applications call REST APIs using TypeScript. You can download the SDK from the NPM site.

Version 9.5.0.cl, September 2023🔗

New API endpoints for Role-Based Access Control Beta🔗

  • POST /api/rest/2.0/roles/search
    Gets details of role objects available in the ThoughtSpot system.

  • POST /api/rest/2.0/roles/create
    Creates a role and assigns privileges

  • POST /api/rest/2.0/roles/{role_identifier}/update
    Updates the properties of a given role

  • POST /api/rest/2.0/roles/{role_identifier}/delete
    Removes a role object from the ThoughtSpot system

For more information, see Role-based access control.

Note

The roles APIs work only if the Role-Based Access Control (RBAC) Beta feature is enabled on your instance. The RBAC feature is turned off by default. To enable this feature, contact ThoughtSpot Support.

Enhancements and API modifications🔗

Support for runtime parameter overrides

The following data and report API endpoints support applying runtime parameter overrides:

  • POST /api/rest/2.0/searchdata

  • POST /api/rest/2.0/metadata/liveboard/data

  • POST /api/rest/2.0/metadata/answer/data

  • POST /api/rest/2.0/report/liveboard

  • POST /api/rest/2.0/report/answer

Git integration support for Orgs

The Version Control API endpoints support using Orgs as disparate deployment environments. You can create separate Orgs for dev, staging, and prod and integrate these environments with a GitHub repo.

For more information, see Git integration and version control.

Response code change BREAKING CHANGE🔗

The following endpoints now return the 204 response code instead of 200. The 204 code doesn’t return a response body. This change may affect your current implementation, so we recommend that you update your code to avoid issues.

  • POST /api/rest/2.0/connection/delete

  • POST /api/rest/2.0/connection/update

  • POST /api/rest/2.0/users/{user_identifier}/update

  • POST /api/rest/2.0/users/{user_identifier}/delete

  • POST /api/rest/2.0/users/change-password

  • POST /api/rest/2.0/users/reset-password

  • POST /api/rest/2.0/users/force-logout

  • POST /api/rest/2.0/groups/{group_identifier}/update

  • POST /api/rest/2.0/groups/{group_identifier}/delete

  • POST /api/rest/2.0/metadata/delete

  • POST /api/rest/2.0/orgs/{org_identifier}/update

  • POST /api/rest/2.0/orgs/{org_identifier}/delete

  • POST /api/rest/2.0/schedules/{schedule_identifier}/delete

  • POST /api/rest/2.0/schedules/{schedule_identifier}/update

  • POST /api/rest/2.0/security/metadata/assign

  • POST /api/rest/2.0/security/metadata/share

  • POST /api/rest/2.0/system/config-update

  • POST /api/rest/2.0/tags/{tag_identifier}/update

  • POST /api/rest/2.0/tags/{tag_identifier}/delete

  • POST /api/rest/2.0/tags/assign

  • POST /api/rest/2.0/tags/unassign

  • POST /api/rest/2.0/vcs/git/config/delete

  • POST /api/rest/2.0/auth/session/login

  • POST /api/rest/2.0/auth/session/logout

  • POST /api/rest/2.0/auth/token/revoke

Version 9.4.0.cl, August 2023🔗

API endpoints to schedule and manage Liveboard jobs🔗

  • POST /api/rest/2.0/schedules/create
    Creates a scheduled job for a Liveboard

  • POST /api/rest/2.0/schedules/{schedule_identifier}/update
    Updates a scheduled job

  • POST /api/rest/2.0/schedules/search
    Gets a list of Liveboard jobs configured on a ThoughtSpot instance

  • POST /api/rest/2.0/schedules/{schedule_identifier}/delete
    Deletes a scheduled job.

For more information, see REST API v2.0 Reference.

API to fetch authentication token🔗

The GET /api/rest/2.0/auth/session/token API endpoint fetches the current authentication token used by the currently logged-in user.

Version Control API enhancements🔗

  • The following Version Control API endpoints support generating and maintaining a GUID mapping file on a Git branch connected to a ThoughtSpot instance:

    • POST /api/rest/2.0/vcs/git/config/create

    • POST /api/rest/2.0/vcs/git/config/update

User and group API enhancements🔗

  • The POST /api/rest/2.0/users/{user_identifier}/update and POST /api/rest/2.0/groups/{group_identifier}/update support specifying the type of operation API request. For example, if you are removing a property of a user or group object, you can specify the operation type as REMOVE in the API request.

  • The POST /api/rest/2.0/users/{user_identifier}/update allows you to define locale settings, preferences, and other properties for a user object.

Version 9.3.0.cl, June 2023🔗

The following Version Control Beta API endpoints are now available for the lifecycle management of content on your deployment environments:

  • POST /api/rest/2.0/vcs/git/config/search

  • POST /api/rest/2.0/vcs/git/commits/search

  • POST /api/rest/2.0/vcs/git/config/create

  • POST /api/rest/2.0/vcs/git/config/update

  • POST /api/rest/2.0/vcs/git/config/delete

  • POST /api/rest/2.0/vcs/git/branches/commit

  • POST /api/rest/2.0/vcs/git/commits/{commit_id}/revert

  • POST /api/rest/2.0/vcs/git/branches/validate

  • POST /api/rest/2.0/vcs/git/commits/deploy

For more information, see Version control and Git integration.

Version 9.2.0.cl, May 2023🔗

New endpoints

  • System

    • POST /api/rest/2.0/system/config-update
      Updates system configuration

    • GET /api/rest/2.0/system/config-overrides
      Gets system configuration overrides

  • Connections

    • POST /api/rest/2.0/connection/create
      Creates a data connection

    • POST /api/rest/2.0/connection/search
      Gets a list of data connections

    • POST /api/rest/2.0/connection/update
      Updates a data connection

    • POST /api/rest/2.0/connection/delete
      Deletes a data connection

Enhancements

  • Support for runtime filters and runtime sorting of columns
    The following REST API v2.0 endpoints support applying runtime filters and sorting column data:

    • POST /api/rest/2.0/report/liveboard

    • POST /api/rest/2.0/report/answer

  • Search users by their favorites

    The /api/rest/2.0/users/search API endpoint allows searching users by their favorite objects and home Liveboard setting.

  • Ability to log in to a specific Org

    The /api/rest/2.0/auth/session/login API endpoint now allows ThoughtSpot users to log in to a specific Org context.

Version 9.0.0.cl, February 2023🔗

The ThoughtSpot Cloud 9.0.0.cl release introduces the REST API v2.0 endpoints and Playground. For information about REST API v2.0 endpoints and Playground, see the following articles: