Collections <sup class="beta betaBackground">Beta</sup>
Cloud
26.6.0.clCloud (Latest)
26.5.0.clCloud
26.4.0.clCloud
26.3.0.clCloud
Software
26.3.0.swSoftware (Latest)
10.10.0.swSoftware
10.1.0.swSoftware
GitHub

Collections Beta

ThoughtSpot now provides REST APIs that enable developers to organize different ThoughtSpot objects into an organizational container called Collections. These objects can be Liveboards, Answers, data models, tables, and even other Collections. Collections provide a powerful way to manage your data assets, making discovery and collaboration easier, while ensuring the integrity of embedded workflows.

Note

The Collections APIs are in Beta and disabled by default on ThoughtSpot instances. To enable these APIs on your instance, contact ThoughtSpot Support.

Before you begin🔗

  • For REST API v2 operations, the Org context is determined based on the authentication token used in your API requests. Ensure you log in to the appropriate Org context from which you want to send API requests.

  • When enabled on a ThoughtSpot instance, Collections can be created by any user, and need no special user privileges.

Create a Collection🔗

To create a new Collection, send a POST request to the POST /api/rest/2.0/collections/create API endpoint, with the following parameters in the request body.

Request parameters🔗

In your POST request body, include the following parameters:

ParameterDescription

name

String. Required. Specify a name for the Collection.

description

String. Optional. A short description for the Collection.

metadata

Array. Optional. The details for the metadata objects to be added to the Collection.

  • type
    Metadata type. Select one of the following values:

    • LIVEBOARD

    • ANSWER

    • LOGICAL_TABLE

    • COLLECTION

      To create nested collections, assign the COLLECTION metadata to a Collection.

  • identifiers
    List of unique IDs or names of metadata objects.

Example request🔗

curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/collections/create'  \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {AUTH_TOKEN}' \
  --data-raw '{
  "name": "Demo Collection",
  "metadata": [
    {
      "type": "LIVEBOARD",
      "identifiers": [
        "Retail sales (Sample)",
        "fe307a35-5242-445f-b3cb-b84cd1fc339c"
      ]
    },
    {
      "type": "COLLECTION",
      "identifiers": [
        "Collection A"
      ]
    }
  ],
  "description": "For testing"
}'

API response🔗

If the API request is successful, a Collection with the given metadata objects will be created.

Search for a Collection🔗

To get a list of Collections, send a POST request to the POST /api/rest/2.0/collections/search API endpoint.

If no parameters are specified, the API returns the first 10 collections (or fewer, depending on the total number available).

Request parameters🔗

In your POST request body, include the following parameters:

ParameterDescription

name_pattern

String. Optional. Specify any case agnostic pattern to match the name of a Collection. Use % to perform a wildcard search by name.

record_offset

Number. Optional. The index of the first record to be included. Default value is 0.

record_size

Number. Optional. The total number of records to be searched. Default value is 10. Set to -1 to search across all available collections.

collection_identifiers

Array. Optional. GUID of the Collection(s) to be searched. name_pattern takes precedence over the collection_identifiers.

created_by_user_identifiers

Array. Optional. Searches for Collections by the name of the author.

include_metadata

Boolean. Optional. When set to true, includes the metadata objects within each Collection in the response.

sort_options

Array. Optional. To sort the search results, specify the field to apply the sort on field_name, and the sort order order.

Example request🔗

curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/collections/search'  \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {AUTH_TOKEN}' \
  --data-raw '{
  "record_offset": 2,
  "record_size": 15,
  "include_metadata": false,
  "name_pattern": "%",
  "sort_options": {
    "field_name": "NAME",
    "order": "ASC"
  }
}'

API response🔗

If the API request is successful, it will return a list of Collection(s) matching the search criteria.

Update a Collection🔗

To update an existing Collection, send a POST request to the POST /api/rest/2.0/collections/{collection_identifier}/update API endpoint.

Request parameters🔗

In your POST request body, include the following parameters:

ParameterDescription

collection_identifier

Required. GUID of the Collection to be updated. collection_identifier is passed as a parameter in the API request.

name

String. Optional. New name for the Collection.

description

String. Optional. Updated or a newly added description for the Collection.

metadata

Array. Required. The details for the metadata objects to be added, removed, or replaced in the Collection.

  • type

  • identifiers

operation

Enum. Required. Specify the nature of the update. Select one of the following values:

  • ADD: Adds the specified metadata objects to the existing Collection without removing the current objects.

  • REMOVE: Removes only the specified metadata objects from the Collection.

  • REPLACE. Default: This replaces all existing objects in the Collection with the objects specified in this replace request.

Example request🔗

curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/collections/0e5fd958-cb2b-43f0-b67f-13ac5c805bad/update'  \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {AUTH_TOKEN}' \
  --data-raw '{
  "operation": "ADD",
  "metadata": [
    {
      "type": "LIVEBOARD",
      "identifiers": [
        "6fee1adb-1c50-4c15-8d49-4fe0503d0b34"
      ]
    }
  ]
}'

API response🔗

If the API request is successful, the object specified in the API request is added to the Collection.

Example request🔗

curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/collections/0e5fd958-cb2b-43f0-b67f-13ac5c805bad/update'  \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {AUTH_TOKEN}' \
  --data-raw '{
  "operation": "REMOVE",
  "metadata": [
    {
      "type": "LIVEBOARD",
      "identifiers": [
        "6fee1adb-1c50-4c15-8d49-4fe0503d0b34"
      ]
    }
  ]
}'

API response🔗

If the API request is successful, the object specified in the API request is removed from the Collection.

Example request🔗

curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/collections/0e5fd958-cb2b-43f0-b67f-13ac5c805bad/update'  \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {AUTH_TOKEN}' \
  --data-raw '{
  "operation": "REPLACE",
  "metadata": [
    {
      "type": "LIVEBOARD",
      "identifiers": [
        "6fee1adb-1c50-4c15-8d49-4fe0503d0b34",
        "87328d32-2bf0-4fc4-ac51-a738712d7e79"
      ]
    },
    {
      "type": "COLLECTION",
      "identifiers": [
        "6d85c77c-4822-42ba-8074-6306a90ba8e1"
      ]
    }
  ]
}'

API response🔗

If the API request is successful, the objects in the Collection are replaced with the objects in this API request.

Share a Collection🔗

Note

Collections sharing via the security API is available from ThoughtSpot Cloud 26.6.0.cl.

To share a Collection with a user or group, send a POST request to the POST /api/rest/2.0/security/metadata/share endpoint with metadata_type set to COLLECTION.

Collections support dual permissions that let you set independent access levels for the Collection and the objects within it.

Permission fields🔗

FieldApplies toDescription

share_mode

Collection

Controls access to the Collection itself — view, edit, or delete the Collection. Accepted values: READ_ONLY, MODIFY, NO_ACCESS.

content_share_mode

Collection content

Controls access to the objects within the Collection — Liveboards, Answers, Models, and nested Collections. Accepted values: READ_ONLY, MODIFY, NO_ACCESS.

Only applicable when metadata_type is COLLECTION. If omitted, defaults to READ_ONLY (or NO_ACCESS when share_mode is NO_ACCESS).

Permission scenarios🔗

Roleshare_modecontent_share_modeWhat the principal can do

MODIFY

MODIFY

Full control — manage the Collection and edit its contents

MODIFY

READ_ONLY

Manage the Collection structure but cannot edit objects within it

READ_ONLY

MODIFY

Edit objects within the Collection but cannot change the Collection itself

READ_ONLY

READ_ONLY

View the Collection and its contents only

Share a Collection (read-only)🔗

To share a Collection with a user in read-only mode, send the following request:

curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/security/metadata/share' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {AUTH_TOKEN}' \
  --data-raw '{
  "metadata_type": "COLLECTION",
  "metadata_identifiers": ["Sales reports"],
  "permissions": [
    {
      "principal": {
        "type": "USER",
        "identifier": "[email protected]"
      },
      "share_mode": "READ_ONLY"
    }
  ],
  "notification": {
    "message": "I have shared the Sales reports collection with you.",
    "notify_on_share": true
  }
}'

If the request is successful, the API returns the HTTP 204 No Content status code.

Share a Collection with dual permissions🔗

To give a user different levels of access to the Collection and its contents, set both share_mode and content_share_mode.

curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/security/metadata/share' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {AUTH_TOKEN}' \
  --data-raw '{
  "metadata_type": "COLLECTION",
  "metadata_identifiers": ["Marketing Analytics"],
  "permissions": [
    {
      "principal": {
        "type": "USER",
        "identifier": "[email protected]"
      },
      "share_mode": "MODIFY",
      "content_share_mode": "READ_ONLY"
    },
    {
      "principal": {
        "type": "USER_GROUP",
        "identifier": "Marketing Team"
      },
      "share_mode": "READ_ONLY",
      "content_share_mode": "READ_ONLY"
    }
  ],
  "notification": {
    "message": "Sharing the Marketing Analytics collection with your team.",
    "notify_on_share": true
  }
}'

If the request is successful, the API returns the HTTP 204 No Content status code.

Remove Collection access🔗

To remove a user’s access to a Collection, set share_mode to NO_ACCESS:

curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/security/metadata/share' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {AUTH_TOKEN}' \
  --data-raw '{
  "metadata_type": "COLLECTION",
  "metadata_identifiers": ["Confidential Reports"],
  "permissions": [
    {
      "principal": {
        "type": "USER",
        "identifier": "[email protected]"
      },
      "share_mode": "NO_ACCESS"
    }
  ]
}'

If the request is successful, the API returns the HTTP 204 No Content status code.

Delete a Collection🔗

To remove an existing Collection, send a POST request to the POST /api/rest/2.0/collections/delete API endpoint.

Request parameters🔗

In your POST request body, include the following parameters:

ParameterDescription

collection_identifiers

String. Required. GUID of the Collection to be deleted.

delete_children

String. Optional. Set to true to delete child objects in the Collection where the user has permission. Any objects without delete access will be ignored.

dry_run

String. Optional. Set to true to preview the deletion process without removing any objects. The response lists the items that would be deleted, so you can review them before proceeding with actual deletion.

Example request🔗

To review your deletion request without actually deleting the Collection and its objects, set dry_run to true and delete_children to true.

curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/collections/delete'  \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {AUTH_TOKEN}' \
  --data-raw '{
  "collection_identifiers": [
    "6996b262-8733-4af6-8f8e-8d7faefb5be0"
  ],
  "delete_children": true,
  "dry_run": true
}'

API response🔗

If the API request is successful, it gives you a preview of the deletion operation without actually deleting anything.

  • metadata_deleted: List of metadata objects that will be deleted

  • metadata_skipped: List of metadata objects that will not be deleted for lack of permissions or other constraints

{"metadata_deleted":[{"type":"COLLECTION","identifiers":[{"id":"6996b262-8733-4af6-8f8e-8d7faefb5be0","name":"Docs Collection"}]},{"type":"LIVEBOARD","identifiers":[{"id":"278d2313-ac3a-44bb-b842-a4c9dff84e68","name":"Demo-lb"},{"id":"1bcdb2c1-e960-4f6b-bbf9-64f3e0cd33b9","name":"Demo-lb1"}]}],"metadata_skipped":[]}

Example request🔗

To delete the Collection and the objects within it, set dry_run to false and delete_children to true.

curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/collections/delete'  \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {AUTH_TOKEN}' \
  --data-raw '{
  "collection_identifiers": [
    "6996b262-8733-4af6-8f8e-8d7faefb5be0"
  ],
  "delete_children": true,
  "dry_run": false
}'

API response🔗

If the API request is successful, it deletes the Collection and all objects within it for which you have delete permission.

{"metadata_deleted":[{"type":"COLLECTION","identifiers":[{"id":"6996b262-8733-4af6-8f8e-8d7faefb5be0","name":"Docs Collection"}]},{"type":"LIVEBOARD","identifiers":[{"id":"278d2313-ac3a-44bb-b842-a4c9dff84e68","name":"Demo-lb"},{"id":"1bcdb2c1-e960-4f6b-bbf9-64f3e0cd33b9","name":"Demo-lb1"}]}],"metadata_skipped":[]}

Additional references🔗

© 2026 ThoughtSpot Inc. All Rights Reserved.