Group APIs

The Group APIs allow you to programmatically create and manage user groups, configure privileges, and assign users to a group.

Supported operations

POST /tspublic/v1/group/
Creates a user group.

PUT /tspublic/v1/group/{groupid}
Modifies a user group.

GET /tspublic/v1/group/
Gets details of a user group.

POST /tspublic/v1/group/{groupid}/user/{userid}
Assigns a user to a group.

GET /tspublic/v1/group/listuser/{groupid}
Gets a list of users assigned to a group.

POST /tspublic/v1/group/{groupid}/users
Adds users to a specific group.

PUT /tspublic/v1/group/{groupid}/users
Updates user data for a given group.

GET /tspublic/v1/group/{groupid}/users
Gets details of the users that are currently assigned to a group.

DELETE /tspublic/v1/group/{groupid}/users
Removes users from a group.

POST /tspublic/v1/group/addprivilege
Assigns a privilege to a user group.

POST /tspublic/v1/group/removeprivilege
Removes the privilege assigned to a group.

POST /tspublic/v1/group/{groupid}/groups
Assigns groups to a parent group.

PUT /tspublic/v1/group/{groupid}/groups
Updates subgroup objects for a given group.

GET /tspublic/v1/group/{groupid}/groups
Gets a list of subgroups for a given group object.

POST /tspublic/v1/group/addmemberships
Adds members to a group.

POST /tspublic/v1/group/removememberships
Removes members from a group.

DELETE /tspublic/v1/group/{groupid}/groups
Removes subgroups from a group.

DELETE /tspublic/v1/group/{groupid}/user/{userid}
Removes a user from a user group.

DELETE /tspublic/v1/group/{groupid}
Deletes a user group.

User groups and privileges

ThoughtSpot administrators can programmatically assign the following types of privileges to a user group:

  • ADMINISTRATION

    Allows users to perform the following functions:

    • Create, edit, and delete users and user groups

    • View and edit access to all data

    • Download a saved answer

  • DEVELOPER

    This privilege is available only if ThoughtSpot Everywhere is enabled on your instance.

  • USERDATAUPLOADING

    Allows users to upload data to ThoughtSpot.

  • DATADOWNLOADING

    Allows users to download ThoughtSpot data from search results and pinboards.

  • DATAMANAGEMENT

    Allows users to create worksheets and views. To edit a worksheet or view created and shared by another user, the user must have edit permission to modify the object.

  • SHAREWITHALL

    Allows users to share objects with other users and user groups.

  • EXPERIMENTALFEATUREPRIVILEGE

    Allows access to the trial and experimental features that ThoughtSpot makes available to evaluating users and early adopters.

  • JOBSCHEDULING

    Allows scheduling and editing pinboard jobs.

  • RANALYSIS

    Allows invoking R scripts to explore search answers and sharing custom scripts.

  • A3ANALYSIS

    Allows users to generate and access SpotIQ analyses.

  • BYPASSRLS

    Allows access to the following operations:

    • Create, edit, or delete existing RLS rules

    • Enable or disable Bypass RLS on a worksheet

Create a user group

To programmatically create a user group, send a POST request to the /tspublic/v1/group/ API endpoint.

ThoughtSpot also has a default group called All. When you create new users in ThoughtSpot, they are automatically added to All. You cannot delete the All group or remove members from it.

Resource URL

POST /tspublic/v1/group/

Request parameters

Form parameter Description

name

String. Name of the user group. The group name string must be unique.

displayname

String. A unique display name string for the user group, for example, Analyst.

description

String. Description text for the group.

privileges Optional

Array of strings. A JSON array of the privileges to assign to the group. Valid values for the privileges string are:

  • ADMINISTRATION

  • DEVELOPER

  • USERDATAUPLOADING

  • DATADOWNLOADING

  • DATAMANAGEMENT

  • SHAREWITHALL

  • EXPERIMENTALFEATUREPRIVILEGE

  • JOBSCHEDULING

  • RANALYSIS

  • A3ANALYSIS

  • BYPASSRLS

grouptype Optional

String. Type of user group. Default value is LOCAL_GROUP, which indicates that the user group is created locally in the ThoughtSpot system.

tenantid Optional

String. GUID of the tenant for which the user group is being created.

visibility Optional

String. Visibility of the user group. The visibility attribute is set to DEFAULT. The DEFAULT attribute makes the user group visible for other user groups and allows them to share objects.

Example request

cURL
curl -X POST \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Accept: application/json' \
--header 'X-Requested-By: ThoughtSpot' \
-d 'name=TS%20Group&display_name=TS%20Group&grouptype=LOCAL_GROUP&visibility=DEFAULT' \
'https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/group/'
Request URL
https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/group/

Example response

If the user group is successfully created in ThoughtSpot, the API returns the user group GUID along with the following JSON response:

{
  "userGroupContent": {
    "schemaVersion": "4"
  },
  "groupIdx": 2,
  "metadataVersion": -1,
  "assignedPinboards": [],
  "assignedGroups": [],
  "inheritedGroups": [],
  "privileges": [],
  "type": "LOCAL_GROUP",
  "parenttype": "GROUP",
  "visibility": "DEFAULT",
  "tenantId": "982d6da9-9cd1-479e-b9a6-35aa05f9282a",
  "displayName": "TS Group",
  "header": {
    "id": "0f7af46f-e48c-4cca-b60f-d63d5ddbe59f",
    "indexVersion": 0,
    "generationNum": 0,
    "name": "TS Group",
    "author": "59481331-ee53-42be-a548-bd87be6ddd4a",
    "created": 1624882497992,
    "modified": 1624882497992,
    "modifiedBy": "59481331-ee53-42be-a548-bd87be6ddd4a",
    "owner": "0f7af46f-e48c-4cca-b60f-d63d5ddbe59f",
    "tags": [],
    "isExternal": false,
    "isDeprecated": false
  },
  "complete": true,
  "incompleteDetail": [],
  "isSystemPrincipal": false
}

Response codes

HTTP status code Description

200

Successful operation

401

Unauthorized request

500

Incorrect password format

Update a user group

If you have admin user privileges, you can programmatically modify the properties of a group using the /tspublic/v1/group/{groupid} API. Using this API, you can also assign privileges and modify the group visibility.

Resource URL

PUT /tspublic/v1/group/{groupid}

Request parameters

Form parameter Description

groupid

String. The GUID of the user group.

content

String. A JSON map of group properties.

Example request

cURL
curl -X PUT \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Accept: application/json' \
--header 'X-Requested-By: ThoughtSpot' \
-d 'groupid=0f7af46f-e48c-4cca-b60f-d63d5ddbe59f&content={   "userGroupContent": {     "schemaVersion": "4"   },   "groupIdx": 2,   "metadataVersion": -1,   "assignedPinboards": [],   "assignedGroups": [],   "inheritedGroups": [],   "privileges": [],   "type": "LOCAL_GROUP",   "parenttype": "GROUP",   "visibility": "DEFAULT",   "tenantId": "982d6da9-9cd1-479e-b9a6-35aa05f9282a",   "displayName": "TS Group",   "header": {     "id": "0f7af46f-e48c-4cca-b60f-d63d5ddbe59f",     "indexVersion": 0,     "generationNum": 0,     "name": "TS Group",     "author": "59481331-ee53-42be-a548-bd87be6ddd4a",     "created": 1624882497992,     "modified": 1624882497992,     "modifiedBy": "59481331-ee53-42be-a548-bd87be6ddd4a",     "owner": "0f7af46f-e48c-4cca-b60f-d63d5ddbe59f",     "tags": [],     "isExternal": false,     "isDeprecated": false   },   "complete": true,   "incompleteDetail": [],   "isSystemPrincipal": false }' \
'https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/group/{groupid}'
Request URL
https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/group/{groupid}

Example JSON for user group update

{
  "userGroupContent": {
    "schemaVersion": "4"
  },
  "groupIdx": 2,
  "metadataVersion": -1,
  "assignedPinboards": [],
  "assignedGroups": [],
  "inheritedGroups": [],
  "privileges": [],
  "type": "LOCAL_GROUP",
  "parenttype": "GROUP",
  "visibility": "DEFAULT",
  "tenantId": "982d6da9-9cd1-479e-b9a6-35aa05f9282a",
  "displayName": "TS Group",
  "header": {
    "id": "0f7af46f-e48c-4cca-b60f-d63d5ddbe59f",
    "indexVersion": 0,
    "generationNum": 0,
    "name": "TS Group",
    "author": "59481331-ee53-42be-a548-bd87be6ddd4a",
    "created": 1624882497992,
    "modified": 1624882497992,
    "modifiedBy": "59481331-ee53-42be-a548-bd87be6ddd4a",
    "owner": "0f7af46f-e48c-4cca-b60f-d63d5ddbe59f",
    "tags": [],
    "isExternal": false,
    "isDeprecated": false
  },
  "complete": true,
  "incompleteDetail": [],
  "isSystemPrincipal": false
}

Example response

On successful update of the user group properties, the API returns the following response code:

Response Code
204

Response codes

HTTP status code Description

204

Successful operation

403

Unauthorized request

500

Invalid content format

Get details of a user group

To get the details of a specific user group or all user groups in the ThoughtSpot system, send a GET request to the /tspublic/v1/group/ API endpoint.

Resource URL

GET /tspublic/v1/group/

Request parameters

Query parameter Description

groupid Optional

String. The GUID of the user group to query.

name Optional

String. Name of the user group that you want to query.

You can use either groupid or name to query data for a specific user group. If using both, make sure the values for these parameters point to the same user group. If neither of these parameters is defined, the API returns a response with the details of all user groups in the ThoughtSpot system.

Example request

cURL
curl -X GET \
--header 'Accept: application/json' \
--header 'X-Requested-By: ThoughtSpot' \
'https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/group/?groupid=0f7af46f-e48c-4cca-b60f-d63d5ddbe59f'
Request URL
https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/group/?groupid=0f7af46f-e48c-4cca-b60f-d63d5ddbe59f

Example response

{
  "userGroupContent": {},
  "groupIdx": 2,
  "metadataVersion": -1,
  "assignedPinboards": [],
  "assignedGroups": [],
  "inheritedGroups": [],
  "privileges": [],
  "type": "LOCAL_GROUP",
  "parenttype": "GROUP",
  "visibility": "DEFAULT",
  "tenantId": "982d6da9-9cd1-479e-b9a6-35aa05f9282a",
  "displayName": "TS Group",
  "header": {
    "id": "0f7af46f-e48c-4cca-b60f-d63d5ddbe59f",
    "indexVersion": 598,
    "generationNum": 598,
    "name": "TS Group",
    "displayName": "TS Group",
    "author": "59481331-ee53-42be-a548-bd87be6ddd4a",
    "created": 1624882497992,
    "modified": 1624886953559,
    "modifiedBy": "59481331-ee53-42be-a548-bd87be6ddd4a",
    "owner": "0f7af46f-e48c-4cca-b60f-d63d5ddbe59f",
    "isDeleted": false,
    "isHidden": false,
    "tags": [],
    "type": "LOCAL_GROUP",
    "isExternal": false,
    "isDeprecated": false
  },
  "complete": true,
  "incompleteDetail": [],
  "isSystemPrincipal": false
}

Response codes

HTTP status code Description

200

Successful retrieval of user group details

400

Invalid parameter

Add a privilege to a user group

For ease of user management and access control, ThoughtSpot administrators can create user groups and assign privileges to these groups. The privileges determine the actions that the users belonging to a group are allowed to do.

If you have admin user credentials, you can programmatically assign a privilege to a user group using the /tspublic/v1/group/addprivilege API endpoint.

ThoughtSpot also has a default group called All group. When you create new users in ThoughtSpot, they are automatically assigned to the All group. By default, the members of All group do not have permissions to download or upload data. You can use this API to add these privileges to the All group.

Resource URL

POST /tspublic/v1/group/addprivilege

Request parameters

Make sure you set the API request’s Content-Type header as multipart/form-data.

Form parameter Description

privilege

String. The type of privilege to add. Valid values for the privileges string are:

  • ADMINISTRATION

  • DEVELOPER

  • USERDATAUPLOADING

  • DATADOWNLOADING

  • DATAMANAGEMENT

  • SHAREWITHALL

  • EXPERIMENTALFEATUREPRIVILEGE

  • JOBSCHEDULING

  • RANALYSIS

  • A3ANALYSIS

  • BYPASSRLS

groupNames

String. A JSON array of group names to which you want to add the privilege. To add a privilege to All group, specify All.

Example request

cURL
curl -X POST \
--header 'Content-Type: multipart/form-data' \
--header 'Accept: application/json' \
--header 'X-Requested-By: ThoughtSpot' \
-F 'privilege=DATADOWNLOADING' \
-F 'groupNames=["Analyst"]' \
'https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/group/addprivilege'
Request URL
https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/group/addprivilege

Example response

If the privilege assignment is successful, the API returns the group metadata with the updated privilege details.

Response codes

HTTP status code Description

200

Successful operation

415

Invalid content type

401

Unauthorized request

Remove a privilege assigned to a group

To programmatically delete a privilege assigned to a user group, use the /tspublic/v1/group/removeprivilege API.

Resource URL

POST /tspublic/v1/group/removeprivilege

Request parameters

Make sure you set the API request’s Content-Type header as multipart/form-data.

Form parameter Description

privilege

String. The group privilege to delete. Valid values are:

  • ADMINISTRATION

  • DEVELOPER

  • USERDATAUPLOADING

  • DATADOWNLOADING

  • DATAMANAGEMENT

  • SHAREWITHALL

  • EXPERIMENTALFEATUREPRIVILEGE

  • JOBSCHEDULING

  • RANALYSIS

  • A3ANALYSIS

  • BYPASSRLS

groupNames

String. A JSON array of group names from which you want to remove the privilege. To remove a privilege from the All group, specify All.

Example request

cURL
curl -X POST \
--header 'Content-Type: multipart/form-data' \
--header 'Accept: application/json' \
--header 'X-Requested-By: ThoughtSpot' \
-F 'privilege=DATAUPLOADING' \
-F 'groupNames=["Analyst"]' \
'https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/group/removeprivilege'
Request URL
https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/group/removeprivilege

Response codes

HTTP status code Description

204

Successful operation

400

Invalid parameter type

415

Invalid content type

Add a user to a group

To programmatically add an existing ThoughtSpot user to a user group, send a POST request to the /tspublic/v1/group/{groupid}/user/{userid} API endpoint.

When you assign a user to a group, the user inherits the privileges assigned to that group.

Resource URL

POST /tspublic/v1/group/{groupid}/user/{userid}

Request parameters

Path Parameter Description

groupid

String. The GUID of the user group to which you want to add the user.

userid

String. The GUID of the user that you want to assign to the specified group.

Example request

cURL
curl -X POST \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'X-Requested-By: ThoughtSpot' \
'https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/group/1f58ba19-83a8-48ee-86e7-9c16f61157e3/user/80560f25-f24e-4c2a-b015-10b9770287c6'
Request URL
https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/group/1f58ba19-83a8-48ee-86e7-9c16f61157e3/user/80560f25-f24e-4c2a-b015-10b9770287c6

Example response

The API returns the following response after the user is successfully assigned to the specified group:

Response Code
204

Response codes

HTTP status code Description

204

Successful operation

400

Invalid parameter

Get a list of users assigned to a group

To get the details of users assigned to a group, send a GET request to the /tspublic/v1/group/listuser/{groupid} API endpoint.

Resource URL

GET /tspublic/v1/group/listuser/{groupid}

Request parameters

Path Parameter Description

groupid

String. The GUID of the user group to query.

Example request

cURL
curl -X GET \
--header 'Accept: application/json' \
--header 'X-Requested-By: ThoughtSpot' \
'https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/group/listuser/e5fc80ce-db65-4921-8ece-c7bb44fceca1'
Request URL
https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/group/listuser/e5fc80ce-db65-4921-8ece-c7bb44fceca1

Example response

[
  {
    "userContent": {
      "userPreferences": {
        "notifyOnShare": true,
        "showWalkMe": true,
        "analystOnboardingComplete": false
      },
      "userProperties": {
        "mail": "user1@thoughtspot.com",
        "persona": "BUSINESS_USER"
      },
      "userActivityProto": {
        "first_login": -1,
        "welcome_email_sent": false
      }
    },
    "state": "ACTIVE",
    "assignedGroups": [
      "b25ee394-9d13-49e3-9385-cd97f5b253b4",
      "e5fc80ce-db65-4921-8ece-c7bb44fceca1"
    ],
    "inheritedGroups": [
      "b25ee394-9d13-49e3-9385-cd97f5b253b4",
      "e5fc80ce-db65-4921-8ece-c7bb44fceca1"
    ],
    "privileges": [
      "DEVELOPER"
    ],
    "type": "LOCAL_USER",
    "parenttype": "USER",
    "visibility": "DEFAULT",
    "tenantId": "982d6da9-9cd1-479e-b9a6-35aa05f9282a",
    "displayName": "user1-dev",
    "header": {
      "id": "eacaa47b-5cde-4b87-898f-41209ec45b56",
      "indexVersion": 2657,
      "generationNum": 2657,
      "name": "user1",
      "displayName": "user1-dev",
      "author": "59481331-ee53-42be-a548-bd87be6ddd4a",
      "created": 1622094121127,
      "modified": 1623847350023,
      "modifiedBy": "59481331-ee53-42be-a548-bd87be6ddd4a",
      "owner": "eacaa47b-5cde-4b87-898f-41209ec45b56",
      "isDeleted": false,
      "isHidden": false,
      "clientState": {
        "preferences": {
          "SAVE_ANSWER_TOOLTIP_SEEN": true
        },
        "tips": {
          "favoriteCardTip": true,
          "recentlyViewedCard": true
        }
      },
      "tags": [],
      "type": "LOCAL_USER",
      "isExternal": false,
      "isDeprecated": false
    },
    "complete": true,
    "incompleteDetail": [],
    "isSuperUser": false,
    "isSystemPrincipal": false
  }
]

Response codes

HTTP status code Description

200

Successful operation

400

Invalid parameter

Add users to a specific group

To add a list of users to a group, send a POST request to the /tspublic/v1/group/{groupid}/users API endpoint.

Resource URL

POST /tspublic/v1/group/{groupid}/users

Request parameters

Parameter Type Description

groupid

path parameter

String. The GUID of the user group to which you want to add users.

userids

query parameter

String. A JSON array of the user GUIDs to add to the specified group.

Example request

cURL
curl -X POST \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'X-Requested-By: ThoughtSpot' \
'https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/group/b8cc6029-3749-4596-9a33-263688a2732e/users?userids=%5B%22fab84cbc-b7ed-4fed-b241-9af2cbb453de%22%5D'
Request URL
https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/group/b8cc6029-3749-4596-9a33-263688a2732e/users?userids=%5B%22fab84cbc-b7ed-4fed-b241-9af2cbb453de%22%5D

Example response

If the user assignment operation is succesful, the API returns the following response:

Response Code
204

Response codes

HTTP status code Description

204

Successful operation

400

Invalid parameter

Update user data for a group

To add or update the list of users assigned to a group, send a PUT request to the /tspublic/v1/group/{groupid}/users API endpoint.

Resource URL

PUT /tspublic/v1/group/{groupid}/users

Request parameters

Form parameter Description

groupid

String. The GUID of the user group to which the specified user IDs belong.

userids

String. A JSON array of the user GUIDs that you want to add or modify.

Example request

cURL
curl -X PUT \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Accept: application/json' \
--header 'X-Requested-By: ThoughtSpot' \
-d 'groupid=876b3cf1-8a20-4210-b671-506eaaa5005e&userids=%5B%22d02210b1-f836-4f84-a0dd-5f555f0a65d1%22%2C%22982d6da9-9cd1-479e-b9a6-35aa05f9282a%22%5D' \
'https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/group/{groupid}/users'
Request URL
https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/group/{groupid}/users

Example response

If the group update operation is successful, the API returns the following response:

Response Code
204

Response codes

HTTP status code Description

204

Successful operation

400

Invalid parameter

Get a list of users in a group

To get a list of users assigned to a group, send a GET request to the /tspublic/v1/group/{groupid}/users API endpoint.

Resource URL

GET /tspublic/v1/group/{groupid}/users

Request parameters

Path Parameter Description

groupid

String. The GUID of the user group to query.

Example request

cURL
curl -X GET \
--header 'Accept: application/json' \
--header 'X-Requested-By: ThoughtSpot' \
'https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/group/b8cc6029-3749-4596-9a33-263688a2732e/users'
Request URL
https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/group/b8cc6029-3749-4596-9a33-263688a2732e/users

Example response

[
  {
    "userContent": {
      "userPreferences": {
        "notifyOnShare": true,
        "showWalkMe": true,
        "analystOnboardingComplete": false
      },
      "userProperties": {},
      "userActivityProto": {
        "first_login": -1,
        "welcome_email_sent": false
      }
    },
    "state": "ACTIVE",
    "assignedGroups": [
      "b8cc6029-3749-4596-9a33-263688a2732e",
      "b25ee394-9d13-49e3-9385-cd97f5b253b4"
    ],
    "inheritedGroups": [
      "b8cc6029-3749-4596-9a33-263688a2732e",
      "b25ee394-9d13-49e3-9385-cd97f5b253b4"
    ],
    "privileges": [
      "DATADOWNLOADING"
    ],
    "type": "LOCAL_USER",
    "parenttype": "USER",
    "visibility": "DEFAULT",
    "tenantId": "982d6da9-9cd1-479e-b9a6-35aa05f9282a",
    "displayName": "Test User 2",
    "header": {
      "id": "fab84cbc-b7ed-4fed-b241-9af2cbb453de",
      "indexVersion": 122,
      "generationNum": 122,
      "name": "TestUser2",
      "displayName": "Test User 2",
      "author": "59481331-ee53-42be-a548-bd87be6ddd4a",
      "created": 1634194734004,
      "modified": 1634194734004,
      "modifiedBy": "59481331-ee53-42be-a548-bd87be6ddd4a",
      "owner": "fab84cbc-b7ed-4fed-b241-9af2cbb453de",
      "isDeleted": false,
      "isHidden": false,
      "tags": [],
      "type": "LOCAL_USER",
      "isExternal": false,
      "isDeprecated": false
    },
    "complete": true,
    "incompleteDetail": [],
    "isSuperUser": false,
    "isSystemPrincipal": false
  }
]

Response codes

HTTP status code Description

204

Successful operation

400

Invalid parameter

Remove users from a specific group

To remove users assigned to a specific group, send a DELETE request to the /tspublic/v1/group/{groupid}/users API endpoint.

Resource URL

DELETE /tspublic/v1/group/{groupid}/users

Request parameters

Parameter Type Description

groupid

path parameter

String. The GUID of the user group from which you want to remove users.

userids

query parameter

String. A JSON array of the GUIDs of users that you want to remove from the specified group.

Example request

cURL
curl -X DELETE \
--header 'Accept: application/json' \
--header 'X-Requested-By: ThoughtSpot' \
'https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/group/062caeb3-8b31-4039-819b-a6c4b02b3791/users?userids=%5B%22164913ae-ee45-49ff-bcf7-4a1f893e78e5%22%2C%22692749ac-a01b-41f1-b2ac-3e38a5131590%22%5D'
Request URL
https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/group/062caeb3-8b31-4039-819b-a6c4b02b3791/users?userids=%5B%22164913ae-ee45-49ff-bcf7-4a1f893e78e5%22%2C%22692749ac-a01b-41f1-b2ac-3e38a5131590%22%5D

Example response

If the group update operation is successful, the API returns the following response:

Response Code
204

Response codes

HTTP status code Description

204

Successful operation

400

Invalid parameter

Add members to a group

To add users to one or several groups, send a POST request to the /tspublic/v1/group/addmemberships endpoint.

Resource URL

POST /tspublic/v1/group/addmemberships

Request parameters

Make sure you set the Content-Type header as multipart/form-data.

Form parameter Description

userids

String. The GUIDs of the users to add to the specified groups.

groupids

String. The GUID of the user groups to which you want to add the specified userids.

Example request

cURL
curl -X POST \
--header 'Content-Type: multipart/form-data' \
--header 'Accept: application/json' \
--header 'X-Requested-By: ThoughtSpot' \
--header 'Cookie: JSESSIONID=a7b4945a-fb77-4e9b-bd46-bf7d47be89ec' \
-F 'userids=['b5f53b17-0649-4107-bb97-5c7b01e4773b']' \
-F 'groupids=['dc1cd425-96b4-42a2-8ea6-cbf4379cba04']' \
'http://<ThoughtSpot-host>/callosum/v1/tspublic/v1/group/addmemberships'
Request URL
https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/group/addmemberships

Response codes

HTTP status code Description

204

Successful operation

400

Invalid parameter

415

Invalid content type

Assign groups to another group

ThoughtSpot allows you to configure hierarchical groups. You can create a master group and assign other groups to it. For example, you can create a master group called Site and assign your tenant or ThoughtSpot user groups to this group. The subgroups inherit the privileges from their parent group.

To assign groups to a specific group, send a POST request to the /tspublic/v1/group/{groupid}/groups endpoint.

Resource URL

POST /tspublic/v1/group/{groupid}/groups

Request parameters

Make sure you set the API request’s Content-Type header as multipart/form-data.

Form parameter Description

principalids

String. A JSON array of the GUIDs of the groups to assign.

groupid

String. The GUID of the group to which you want to assign the group IDs specified in the principalids attribute.

Example request

cURL
curl -X POST \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Accept: application/json' \
--header 'X-Requested-By: ThoughtSpot' \
-d 'principalids=%5B%22b9541f8f-06cc-4295-8acc-cb57cfba8ced%22%2C%22982d6da9-9cd1-479e-b9a6-35aa05f9282a%22%5D&groupid=27ffc229-a3e7-4c46-aed8-26cad6b395ed' \
'https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/group/{groupid}/groups'
Request URL
https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/group/{groupid}/groups

Example response

If the group assignment is successful, the API returns the following response:

Response Code
204

Response codes

HTTP status code Description

204

Successful operation

400

Invalid parameter

Update the subgroup objects of a group

To update the subgroups assigned to a group, send a PUT request to the /tspublic/v1/group/{groupid}/groups endpoint.

Resource URL

PUT /tspublic/v1/group/{groupid}/groups

Request parameters

Form parameter Description

principalids

String. A JSON array of the subgroup GUIDs.

groupid

String. The GUID of the group that you want to update.

Example request

cURL
curl -X PUT  \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Accept: application/json' \
--header 'X-Requested-By: ThoughtSpot' \
-d 'principalids=%5B%22b9541f8f-06cc-4295-8acc-cb57cfba8ced%22%2C%22982d6da9-9cd1-479e-b9a6-35aa05f9282a%22%5D&groupid=27ffc229-a3e7-4c46-aed8-26cad6b395ed' \
'https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/group/{groupid}/groups'
Request URL
https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/group/{groupid}/groups

Example response

If the group update operation is successful, the API returns the following response:

Response Code
204

Response codes

HTTP status code Description

204

Successful operation

400

Invalid parameter

Get a list of subgroups from a group object

To get a list subgroups associated with a group object, send a GET request to the /tspublic/v1/group/{groupid}/groups endpoint.

Resource URL

GET /tspublic/v1/group/{groupid}/groups

Request parameters

Path Parameter Description

groupid

String. The GUID of the group that you want to query.

Example request

cURL
curl -X GET \
--header 'Accept: application/json' \
--header 'X-Requested-By: ThoughtSpot' \
'https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/group/982d6da9-9cd1-479e-b9a6-35aa05f9282a/groups'
Request URL
https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/group/982d6da9-9cd1-479e-b9a6-35aa05f9282a/groups

Example response

If the GET operation is successful, the API returns the details of the subgroups mapped to the specified group ID.

[
  {
    "userGroupContent": {},
    "groupIdx": 2,
    "metadataVersion": -1,
    "assignedPinboards": [],
    "assignedGroups": [
      "982d6da9-9cd1-479e-b9a6-35aa05f9282a"
    ],
    "inheritedGroups": [
      "982d6da9-9cd1-479e-b9a6-35aa05f9282a"
    ],
    "privileges": [
      "DATADOWNLOADING",
      "USERDATAUPLOADING"
    ],
    "type": "LOCAL_GROUP",
    "parenttype": "GROUP",
    "visibility": "DEFAULT",
    "tenantId": "982d6da9-9cd1-479e-b9a6-35aa05f9282a",
    "displayName": "user group 2",
    "header": {
      "id": "fc883cd4-edd9-47c5-80c3-09f8af3a17fc",
      "indexVersion": 305,
      "generationNum": 305,
      "name": "user_group2",
      "displayName": "user group 2",
      "description": "",
      "author": "59481331-ee53-42be-a548-bd87be6ddd4a",
      "created": 1632296030814,
      "modified": 1632296031005,
      "modifiedBy": "59481331-ee53-42be-a548-bd87be6ddd4a",
      "owner": "fc883cd4-edd9-47c5-80c3-09f8af3a17fc",
      "isDeleted": false,
      "isHidden": false,
      "tags": [],
      "type": "LOCAL_GROUP",
      "isExternal": false,
      "isDeprecated": false
    },
    "complete": true,
    "incompleteDetail": [],
    "isSystemPrincipal": false
  },
  {
    "userGroupContent": {},
    "groupIdx": 2,
    "metadataVersion": -1,
    "assignedPinboards": [],
    "assignedGroups": [
      "982d6da9-9cd1-479e-b9a6-35aa05f9282a"
    ],
    "inheritedGroups": [
      "982d6da9-9cd1-479e-b9a6-35aa05f9282a"
    ],
    "privileges": [
      "DATADOWNLOADING",
      "USERDATAUPLOADING"
    ],
    "type": "LOCAL_GROUP",
    "parenttype": "GROUP",
    "visibility": "DEFAULT",
    "tenantId": "982d6da9-9cd1-479e-b9a6-35aa05f9282a",
    "displayName": "User Group",
    "header": {
      "id": "24ac76b8-c1ec-43ee-84d4-3974b95bf163",
      "indexVersion": 305,
      "generationNum": 305,
      "name": "UserGroup",
      "displayName": "User Group",
      "description": "",
      "author": "59481331-ee53-42be-a548-bd87be6ddd4a",
      "created": 1632295966888,
      "modified": 1632295967093,
      "modifiedBy": "59481331-ee53-42be-a548-bd87be6ddd4a",
      "owner": "24ac76b8-c1ec-43ee-84d4-3974b95bf163",
      "isDeleted": false,
      "isHidden": false,
      "tags": [],
      "type": "LOCAL_GROUP",
      "isExternal": false,
      "isDeprecated": false
    },
    "complete": true,
    "incompleteDetail": [],
    "isSystemPrincipal": false
  }
]

Response codes

HTTP status code Description

200

Successful operation

400

Invalid parameter

Remove subgroups from a group

To delete subgroup from a group object, send a DELETE request to the /tspublic/v1/group/{groupid}/groups endpoint.

The DELETE /tspublic/v1/group/{groupid}/groups operation removes only the group associations. If you want to delete the remove the group from the ThoughtSpot system, send a DELETE request to the /tspublic/v1/group/{groupid} endpoint.

Resource URL

DELETE /tspublic/v1/group/{groupid}/groups

Request parameters

Form parameter Description

principalids

String. A JSON array of the subgroup GUIDs that you want to delete.

groupid

String. The GUID of the group from which you want to remove the group association.

Example request

cURL
curl -X DELETE \
--header 'Accept: application/json' \
--header 'X-Requested-By: ThoughtSpot' \
-d 'principalids=%5B%2224ac76b8-c1ec-43ee-84d4-3974b95bf163%22%5D&groupid=982d6da9-9cd1-479e-b9a6-35aa05f9282a' \
'https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/group/{groupid}/groups'
Request URL
https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/group/{groupid}/groups

Example response

If the delete operation is successful, the API returns the following response:

Response Code
204

Response codes

HTTP status code Description

204

Successful operation

400

Invalid parameter

Remove members from a group

To remove users from groups, send a POST request to the /tspublic/v1/group/removememberships endpoint.

Resource URL

POST /tspublic/v1/group/removememberships

Request parameters

Form parameter Description

userids

String. A JSON array of the GUIDs of the users that you want to remove from the specified groupids.

groupids

String. A JSON array of the GUIDs of the user groups from which you want to remove the specified userids.

Example request

cURL
curl -X POST \
--header 'Content-Type: multipart/form-data' \
--header 'Accept: application/json' \
--header 'X-Requested-By: ThoughtSpot' \
--header 'Cookie: JSESSIONID=a7b4945a-fb77-4e9b-bd46-bf7d47be89ec' \
-F 'userids=['b5f53b17-0649-4107-bb97-5c7b01e4773b']' \
-F 'groupids=['dc1cd425-96b4-42a2-8ea6-cbf4379cba04']' \
'http://<ThoughtSpot-host>/callosum/v1/tspublic/v1/group/removememberships'
Request URL
https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/group/removememberships

Response codes

HTTP status code Description

204

Successful operation

400

Invalid parameter

415

Invalid content type

Delete a user from a user group

To programmatically remove a user from a user group, send a DELETE request to the /tspublic/v1/group/{groupid}/user/{userid} API endpoint.

The API removes only the user association. It does not delete the user from the Thoughtspot system. To delete a user, use the DELETE /tspublic/v1/user/{userid} API.

Resource URL

DELETE /tspublic/v1/group/{groupid}/user/{userid}

Request parameters

Path Parameter Description

userid

String. The GUID of the user that you want to remove from the group.

groupid

String. The GUID of the user group from which you want to remove the user.

Example request

cURL
curl -X DELETE \
--header 'Accept: application/json' \
--header 'X-Requested-By: ThoughtSpot' \
'https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/group/1f58ba19-83a8-48ee-86e7-9c16f61157e3/user/80560f25-f24e-4c2a-b015-10b9770287c6'
Request URL
https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/group/1f58ba19-83a8-48ee-86e7-9c16f61157e3/user/80560f25-f24e-4c2a-b015-10b9770287c6

Example response

The API returns the following response after the user is successfully removed from the specified group:

Response Code
204

Response codes

HTTP status code Description

204

Successful operation

403

Unauthorized request

500

Invalid group or user ID

Delete a user group

To remove a user group from the ThoughtSpot system, send a DELETE request to the /tspublic/v1/group/{groupid} API endpoint.

Resource URL

DELETE /tspublic/v1/group/{groupid}

Request parameters

Path Parameter Description

groupid

String. The GUID of the user group to delete.

Example request

cURL
curl -X DELETE \
--header 'Accept: application/json' \
--header 'X-Requested-By: ThoughtSpot' \ 'https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/group/0f7af46f-e48c-4cca-b60f-d63d5ddbe59f'
Request URL
https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/group/0f7af46f-e48c-4cca-b60f-d63d5ddbe59f

Example response

On successful removal of the user group, the API returns the following response:

Response Code
204

Response codes

HTTP status code Description

204

Successful operation

403

Forbidden client

500

Invalid group ID