TypeScript SDK for REST APIs
10.14.0.cl
Cloud (Latest)
10.13.0.cl
Cloud
10.12.0.cl
Cloud
10.10.0.sw
Software (Latest)
10.1.0.sw
Software

TypeScript SDK for REST APIs

The REST API TypeScript SDK includes classes and methods that correspond to the resource elements and data types that the API uses when processing requests and responses.

The REST API SDK library for TypeScript is available on the NPM site.

Before you begin🔗

Before you begin, check the following prerequisites:

  • Node.js version 18 or later is installed.

  • Access to a ThoughtSpot instance. Make sure you have the following information:

    • User credentials

    • URL of the ThoughtSpot instance

    • Secret key (Required for trusted authentication only)

  • User privileges and object permissions to view, edit, or create ThoughtSpot objects and resources.

Setup and usage🔗

Complete the following steps:

  1. Install the SDK in your local directory.

    npm install @thoughtspot/rest-api-sdk --save

  2. Import the SDK.

    import {
    createBearerAuthenticationConfig,
    ThoughtSpotRestApi,
} from '@thoughtspot/rest-api-sdk';

  3. Create a client session using one of the following options:

    • Get an authentication token via getAuthToken method.

      const config = createBearerAuthenticationConfig("CLUSTER_SERVER_URL", getAuthToken);
const tsRestApiClient = new ThoughtSpotRestApi(config);

const getAuthToken = async () => {
    returns "BEARER TOKEN";
}

    • To obtain a token on behalf of another user, use secret_key instead of password. The secret key is generated on ThoughtSpot if Trusted authentication is enabled on your ThoughtSpot instance. For more information, see Secret key management.

      const config = createBearerAuthenticationConfig("CLUSTER_SERVER_URL", {
    username: "USERNAME",
    secret_key: "SECRET_KEY",
});
const tsRestApiClient = new ThoughtSpotRestApi(config);

      If the user account doesn’t exist in ThoughtSpot, you can provision a user just in time and assign privileges.

      const config = createBearerAuthenticationConfig();
const tsRestApiClient = new ThoughtSpotRestApi(config);
tsRestApiClient.getFullAccessToken(
    // GetFullAccessTokenRequest
    {
        username: "USERNAME",
        secret_key: "SECRET_KEY",
        email: "[email protected]",
        display_name: "display_name_example",
        auto_create: true,
        org_id: 0,
        group_identifiers: [
            "GROUP-A", "GROUP-B",
        ],
    }
).then((data: any) => {
    console.log('API called successfully. Returned data: ' + data);
}).catch((error: any) => console.error(error));

    • Use basic authentication with username and password:

      const config = createBearerAuthenticationConfig("CLUSTER_SERVER_URL", {
        username: "YOUR_USERNAME",
        password: "PASSWORD",
    });
const tsRestApiClient = new ThoughtSpotRestApi(config);
};

    • If a session cookie is already set via either Visual Embed SDK or login method, you can send requests without authentication.

       const config = createConfiguration({
    baseServer: new ServerConfiguration("CLUSTER_SERVER_URL", {}),
  });
  const tsRestApiClient = new ThoughtSpotRestApi(config);

  4. Send a test request.

    • Try creating a user as shown in the following example. To view and copy the supported parameters and values, use the REST API v2 Playground.

      import {
    createBearerAuthenticationConfig,
    ThoughtSpotRestApi,
} from '@thoughtspot/rest-api-sdk';

const tsRestApiClient = new ThoughtSpotRestApi(config);
tsRestApiClient.createUser(
    // CreateUserRequest
    {
        name: "UserA",
        display_name: "User A",
        password: "123Guest!",
        email: "[email protected]",
        account_type: "LOCAL_USER",
        account_status: "ACTIVE",
        visibility: "SHARABLE",
        notify_on_share: true,
        show_onboarding_experience: true,
        onboarding_experience_completed: false,
        preferred_locale: "en-CA",
        trigger_welcome_email: true,
    }
).then((data: any) => {
    console.log('API called successfully. Returned data: ' + data);
}).catch((error: any) => console.error(error));

    • Try a GET call, for example, get a list of users via searchUsers. To get specific details, you can specify optional parameters such as visibility, account_type, account_status, group_identifiers, and so on. To get the details of a user, specify the name or GUID of the user as user_identifier.

      import {
    createBearerAuthenticationConfig,
    ThoughtSpotRestApi,
} from '@thoughtspot/rest-api-sdk';

const tsRestApiClient = new ThoughtSpotRestApi(config);
tsRestApiClient.searchUsers(
    // SearchUsersRequest (optional parameters)
    {
        user_identifier: "UserA",
    }
).then((data: any) => {
    console.log('API called successfully. Returned data: ' + data);
}).catch((error: any) => console.error(error));

Error handling🔗

The SDK raises errors when the HTTP response code indicates an error. You can use these error codes to handle or log errors as shown in the following example:

const test = async () => {
    const client = getClientWithoutAuth(HOST);
    try {
        const data = await client.searchUsers({});
        const names = data.reduce((names, user) => {
            return names + " " + user.name;
        }, "");
        console.log(names);
    } catch (e) {
        switch (e.code) {
            case 401: {
                alert("Unauthorized error");
                break;
            }
            case 400: {
                alert("Incorrect input");
                break;
            }
            default: {
                alert("Server error " + e.code);
            }
        }
    }
};

Supported versions🔗

Note the version recommendations for your ThoughtSpot instances:

ThoughtSpot release versionRecommended SDK version

ThoughtSpot Cloud: 10.14.0.cl

v2.19.0 or later

ThoughtSpot Cloud: 10.13.0.cl

v2.18.0 or later

ThoughtSpot Cloud: 10.12.0.cl

v2.17.0 or later

ThoughtSpot Cloud: 10.11.0.cl

v2.16.0 or later

ThoughtSpot Cloud: 10.10.0.cl

v2.15.1 or later

ThoughtSpot Cloud: 10.9.0.cl

v2.14.0 or later

ThoughtSpot Cloud: 10.8.0.cl

v2.13.1 or later

ThoughtSpot Cloud: 10.6.0.cl

v2.12.1 or later

  • ThoughtSpot Cloud release versions:

    • 9.12.0.cl

    • 9.12.5.cl

    • 10.1.0.cl

    • 10.3.0.cl

    • 10.4.0.cl

    • 10.5.0.cl

  • ThoughtSpot Software: 10.1.0.sw

v2.11.1 or later

  • ThoughtSpot Cloud: 9.10.5.cl

v2.4.1 or later

  • ThoughtSpot Cloud: 9.10.0.cl

v2.4.0 or later

  • ThoughtSpot Cloud: 9.8.0.cl

  • ThoughtSpot Software: 9.8.0.sw

v2.2.0 or later

  • ThoughtSpot Cloud: 9.7.0.cl

  • ThoughtSpot Software: 9.8.0.sw

v2.1.0 or later

  • ThoughtSpot Cloud: 9.6.0.cl

  • ThoughtSpot Software: 9.8.0.sw

v2.0.2 or later

For information about new features, breaking changes, and deprecated parameters, see API changelog.

SDK Reference🔗

For a complete list of supported methods to use for API requests, see the following resources:

MethodHTTP request

activateUser

POST /api/rest/2.0/users/activate

assignChangeAuthor

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

assignTag

POST /api/rest/2.0/tags/assign

changeUserPassword

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

commitBranch

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

connectionConfigurationSearch

POST /api/rest/2.0/connection-configurations/search

convertWorksheetToModel

POST /api/rest/2.0/metadata/worksheets/convert

copyObject

POST /api/rest/2.0/metadata/copyobject

createCalendar

POST /api/rest/2.0/calendars/create

createConfig

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

createConnection

POST /api/rest/2.0/connection/create

createConnectionConfiguration

POST /api/rest/2.0/connection-configurations/create

createConversation

POST /api/rest/2.0/ai/conversation/create

createCustomAction

POST /api/rest/2.0/customization/custom-actions

createEmailCustomization

POST /api/rest/2.0/customization/email

createOrg

POST /api/rest/2.0/orgs/create

createRole

POST /api/rest/2.0/roles/create

createSchedule

POST /api/rest/2.0/schedules/create

createTag

POST /api/rest/2.0/tags/create

createUser

POST /api/rest/2.0/users/create

createUserGroup

POST /api/rest/2.0/groups/create

createVariable

POST /api/rest/2.0/template/variables/create

dbtConnection

POST /api/rest/2.0/dbt/dbt-connection

dbtGenerateSyncTml

POST /api/rest/2.0/dbt/generate-sync-tml

dbtGenerateTml

POST /api/rest/2.0/dbt/generate-tml

dbtSearch

POST /api/rest/2.0/dbt/search

deactivateUser

POST /api/rest/2.0/users/deactivate

deleteCalendar

POST /api/rest/2.0/calendars/{calendar_identifier}/delete

deleteConfig

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

deleteConnection

POST /api/rest/2.0/connection/delete

deleteConnectionConfiguration

POST /api/rest/2.0/connection-configurations/delete

deleteConnectionV2

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

deleteCustomAction

POST /api/rest/2.0/customization/custom-actions/{custom_action_identifier}/delete

deleteDbtConnection

POST /api/rest/2.0/dbt/{dbt_connection_identifier}/delete

deleteEmailCustomization

POST /api/rest/2.0/customization/email/{template_identifier}/delete

deleteMetadata

POST /api/rest/2.0/metadata/delete

deleteOrg

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

deleteOrgEmailCustomization

POST /api/rest/2.0/customization/email/delete

deleteRole

POST /api/rest/2.0/roles/{role_identifier}/delete

deleteSchedule

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

deleteTag

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

deleteUser

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

deleteUserGroup

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

deleteVariable

POST /api/rest/2.0/template/variables/{identifier}/delete

deployCommit

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

downloadConnectionMetadataChanges

POST /api/rest/2.0/connections/download-connection-metadata-changes/{connection_identifier}

exportAnswerReport

POST /api/rest/2.0/report/answer

exportLiveboardReport

POST /api/rest/2.0/report/liveboard

exportMetadataTML

POST /api/rest/2.0/metadata/tml/export

exportMetadataTMLBatched

POST /api/rest/2.0/metadata/tml/export/batch

fetchAnswerData

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

fetchAnswerSqlQuery

POST /api/rest/2.0/metadata/answer/sql

fetchAsyncImportTaskStatus

POST /api/rest/2.0/metadata/tml/async/status

fetchColumnSecurityRules

POST /api/rest/2.0/security/column/rules/fetch

fetchConnectionDiffStatus

POST /api/rest/2.0/connections/fetch-connection-diff-status/{connection_identifier}

fetchLiveboardData

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

fetchLiveboardSqlQuery

POST /api/rest/2.0/metadata/liveboard/sql

fetchLogs

POST /api/rest/2.0/logs/fetch

fetchPermissionsOfPrincipals

POST /api/rest/2.0/security/principals/fetch-permissions

fetchPermissionsOnMetadata

POST /api/rest/2.0/security/metadata/fetch-permissions

forceLogoutUsers

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

generateCSV

POST /api/rest/2.0/calendars/generate-csv

getCurrentUserInfo

GET /api/rest/2.0/auth/session/user

getCurrentUserToken

GET /api/rest/2.0/auth/session/token

getCustomAccessToken

POST /api/rest/2.0/auth/token/custom

getFullAccessToken

POST /api/rest/2.0/auth/token/full

getObjectAccessToken

POST /api/rest/2.0/auth/token/object

getSystemConfig

GET /api/rest/2.0/system/config

getSystemInformation

GET /api/rest/2.0/system

getSystemOverrideInfo

GET /api/rest/2.0/system/config-overrides

importMetadataTML

POST /api/rest/2.0/metadata/tml/import

importMetadataTMLAsync

POST /api/rest/2.0/metadata/tml/async/import

importUserGroups

POST /api/rest/2.0/groups/import

importUsers

POST /api/rest/2.0/users/import

login

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

logout

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

parameterizeMetadata

POST /api/rest/2.0/metadata/parameterize

publishMetadata

POST /api/rest/2.0/security/metadata/publish

queryGetDecomposedQuery

POST /api/rest/2.0/ai/analytical-questions

resetUserPassword

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

revertCommit

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

revokeToken

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

searchCalendars

POST /api/rest/2.0/calendars/search

searchCommits

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

searchConfig

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

searchConnection

POST /api/rest/2.0/connection/search

searchCustomActions

POST /api/rest/2.0/customization/custom-actions/search

searchData

POST /api/rest/2.0/searchdata

searchEmailCustomization

POST /api/rest/2.0/customization/email/search

searchMetadata

POST /api/rest/2.0/metadata/search

searchOrgs

POST /api/rest/2.0/orgs/search

searchRoles

POST /api/rest/2.0/roles/search

searchSchedules

POST /api/rest/2.0/schedules/search

searchTags

POST /api/rest/2.0/tags/search

searchUserGroups

POST /api/rest/2.0/groups/search

searchUsers

POST /api/rest/2.0/users/search

searchVariables

POST /api/rest/2.0/template/variables/search

sendMessage

POST /api/rest/2.0/ai/conversation/{conversation_identifier}/converse

shareMetadata

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

singleAnswer

POST /api/rest/2.0/ai/answer/create

unassignTag

POST /api/rest/2.0/tags/unassign

unparameterizeMetadata

POST /api/rest/2.0/metadata/unparameterize

unpublishMetadata

POST /api/rest/2.0/security/metadata/unpublish

updateCalendar

POST /api/rest/2.0/calendars/{calendar_identifier}/update

updateColumnSecurityRules

POST /api/rest/2.0/security/column/rules/update

updateConfig

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

updateConnection

POST /api/rest/2.0/connection/update

updateConnectionConfiguration

POST /api/rest/2.0/connection-configurations/{configuration_identifier}/update

updateConnectionV2

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

updateCustomAction

POST /api/rest/2.0/customization/custom-actions/{custom_action_identifier}/update

updateDbtConnection

POST /api/rest/2.0/dbt/update-dbt-connection

updateEmailCustomization

POST /api/rest/2.0/customization/email/update

updateMetadataHeader

POST /api/rest/2.0/metadata/headers/update

updateMetadataObjId

POST /api/rest/2.0/metadata/update-obj-id

updateOrg

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

updateRole

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

updateSchedule

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

updateSystemConfig

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

updateTag

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

updateUser

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

updateUserGroup

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

updateVariable

POST /api/rest/2.0/template/variables/{identifier}/update

updateVariableValues

POST /api/rest/2.0/template/variables/update

validateEmailCustomization

POST /api/rest/2.0/customization/email/validate

validateMerge

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

validateToken

POST /api/rest/2.0/auth/token/validate

© 2025 ThoughtSpot Inc. All Rights Reserved.