Group APIs

Group APIs

The Group API endpoints allow you to programmatically create and manage user groups, configure privileges, and assign users to a 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

    Allows users to perform the following functions:

    • Access Developer portal

    • Embed ThoughtSpot app or its content in an external application

    • Add custom menu options in the embedded Liveboards and visualizations

    • Re-brand the interface elements of the embedded ThoughtSpot content

  • USERDATAUPLOADING

    Allows users to upload data to ThoughtSpot.

  • DATADOWNLOADING

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

  • 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 Liveboard 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

  • SYNCMANAGEMENT

    Allows setting up secure pipelines to external business apps and sync data using ThoughtSpot Sync.

Supported operations🔗

API endpointAvailable from

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

ThoughtSpot Cloud ts7.aug.cl
ThoughtSpot Software 7.1.1

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

ThoughtSpot Cloud ts7.aug.cl
ThoughtSpot Software 7.1.1

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

ThoughtSpot Cloud ts7.aug.cl
ThoughtSpot Software 7.1.1

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

ThoughtSpot Cloud ts7.aug.cl
ThoughtSpot Software 7.1.1

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

ThoughtSpot Cloud ts7.aug.cl
ThoughtSpot Software 7.1.1

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

ThoughtSpot Cloud ts7.oct.cl
ThoughtSpot Software 7.2.1

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

ThoughtSpot Cloud ts7.oct.cl
ThoughtSpot Software 7.2.1

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

ThoughtSpot Cloud ts7.oct.cl
ThoughtSpot Software 7.2.1

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

ThoughtSpot Cloud ts7.oct.cl
ThoughtSpot Software 7.2.1

POST /tspublic/v1/group/addrole Beta
Assigns a Role to a user group.

ThoughtSpot Cloud 9.7.0.cl
ThoughtSpot Software Not available

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

ThoughtSpot Cloud ts7.may.cl
ThoughtSpot Software 6.0.x

POST /tspublic/v1/group/removerole Beta
Removes the Role assigned to a group.

ThoughtSpot Cloud 9.7.0.cl
ThoughtSpot Software Not available

POST /tspublic/v1/group/removeprivilege
Removes privileges assigned to a user group.

ThoughtSpot Cloud ts7.may.cl
ThoughtSpot Software 6.0.x

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

ThoughtSpot Cloud ts7.sep.cl
ThoughtSpot Software 7.2.1

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

ThoughtSpot Cloud ts7.sep.cl
ThoughtSpot Software 7.2.1

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

ThoughtSpot Cloud ts7.sep.cl
ThoughtSpot Software 7.2.1

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

ThoughtSpot Cloud ts7.sep.cl
ThoughtSpot Software 7.2.1

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

ThoughtSpot Cloud ts7.sep.cl
ThoughtSpot Software 7.2.1

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

ThoughtSpot Cloud ts7.sep.cl
ThoughtSpot Software 7.2.1

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

ThoughtSpot Cloud ts7.aug.cl
ThoughtSpot Software 7.1.1

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

ThoughtSpot Cloud ts7.aug.cl
ThoughtSpot Software 7.1.1

Required permissions🔗

You must have administrator access to create, edit, or delete group objects, configure privileges, and assign users.

If you have a multi-tenant instance, the cluster admin can associate a group to an orgid. For more information about Orgs, see Multi-tenancy with Orgs.

Create a user group🔗

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

Note

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 parameterDescription

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, Developer.

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.

roleIds Optional

Array of Strings. Array of Role GUIDs. If RBAC is enabled and Roles are created on your instance, specify the GUIDs of the Role 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 codeDescription

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 parameterDescription

groupid

String. The GUID of the user group.

content

String. A JSON map of group properties.

roleIds Optional

Array of Strings. Array of Role GUIDs. If RBAC is enabled and Roles are created on your instance, specify the GUIDs of the Role objects.

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 codeDescription

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 parameterDescription

groupid Optional

String. The GUID of the user group to query.

name Optional

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

Note

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 codeDescription

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.

Note

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 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 parameterDescription

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, 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 CodeDescription

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 parameterDescription

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 assigned to 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 CodeDescription

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 ParameterDescription

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 codeDescription

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 ParameterDescription

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": "[email protected]",
        "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 codeDescription

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🔗

ParameterTypeDescription

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 successful, the API returns the following response:

Response Code
204

Response codes🔗

HTTP status codeDescription

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 parameterDescription

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=["d02210b1-f836-4f84-a0dd-5f555f0a65d1","982d6da9-9cd1-479e-b9a6-35aa05f9282a"]' \
'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 codeDescription

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 ParameterDescription

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 codeDescription

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🔗

ParameterTypeDescription

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 codeDescription

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 parameterDescription

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 codeDescription

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 parameterDescription

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 codeDescription

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 parameterDescription

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 codeDescription

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 ParameterDescription

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 codeDescription

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.

Note

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 parameterDescription

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 codeDescription

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 parameterDescription

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 codeDescription

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.

Note

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 ParameterDescription

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 codeDescription

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.

Important

ThoughtSpot does not recommend removing a user from the All group.

Resource URL🔗

DELETE /tspublic/v1/group/{groupid}

Request parameters🔗

Path ParameterDescription

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 codeDescription

204

Successful operation

403

Forbidden client

500

Invalid group ID

APIs for Role assignment🔗

The API endpoints for Role administration and assignment are available only if the Role-based access control (RBAC) Beta feature is enabled on your instance. The RBAC feature is turned off by default. To enable RBAC on your instance, contact ThoughtSpot Support.

After RBAC is enabled on your instance, the group privileges will be migrated to the corresponding role privilege. For granular access control, you can create a new role and assign it to a group.

Add a Role to groups🔗

To add a Role to a group object, send a POST request to the /tspublic/v1/group/addrole API endpoint. To assign Roles to a group object, the administrator must have GROUP_ADMINISTRATION and ROLE_ADMINISTRATION privileges.

Resource URL🔗

POST /tspublic/v1/group/addrole

Request parameters🔗

Form parameterDescription

roleID

String. GUID of the Role that you want to assign.

groupNames

String. A JSON array of group names to which you want to assign the Role.

Example request🔗

cURL
curl -X POST \
--header 'Content-Type: multipart/form-data' \
--header 'Accept: application/json' \
--header 'X-Requested-By: ThoughtSpot' \
-F 'roleID=D7210f4d8-835d-46c0-ac1a-d134c4a5da5d' \
-F 'groupNames=["Analyst"]' \
'https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/group/addrole'
Request URL
https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/group/addrole

Example response🔗

If the Role assignment is successful, the API returns the 204 response code

204

Response codes🔗

HTTP CodeDescription

204

Successful operation

415

Invalid content type

401

Unauthorized request

Remove a Role from groups🔗

To programmatically delete a privilege assigned to a user group, send a DELETE request to the /tspublic/v1/group/removeprivilege API endpoint.

To remove roles from a group object, the administrator must have GROUP_ADMINISTRATION and ROLE_ADMINISTRATION privileges.

Resource URL🔗

POST /tspublic/v1/group/removerole

Request parameters🔗

Form parameterDescription

roleID

String. GUID of the Role that you want to remove.

groupNames

String. A JSON array of group names from which you want to remove the Role.

Example request🔗

cURL
curl -X POST /
--header 'Content-Type: multipart/form-data' /
--header 'Accept: application/json' /
-F roleID=e8d3ff37-841a-460a-89b4-58f76d5712a5 /
-F groupNames=%5BAdministrator%5D /
'https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/group/removerole'
Request URL
https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/group/removerole

Example response🔗

If API request is successful, the 204 response code is returned:

204

Response codes🔗

HTTP CodeDescription

204

Successful operation

400

Invalid parameter type

415

Invalid content type