Use the Metadata APIs to fetch ThoughtSpot visualization and object headers.

The metadata API service allows you to fetch metadata details for various objects in the ThoughtSpot system. For example, you may want to see the visualization headers of a particular visualization or a pinboard.

Get object headers

To query metadata objects headers for a data type in the Thoughtspot system, use the /tspublic/v1/metadata/listobjectheaders API.

Resource URL

GET /tspublic/v1/metadata/listobjectheaders

Request parameters

Query Parameter Data Type Description

type Optional

string

Type of the metadata object. To query data for specific object type, set the metadata object type to one of the following values:

  • QUESTION_ANSWER_BOOK for search answers.

  • PINBOARD_ANSWER_BOOK for pinboards.

  • LOGICAL_COLUMN for a column of any data object such as tables, worksheets, or views.

  • LOGICAL_TABLE for any data object such as a table, worksheet, or view.

  • LOGICAL_RELATIONSHIP for table or worksheet joins. A join combines columns from one or several data objects by using matching values.

  • TAG for tags assigned to a metadata object.

  • DATA_SOURCE for data source from which the metadata objects were loaded.

**NOTE**: The QUESTION_ANSWER_SHEET and PINBOARD_ANSWER_SHEET metadata object types are deprecated.

subtypes Optional

string

Specifies the sub-types of a metadata object. If you have specified the metadata object type as LOGICAL_TABLE, you can query data objects of a specific subtype.

  • ONE_TO_ONE_LOGICAL for tables

  • WORKSHEET for worksheets. A worksheet is a collection of related tables.

  • USER_DEFINED for tables uploaded from a CSV file.

  • AGGR_WORKSHEET for Views. A View in ThoughtSpot refers to a table materialized from a search answer that was saved as a View by a user.

The PRIVATE_WORKSHEET metadata sub-type is deprecated.

category Optional

string

The metadata object classification. In ThoughtSpot, metadata objects such as search answers and pinboards are categorized under All, Yours, and Favorites. To query data for an object based on category, set one of the following values:

  • ALL to get all objects for a given metadata type, for example, search answers or pinboards.

  • MY to get the objects created or saved by the current logged in user.

  • FAVORITE to get a list of objects marked as favorites by the current logged in user.

  • REQUESTED to get only the objects requested by the current logged in user.

sort Optional

string

The sort order for the headers returned by the API. Valid values are:

  • DEFAULT

  • NAME

  • DISPLAY_NAME

  • AUTHOR

  • CREATED

  • MODIFIED

sortascending Optional

boolean

A flag to specify the sort order. A null value defines the default order.

  • To set an ascending order, specify true.

  • To set a descending order, specify false.

offset Optional

integer

The batch offset to fetch the page headers. The system default is -1, which implies first page.

batchsize Optional

integer

The batch size of the object. A value of -1 implies no pagination.

tagname Optional

string

A JSON array containing a set of tag names to filter headers by.

pattern Optional

string

A pattern to match object name. Use `%`for a wildcard match.

skipids Optional

string

A JSON array containing the GUIDs of the metadata objects that you want to exclude.

fetchids

string

A JSON array containing the GUIDs of the metadata objects that you want to fetch.

auto_created Optional

boolean

A flag to indicate whether to list only the auto-created objects. A value of null returns all objects.

Example request

cURL
curl -X GET --header 'Accept: application/json' --header 'X-Requested-By: ThoughtSpot' 'https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/metadata/listobjectheaders?type=PINBOARD_ANSWER_BOOK&subtypes=WORKSHEET&category=ALL&sort=CREATED&offset=-1'
Request URL
https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/metadata/listobjectheaders?type=PINBOARD_ANSWER_BOOK&subtypes=WORKSHEET&category=ALL&sort=CREATED&offset=-1

Example response

[
  {
    "id": "7752fa9e-db22-415e-bf34-e082c4bc41c3",
    "name": "Basic Pinboard 1",
    "description": "This pinboard contains one TPCH based visualization",
    "author": "59481331-ee53-42be-a548-bd87be6ddd4a",
    "created": 1450823023991,
    "modified": 1504281997165,
    "modifiedBy": "59481331-ee53-42be-a548-bd87be6ddd4a",
    "owner": "7752fa9e-db22-415e-bf34-e082c4bc41c3",
    "isAutoCreated": false,
    "isAutoDelete": false
  },
  {
    "id": "6715f768-8930-4180-9a3d-1efdbfaa8e7f",
    "name": "Headline Pinboard",
    "author": "59481331-ee53-42be-a548-bd87be6ddd4a",
    "created": 1519940021267,
    "modified": 1519945210514,
    "modifiedBy": "59481331-ee53-42be-a548-bd87be6ddd4a",
    "owner": "6715f768-8930-4180-9a3d-1efdbfaa8e7f",
    "isAutoCreated": false,
    "isAutoDelete": false
  },
  {
    "id": "601be8e5-140e-477c-8812-843795306438",
    "name": "Pinboard Filter - datatypes",
    "author": "59481331-ee53-42be-a548-bd87be6ddd4a",
    "created": 1519943239150,
    "modified": 1519944533160,
    "modifiedBy": "59481331-ee53-42be-a548-bd87be6ddd4a",
    "owner": "601be8e5-140e-477c-8812-843795306438",
    "isAutoCreated": false,
    "isAutoDelete": false
  }
]

Response codes

HTTP Code Description
200 Successful retrieval of metadata headers

Get visualization headers

To get a list of visualization headers from the ThoughtSpot system, you can use the /tspublic/v1/metadata/listvizheaders API. The API returns a list of visualizations for a given pinboard or a search answer.

Resource URL

GET /tspublic/v1/metadata/listvizheaders

Request parameters

Query Parameter Data Type Description
id string ID of a particular answer or a pinboard.

Example request

cURL
curl -X GET --header 'Accept: application/json' --header 'X-Requested-By: ThoughtSpot' 'https://<instance>/callosum/v1/tspublic/v1/metadata/listvizheaders?id=97begg839e-71b6-42ad-a980-20c38b4d6db5'
Request URL
https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/metadata/listvizheaders?id=97be839e-71b6-42ggad-a980-20c38b4d6db5

Example response

[
  {
    "id": "dd7f5467-99c3-4278-998b-6dd0c4346cd4",
    "name": "Headline Viz answer book guid max timestamp answer book guid != {null} sort by max timestamp descending today last 180 days",
    "author": "67e15c06-d153-4924-a4cd-ff615393b60f",
    "created": 1536179170172,
    "modified": 1536179170172,
    "modifiedBy": "67e15c06-d153-4924-a4cd-ff615393b60f",
    "owner": "ec718bc5-4608-4ea9-93e2-c1f82e9f2b31"
  },
  {
    "id": "fcb65fdb-3965-4f56-8bda-e5e3c2a127a7",
    "name": "Filter Viz answer book guid max timestamp answer book guid != {null} sort by max timestamp descending today last 180 days Row: 1",
    "author": "67e15c06-d153-4924-a4cd-ff615393b60f",
    "created": 1536179170172,
    "modified": 1536179170172,
    "modifiedBy": "67e15c06-d153-4924-a4cd-ff615393b60f",
    "owner": "ec718bc5-4608-4ea9-93e2-c1f82e9f2b31"
  },
  {
    "id": "0f6e7220-5088-4a0e-8122-50b637c356fc",
    "name": "Table Viz answer book guid max timestamp answer book guid != {null} sort by max timestamp descending today last 180 days",
    "author": "67e15c06-d153-4924-a4cd-ff615393b60f",
    "created": 1536179170172,
    "modified": 1536179170172,
    "modifiedBy": "67e15c06-d153-4924-a4cd-ff615393b60f",
    "owner": "ec718bc5-4608-4ea9-93e2-c1f82e9f2b31"
  }
]

Response codes

HTTP status code Description
200 Successful retrieval of visualization headers
400 Invalid pinboard GUID

Get metadata objects for a user or user group

Use the /tspublic/v1/metadata/listas API to get a list of metadata objects available for a user or user group.

Resource URL

GET /tspublic/v1/metadata/listas

Request parameters

Query Parameter Data Type Description

offset Optional

integer

The batch offset value that indicates the first item to return in a page of headers. The system default is -1, which implies first page.

batchsize Optional

integer

The batch size of the objects. A value of -1 implies no pagination.

pattern Optional

string

The pattern to match object names. Use % for a wildcard match.

principalid Optional

string

ID of the user or user group.

  • If you specify a userID and set the type parameter to USER, the API returns metadata objects associated with the user ID.

  • If you specify a user group ID and set the type parameter to USER_GROUP, the API returns metadata objects for all the users mapped to the specified user group.

  • If the principalID parameter is not defined, but the type attribute is set to USER, the API returns metadata objects for the current logged-in user.

  • If the principalID parameter is not defined, but the type attribute is set to USER_GROUP, the API returns metadata objects for all user groups.

  • If both principalID and type parameters are not defined, the API returns headers for all users.

minimumaccesslevel Optional

string

Minimum access level that the specified user or user group has. Valid values are:

  • NO_ACCESS

  • READ_ONLY

  • MODIFY

The default value is NO_ACCESS.

type Optional

string

Type of principal. The allowed values are USER and USER_GROUP.

Example request

##### cURL
curl -X GET --header 'Accept: application/json' --header 'X-Requested-By: ThoughtSpot' 'https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/metadata/listas?offset=-1&pattern=%25&principalid=13bb9aec-aad0-4075-adb9-bd0569351393&minimumaccesslevel=READ_ONLY&type=USER'
##### Request URL
https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/metadata/listas?offset=-1&pattern=%25&principalid=13bb9aec-aad0-4075-adb9-bd0569351393&minimumaccesslevel=READ_ONLY&type=USER

Example response

The following example shows the headers for user groups:

{
  "headers": [
    {
      "id": "eea322db-2b8c-4bb7-922d-a80807a0ba94",
      "indexVersion": 5,
      "generationNum": 1471,
      "name": "Stats and Trends for Search on Answers",
      "description": "This pinboard describes how users are searching for existing answers.",
      "author": "67e15c06-d153-4924-a4cd-ff615393b60f",
      "authorName": "system",
      "authorDisplayName": "System User",
      "created": 1604579772176,
      "modified": 1618858656671,
      "modifiedBy": "67e15c06-d153-4924-a4cd-ff615393b60f",
      "owner": "eea322db-2b8c-4bb7-922d-a80807a0ba94",
      "isDeleted": false,
      "isHidden": false,
      "isAutoCreated": false,
      "isAutoDelete": false,
      "tags": [],
      "isExternal": false,
      "isDeprecated": false
    },
    {
      "id": "9d789a9e-12a7-4b00-91de-e558b590d192",
      "indexVersion": 1217,
      "generationNum": 1217,
      "name": "test table 2",
      "author": "59481331-ee53-42be-a548-bd87be6ddd4a",
      "authorName": "tsadmin",
      "authorDisplayName": "Administrator",
      "created": 1618463063893,
      "modified": 1618463113058,
      "modifiedBy": "59481331-ee53-42be-a548-bd87be6ddd4a",
      "owner": "9d789a9e-12a7-4b00-91de-e558b590d192",
      "isDeleted": false,
      "isHidden": false,
      "isAutoCreated": false,
      "isAutoDelete": false,
      "tags": [],
      "isExternal": false,
      "isDeprecated": false
    }
  ],
  "isLastBatch": true,
  "debugInfo": {}
}

The following example shows the headers returned for a user:

{
  "headers": [
    {
      "id": "b27d4ce9-0220-4238-b0b0-917ee18147df",
      "indexVersion": 1494,
      "generationNum": 1494,
      "name": "Sales Performance",
      "description": "",
      "author": "59481331-ee53-42be-a548-bd87be6ddd4a",
      "authorName": "tsadmin",
      "authorDisplayName": "Administrator",
      "created": 1614677491805,
      "modified": 1619648685627,
      "modifiedBy": "59481331-ee53-42be-a548-bd87be6ddd4a",
      "owner": "b27d4ce9-0220-4238-b0b0-917ee18147df",
      "isDeleted": false,
      "isHidden": false,
      "isAutoCreated": false,
      "isAutoDelete": false,
      "tags": [],
      "isExternal": false,
      "isDeprecated": false
    },
    {
      "id": "8161e7ab-8ada-43ae-9627-f9b76dd85d27",
      "indexVersion": 1490,
      "generationNum": 1490,
      "name": "Copy of Sales Performance",
      "description": "",
      "author": "59481331-ee53-42be-a548-bd87be6ddd4a",
      "authorName": "tsadmin",
      "authorDisplayName": "Administrator",
      "created": 1619644750652,
      "modified": 1619644750652,
      "modifiedBy": "59481331-ee53-42be-a548-bd87be6ddd4a",
      "owner": "8161e7ab-8ada-43ae-9627-f9b76dd85d27",
      "isDeleted": false,
      "isHidden": false,
      "isAutoCreated": false,
      "isAutoDelete": false,
      "tags": [],
      "isExternal": false,
      "isDeprecated": false
    },
    {
      "id": "eea322db-2b8c-4bb7-922d-a80807a0ba94",
      "indexVersion": 5,
      "generationNum": 1471,
      "name": "Stats and Trends for Search on Answers",
      "description": "This pinboard describes how users are searching for existing answers. It provides what users are searching for, where users are successful and where they are not.",
      "author": "67e15c06-d153-4924-a4cd-ff615393b60f",
      "authorName": "system",
      "authorDisplayName": "System User",
      "created": 1604579772176,
      "modified": 1618858656671,
      "modifiedBy": "67e15c06-d153-4924-a4cd-ff615393b60f",
      "owner": "eea322db-2b8c-4bb7-922d-a80807a0ba94",
      "isDeleted": false,
      "isHidden": false,
      "isAutoCreated": false,
      "isAutoDelete": false,
      "tags": [],
      "isExternal": false,
      "isDeprecated": false
    },

    {
      "id": "7e4071e5-6223-4ccd-a839-2621e5d8201e",
      "indexVersion": 1230,
      "generationNum": 1470,
      "name": "Sales Breakdown",
      "description": "",
      "author": "59481331-ee53-42be-a548-bd87be6ddd4a",
      "authorName": "tsadmin",
      "authorDisplayName": "Administrator",
      "created": 1618469015915,
      "modified": 1618469413741,
      "modifiedBy": "59481331-ee53-42be-a548-bd87be6ddd4a",
      "owner": "7e4071e5-6223-4ccd-a839-2621e5d8201e",
      "isDeleted": false,
      "isHidden": false,
      "isAutoCreated": false,
      "isAutoDelete": false,
      "tags": [
        {
          "id": "bde9b681-01e8-4156-bf86-170f6cb7d7ab",
          "indexVersion": 2045,
          "generationNum": 2045,
          "name": "Sales",
          "author": "59481331-ee53-42be-a548-bd87be6ddd4a",
          "created": 1621312956892,
          "modified": 1621312957239,
          "modifiedBy": "59481331-ee53-42be-a548-bd87be6ddd4a",
          "owner": "bde9b681-01e8-4156-bf86-170f6cb7d7ab",
          "isDeleted": false,
          "isHidden": false,
          "clientState": {
            "color": "#63c9ea"
          },
      "tags": [],
      "isExternal": false,
      "isDeprecated": false
    },

  ],
  "isLastBatch": true,
  "debugInfo": {}
}

Response codes

HTTP status code Description
200 Successful retrieval of metadata headers
401 Unauthorized request
404 The requested resource could not be found

Assign tags to metadata objects

Tags are labels that you can apply to a Thoughtspot object, such as a pinboard or search answer. You can use tags to find and filter your answers, pinboards, and data objects.

To apply a tag to a ThoughtSpot object programmatically, you can use the /tspublic/v1/metadata/assigntag API.

Before you apply a tag, make sure the tags are created and available for assignment.

Resource URL

    POST /tspublic/v1/metadata/assigntag

Request parameters

Query Parameter Data Type Description

id

string

The GUID of the metadata object to tag. For example, a pinboard or visualization. If you want to assign the same tag to several objects, specify the GUID of the metadata objects.

type Optional

string

Type of the metadata object. Specify one of the following values as a metadata object type:

  • QUESTION_ANSWER_BOOK for search answers.

  • PINBOARD_ANSWER_BOOK for pinboards.

  • LOGICAL_COLUMN for a column of any data object such as tables, worksheets, or views.

  • LOGICAL_TABLE for any data object such as a table, worksheet, or view.

tagid

string

The GUID of tag to assign.

Example request

cURL
curl -X POST --header 'Content-Type: application/x-www-form-urlencoded' --header 'Accept: application/json' --header 'X-Requested-By: ThoughtSpot' -d 'id=%5B%225772aaf1-555d-44c4-a24c-ae6fba6684c3%22%5D&type=%5B%22QUESTION_ANSWER_BOOK%22%5D&tagid=%5B%22c4db6274-dec3-4902-ba0e-493734fef9c0%22%5D' 'https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/metadata/assigntag'
Request URL
    https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/metadata/assigntag

Example response

    Response code

    204

Response codes

HTTP code Description
204 Successful application of tag to a metadata object
400 Invalid parameter value
500 Invalid metadata object ID