# Collections > For the complete documentation index, see [llms.txt](https://developers.thoughtspot.com/docs/llms.txt) Source: https://developers.thoughtspot.com/docs/collections # Collections 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. You can also embed the Collections page directly in your application using the Visual Embed SDK. To navigate users to the Collections page in full application embedding, set `pageId` to `Page.Collections` in `AppViewConfig`. For more information, see [Navigate to the Collections page]({{navprefix}}/{{customize-nav-full-embed}}#_navigate_to_the_collections_page). ## 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: | Parameter | Description | | --- | --- | | `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 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: | Parameter | Description | | --- | --- | | `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. Do not set this to `-1`; specify an explicit `record_size` and iterate through pages programmatically. | | `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 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: | Parameter | Description | | --- | --- | | `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 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 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 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 | Field | Applies to | Description | | --- | --- | --- | | `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 | Role | `share_mode` | `content_share_mode` | What 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 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": "name@example.com" }, "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 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": "name@example.com" }, "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 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": "former-member@example.com" }, "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: | Parameter | Description | | --- | --- | | `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 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 ```JSON {"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 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. ```JSON {"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 - For information about creating and managing Collections via ThoughtSpot UI, see [Collections in ThoughtSpot](https://docs.thoughtspot.com/cloud/latest/collections)