Get started with REST API v1

Table of Contents

API Explorer
Authentication
API requests and response

Before you start using REST APIs, perform the following checks:

Your client application domain is added as a Cross-Origin Resource Sharing (CORS) host in the ThoughtSpot Developer portal.

Note that after you add your host domain for CORS, ThoughtSpot adds the access-control-allow-origin header in its API responses.
You have valid login credentials and access privileges to run the operations.

API Explorer🔗

You can access the REST API v1 explorer using one of the following options:

Using the REST Playground v1 menu option in the Develop page (Requires Developer or Administrator privilege)
Try it out
Using the Swagger URL
```
https://<your-thoughtspot.com>/external/swagger
```
The REST API v1 Explorer displays a list of REST API services available for the logged-in ThoughtSpot users.

To make an API call and view results:
1. Click the API service category and view a list of endpoints.
2. Click on the endpoint to which you want to send an API request.
3. If required, define the attributes.
4. Click Try it out and verify the API response and HTTP status code.

Authentication🔗

To create, access, and modify ThoughtSpot objects and resources using the REST API, you must log in as an authorized user.

When using the REST API through a web browser, we recommend that you use the SAML SSO or trusted authentication service to authenticate to ThoughtSpot.

Any completed log-in process will return session cookies from the ThoughtSpot system, which must be included with any subsequent REST API call.

For more information, see Authentication.

API requests and response🔗

To call a REST API, send a request to the endpoint URL with the attributes required to create, view, or modify an object.

Request method🔗

Specify the HTTP request method in your API request.

GET to query information, such as getting a list of users or groups.
POST to create and add new properties to a resource, such as a user, group, Answer, Worksheet, or data object.
PUT to update the properties of an existing resource, such as modifying the properties of a user or user group.
DELETE to remove an object or object association.

Some endpoints may require you to send a POST request for delete or update operation. For more information about the endpoint URIs and request methods, see REST API v1 Reference.

Request headers🔗

X-Requested-By

Make sure you include the 'X-Requested-By: ThoughtSpot' header in all API requests.

User-Agent

The User-Agent header is required for all requests. Most clients will add the User-Agent header automatically. However, when making API calls from code, especially .NET, you need to add the User-Agent header.

The User-Agent can be any string; for example, you can set the header as 'User-Agent: <browser>/<browser-version><os/platform>'.

Accept

Use this header to specify the content type for the API responses. You can set it to 'Accept: application/json' for JSON and 'Accept: text/plain' for plain text responses.

Content-Type

Use this header to indicate the content type to use in the request body. Set this header as 'Content-Type: application/json'.

Some POST operations, such as sharing an object with another user, require the URL-encoded objects to be passed as parameters in the URL. For such API requests, set the header as 'Content-Type: application/x-www-form-urlencoded'.
For some endpoints, such as /tspublic/v1/user/sync, you need to send the request body as separate blocks of data or as a JSON file in POST requests. For APIs that require multiple blocks of data, set the header as 'Content-Type: multipart/form-data'.

For more information, see the example requests in the API reference articles.

Request parameters🔗

Some API endpoints allow you to send attributes as query parameters in POST requests. For example, the /tspublic/v1/metadata/listobjectheaders API endpoint passes request parameters as a query string in the URL.

For object creation or update operations (POST and PUT requests), you may need to send formData attributes as a JSON array of strings or as a JSON map of key-value pairs in the request body. Make sure you specify the attributes in the format recommended in the Swagger UI and REST API v1 Reference.

Object IDs🔗

All ThoughtSpot objects and resources are assigned a Globally Unique Identifier (GUID) by default. Most endpoints require you to specify the GUID to access, query, or modify a specific object. You can query the metadata list to get a list of objects of a specific type and the GUIDs assigned to each of these objects.

For example, you can use the /tspublic/v1/metadata/listvizheaders endpoint to get a list of the Liveboards and their GUIDs:

[
{
   "id":"d084c256-e284-4fc4-b80c-111cb606449a",
   "name":"Sales Performance",
   "description":"",
   "author":"67e15c06-d153-4924-a4cd-ff615393b60f",
   "created":1642560047638,
   "modified":1642560047638,
   "modifiedBy":"67e15c06-d153-4924-a4cd-ff615393b60f",
   "owner":"d084c256-e284-4fc4-b80c-111cb606449a",
   "isAutoCreated":false,
   "isAutoDelete":false
},
{
   "id":"74852035-9624-4fac-b352-200fa8506b14",
   "name":"Object Usage",
   "description":"",
   "author":"67e15c06-d153-4924-a4cd-ff615393b60f",
   "created":1620198465429,
   "modified":1620198473992,
   "modifiedBy":"67e15c06-d153-4924-a4cd-ff615393b60f",
   "owner":"74852035-9624-4fac-b352-200fa8506b14",
   "isAutoCreated":false,
   "isAutoDelete":false
}
]

Data format🔗

The REST APIs allow you to send and receive data in JSON format. To embed this data in your application, you can import or extract the data from the JSON file.

Date format in API response🔗

If Custom Calendar is not enabled on your instance, the API output shows the date and time data in Epoch time format.

[694252800,702115200,709974000,717922800,725875200,733651200,741510000,749458800,757411200,765187200,773046000,780994800,788947200,796723200,804582000,812530800,820483200,828345600,836204400,844153200,852105600,859881600,867740400,875689200,883641600,891417600,899276400,907225200]

If Custom Calendar is enabled on your instance, the data returned in the API response shows the date and time in the {"v":{"s":694252800}} format.

[{"v":{"s":694252800}},{"v":{"s":702115200}},{"v":{"s":709974000}},{"v":{"s":717922800}},{"v":{"s":725875200}},{"v":{"s":733651200}},{"v":{"s":741510000}},{"v":{"s":749458800}},{"v":{"s":757411200}},{"v":{"s":765187200}},{"v":{"s":773046000}},{"v":{"s":780994800}},{"v":{"s":788947200}},{"v":{"s":796723200}},{"v":{"s":804582000}},{"v":{"s":812530800}},{"v":{"s":820483200}},{"v":{"s":828345600}},{"v":{"s":836204400}},{"v":{"s":844153200}},{"v":{"s":852105600}},{"v":{"s":859881600}},{"v":{"s":867740400}},{"v":{"s":875689200}},{"v":{"s":883641600}},{"v":{"s":891417600}},{"v":{"s":899276400}},{"v":{"s":907225200}}]

v indicates value
s indicates the start date in Epoch time format
e indicates the end date in Epoch time format

If the API implementation in your environment is designed to use the date output in Epoch format, this change may break your current setup.

HTTP status codes🔗

For each API request, ThoughtSpot sends a response. The API returns one of the following response codes upon completing a request operation:

200

Indicates a successful operation. The API returns a response body.
204

Indicates a successful operation. The 204 response code does not include a response body.
400

Indicates a bad request. You may have to modify the request before making another call.
401

Indicates an unauthorized request. Check if you have the required credentials and object access to send the API request.
415

Indicates an unsupported media type. Check the media type specified in the Content-Type header.
500

Indicates an internal server error. Check if the data format of the request is supported. Verify if the server is available and can process the request.