Get started

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

  • Your client application domain is added as a CORS host.

    This step is required if you are embedding ThoughtSpot objects using REST APIs. 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.

  • If trusted authentication is enabled on your instance, you must obtain a login token and include it in your subsequent login requests.

Swagger UI

To access REST APIs on Swagger:

  1. Sign in to your ThoughtSpot instance.

  2. Access the Swagger portal.

    To access Swagger UI, change your URL as shown here:

    https://<your-thoughtspot.com>/external/swagger

    The portal displays a list of REST API services available for the logged-in ThoughtSpot users.

  3. Select a header to expand and view the list of services.

  4. Select a service name to view more details about the API service.

  5. To explore an API, select Try it out.

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 a 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 a POST request for delete or update operation. For more information about the endpoint URIs and request methods, see REST v1 API reference.
Query string

A query string consists of additional parameters that are passed in the URL. For example, the /tspublic/v1/metadata/listobjectheaders API endpoint requires query parameters that are passed as a query string in the URL.

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 REST v1 API reference.

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 v1 API 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
}
]

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. Make sure the data format of the request is correct and check if the server is available and can process your request.

Related information

Was this page helpful?
×