The Data API will help you do the following:
Integrate your SwipeGuide data with your visualization and storage systems, like Grafana, Power BI, Snowflake, or Tableau.
Extract all relevant data from SwipeGuide to your data lake (eg. Azure) for custom reporting. Streamline your data to improve processes and keep higher management informed about progress directly in your centralized reporting.
Streamline your data to improve processes and keep management informed about progress directly in your centralized reporting.
Data API is an add-on to Knowledge Analytics. Please contact your Customer Success Manager for more details.
Cost: $160/workspace/month (with max. 10.000 API calls per month)
Getting Started
Our REST API can be used for extracting data in JSON format.
To get started, we will share with you a user_identifier and authorization token so you're able to access the API. Please contact your Customer Success Manager for more details.
Note: This document refers to the V1 SwipeGuide Data API. As we learn more about the needs of our users, we may make upgrades that include breaking changes. These changes will be announced in advance so there is not unexpected downtime in the connection.
Authentication
We use an Oauth 2.0 bearer token authentication method, which provides a secure way to access your data. Your REST client requires a bearer access token to authenticate to the API. The access token is a string, which you must include in the Authorization header to authorize your API requests (see Retrieve Data). In order to receive an authentication token, please reach out to your SwipeGuide customer success manager.
At any point in time you have control to revoke the token and request a new one (see Revoke a Token below)
Note: By default, the bearer token is valid for 6 months. We can configure the token expiry duration as per your requirement or you may request a new token for your API sessions. If you send an API request with an expired token, the server returns an error. In consultation, we can offer the ability to create your own tokens via basic authentication (username and password) with the understanding that this method is slightly less secure.
Revoke a token
To revoke a token, send a POST request with the following attributes to the /api/rest/2.0/auth/token/revoke endpoint.
Request parameters
Parameter | Description |
| String. GUID of the user |
| String. Token issued for the user specified in |
Example request
cURL
curl -X POST \
--url 'https://swipeguide.thoughtspot.cloud/api/rest/2.0/auth/token/revoke' \
-H 'Authorization: Bearer {access_token}'\
-H 'Content-Type: application/json' \
--data-raw '{
"user_identifier": "{user_identifier}",
"token": "{access_token}"
}'
Request URL
https://swipeguide.thoughtspot.cloud/api/rest/2.0/auth/token/revoke
Example response
If the API request is successful, the access token is revoked, and the current user session becomes invalid. Before making another API call, you must obtain a new token.
Response codes
HTTP status code | Description |
204 | Successful token revocation |
400 | Invalid request |
401 | Unauthorised access |
403 | Forbidden access |
500 | Failed operation or unauthorised request |
Retrieve Data
You may search for data from a data source (see Data Sources) by passing query strings in the API request. Requests include several components for a successful query.
Components of a Call Request
Endpoint URL
POST /api/rest/2.0/searchdata
Example Request
curl -X POST \
--url 'https://swipeguide.thoughtspot.cloud/api/rest/2.0/searchdata' \
-H 'Authorization: Bearer {access_token}'\
-H 'Accept: application/json'\
-H 'Content-Type: application/json' \
--data-raw '{
"query_string": "[Workspace Name] [Guide Id]",
"logical_table_identifier": "2cb84f36-fc25-4fd0-8f71-2a8d2e65089f",
"data_format": "COMPACT",
"record_offset": 0,
"record_size": 10
}'
Example Response
{
"contents": [
{
"available_data_row_count": 2,
"column_names": [
"key1",
"key2"
],
"data_rows": [
[
"value1",
"value2"
],
[
"value1",
"value2"
]
],
"record_offset": 0,
"record_size": 10,
"returned_data_row_count": 2,
"sampling_ratio": 1
}
]
}
Request Headers
Each API call must include the following headers.
Key | Value | Description |
Authorization | Bearer {access_token} | The authorization header must include the OAuth token obtained from SwipeGuide. Replace the text "{access_token}" with the provided OAuth token |
Content-Type | application/json | The header to indicate the content type for the request body. |
Accept | application/json | The Accept header for API response format. |
User-Agent | See Description | 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 must 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>'. |
X-Requested-By | ThoughtSpot | Optional: Some clients such as Azure Data Factory can fail to call the API without this header |
Request Body
Each API call must include the following body elements.
Name | Description |
query_string REQUIRED | String. Data search query string token. (See Construct your “query_string”) |
logical_table_identifier REQUIRED | String. GUID of the data source object. (See Data Sources) |
data_format | Data Format. JSON output format
Default: COMPACT |
record_offset | Number. The starting record number from where the records should be included. (See Response Pagination)
Default: 0 |
record_size | Number. The number of records to include in a batch. (See Response Pagination)
Default: 10 |
Response codes
HTTP status code | Description |
204 | Successful token revocation |
400 | Invalid request |
401 | Unauthorised access |
403 | Forbidden access |
500 | Unexpected error |
Construct your “query_string”
Data Columns
Column names being queried must be enclosed in square brackets [ ] and separated by a space. The input is case-insensitive.
For example, in the query to retrieve all workspace names and guide titles in those workspaces, a valid query_string for the API is:
[Workspace Name] [Guide Title]
Date Buckets
When using the API, the bucket size of date fields being queried must be explicitly included, otherwise an unpredictable response will be retrieved. Use a period to separate the column with which the date bucket is bound, and the date bucket token.
For example, when querying guide title and the creation timestamp, the query_string for the API is:
[Guide Title] [Guide Created At].detailed
Alternatively, a query_string for guide title and the month it was created at would be:
[Guide Title] [Guide Created At].monthly
Date Bucket | Description |
detailed | Fully detailed timestamp in UTC. Returns in Unix time |
hourly | Truncated hourly |
daily | Truncated daily |
monthly | Truncated monthly |
quarterly | Truncated quarterly |
yearly | Truncated yearly |
Filter Response
The REST API supports various operators such as =, !=, >, >=, <=, <, contains, not contains.
For example, in a query to retrieve all guide titles and instructions titles from the ‘Amsterdam’ workspace, a valid query_string for the API is:
[Guide Title] [Instruction Title] [Workspace Name] = 'Amsterdam'
Alternatively with filter at front of query:
[Workspace Name] = 'Amsterdam' [Guide Title] [Instruction Title]
When filtering by date, the filter format should be ‘MM/DD/YYYY’
[Guide Created At] >= '06/18/2023' [Guide Title] [Instruction Title]
Combine filters by separating by a space:
[Workspace Name] = 'Amsterdam' [Guide Created At] >= '06/18/2023' [Guide Title] [Instruction Title]
Sort Response
The REST API supports sorting of the response. This can be especially useful when parsing through paginated results (see Response Pagination).
For example, in a query to retrieve all workspace names and IDs, sorted by workspace name, a valid query_string for the API is:
[Workspace Name] [Workspace Id] sort by [Workspace Name]
Response Pagination
When you make REST API calls, the APIs may return many rows of data in response. You can paginate the JSON response and retain the order of data across all pages. Given the ability to paginate, you can quickly populate tables and make new REST calls every time you go to the next page of the data on the table. There can be significant load time if you want to populate the data table with many rows (greater than 1000).
Note: The REST API has a limit of 100,000 rows per response, so queries that result in more rows will return truncated results. Pagination allows you to programmatically address this.
Paginated queries must be sorted to ensure consistent query behavior. The following query gives all values for [Guide Title] sorted by [Guide Created At] and filtered on [Guide Created At] >= '06/18/2023':
[Guide Title] sort by [Guide Created At] [Guide Created At] >= '06/18/2023'
For some data sources, a field called [Pagination Timestamp] is available to help you retrieve only the most recently updated or added rows. This is calculated on the finest level of detail in the underlying table, so it is most useful when querying at that level of granularity, as in when copying bulk data to a data warehouse.
To paginate results in your API response, adjust the following body components in the query:
Name | Description |
record_offset | Number. The starting record (row) number from where the records should be included in the query results.
Default: 0 |
record_size | Number. The number of records to include in a batch.
Default: 10 |
The following call retrieves all values of [Step Text] and [Step Id], sorted by [Step Updated At]. The record_size value limits the response to 10 rows and the record_offset value skips to the 870th record in the underlying sorted data.
curl -X POST \
--url 'https://swipeguide.thoughtspot.cloud/api/rest/2.0/searchdata' \
-H 'Authorization: Bearer {access_token}'\
-H 'Accept: application/json'\
-H 'Content-Type: application/json' \
--data-raw '{
"query_string": "[Step Text] [Step Id] sort by [Step Updated At]",
"logical_table_identifier": "28780726-141c-4a91-aac1-6606f6905fc8",
"data_format": "COMPACT",
"record_offset": 870,
"record_size": 10
}'
Data Sources
Below are the available data sources that can be accessed via the API. Each has a logical_table_identifier that is used when retrieving data (see Retrieve Data).
You can find the details on data field availability and descriptions per source in our Data Glossary.
Content
logical_table_identifier: 2cb84f36-fc25-4fd0-8f71-2a8d2e65089f
Contains data regarding instructional content that is created in SwipeGuide
Events
logical_table_identifier: ebe1aaf3-eb0f-4c23-a743-b3364a78bf33
Contains data regarding page view events of the content
Checklists
logical_table_identifier: f727b950-03cd-439f-989d-bc8c5a9a45ba
Contains checklist submission results and the content they are tied to
Sign-offs
logical_table_identifier: dc8cc054-42a2-4258-b363-5017f99326c9
Contains sign-off responses and the content they are tied to
Feedbacks
logical_table_identifier: ec0d1566-e255-4d90-9f21-e40c4d0a0cff
Contains content content feedback submitted by viewers
Tags
logical_table_identifier: 8fc7d097-b7df-41d7-bccb-9abe44387a0c
Contains content tags
Users & Teams
logical_table_identifier: 22482696-5234-44cd-aae8-835c586a4919
Contains users and their associated teams and workspaces