# Get started with REST API v1

> For the complete documentation index, see [llms.txt](https://developers.thoughtspot.com/docs/llms.txt)

Source: https://developers.thoughtspot.com/docs/rest-api-getstarted

# Get started with REST API v1

> **IMPORTANT:** The REST API v1 endpoints are deprecated and replaced with the REST API v2 endpoints. Your existing integrations with REST API v1 endpoints will continue to function without disruption until further notice. ThoughtSpot strongly recommends migrating your integrations to the REST API v2 endpoints.

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

-   Your client application domain is added as a [Cross-Origin Resource Sharing (CORS) host]({{navprefix}}/{{security-settings}}) 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]({{previewPrefix}}/api/rest/playgroundV1)
-   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]({{navprefix}}/{{configure-saml}}) or [trusted authentication]({{navprefix}}/{{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]({{navprefix}}/{{api-auth-session}}).

## 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]({{navprefix}}/{{rest-api-reference}}).

### Request headers

<table class="tableblock frame-all grid-all stretch"><colgroup><col style="width: 20%;"> <col style="width: 80%;"></colgroup><tbody><tr><td class="tableblock halign-left valign-top"><p class="tableblock"><code>X-Requested-By</code></p></td><td class="tableblock halign-left valign-top"><p class="tableblock">Make sure you include the <code>'X-Requested-By: ThoughtSpot'</code> header in all API requests.</p></td></tr><tr><td class="tableblock halign-left valign-top"><p class="tableblock"><code>User-Agent</code></p></td><td class="tableblock halign-left valign-top"><p class="tableblock">The <code>User-Agent</code> header is required for all requests. Most clients will add the <code>User-Agent</code> header automatically. However, when making API calls from code, especially <code>.NET</code>, you need to add the <code>User-Agent</code> header.</p><p class="tableblock">The <code>User-Agent</code> can be any string; for example, you can set the header as <code>'User-Agent: &lt;browser&gt;/&lt;browser-version&gt;&lt;os/platform&gt;'</code>.</p></td></tr><tr><td class="tableblock halign-left valign-top"><p class="tableblock"><code>Accept</code></p></td><td class="tableblock halign-left valign-top"><p class="tableblock">Use this header to specify the content type for the API responses. You can set it to <code>'Accept: application/json'</code> for JSON and <code>'Accept: text/plain'</code> for plain text responses.</p></td></tr><tr><td class="tableblock halign-left valign-top"><p class="tableblock"><code>Content-Type</code></p></td><td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph"><p>Use this header to indicate the content type to use in the request body. Set this header as <code>'Content-Type: application/json'</code>.</p></div><div class="ulist"><ul><li><p>Some <code>POST</code> 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 <code>'Content-Type: application/x-www-form-urlencoded'</code>.</p></li><li><p>For some endpoints, such as <code>/tspublic/v1/user/sync</code>, you need to send the request body as separate blocks of data or as a JSON file in <code>POST</code> requests. For APIs that require multiple blocks of data, set the header as <code>'Content-Type: multipart/form-data'</code>.</p></li></ul></div><div class="paragraph"><p>For more information, see the example requests in the <a href="{{navprefix}}/{{rest-api-reference}}">API reference articles</a>.</p></div></div></td></tr></tbody></table>

### 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]({{navprefix}}/{{rest-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:

```JSON
[
{
   "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.