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 user to a group.

GET /tspublic/v1/group/listuser/{groupid}
Gets a list of users assigned to 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.

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 group. 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

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, `Analysts`.
`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 group visible to other user groups and allows them to share objects.

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

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 group visible to 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
403	Forbidden client
500	Incorrect password format

HTTP status code

Description

200

Successful operation

401

Unauthorized request

403

Forbidden client

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 assign also privileges and modify group visibility.

Resource URL

PUT /tspublic/v1/group/{groupid}

Request parameters

Form parameter Description

Form parameter	Description
`groupid`	String. The GUID of the user group.
`content`	String. A JSON map of group properties.

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}

JSON file example for updating user profile

{
  "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 profile, the API returns the following response code:

Response Code
204

Response codes

HTTP status code	Description
204	Successful operation
403	Unauthorized request
403	Forbidden client
500	Invalid content format

HTTP status code

Description

204

Successful operation

403

Unauthorized request

403

Forbidden client

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

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.

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 group name string
500	Invalid group ID

HTTP status code

Description

200

Successful retrieval of user group details

400

Invalid group name string

500

Invalid group ID

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.

ThoughtSpot also has a default group called All. When you create new users in ThoughtSpot, they are automatically assigned to the All group. By default, the members of All do not have permission 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

This API uses multipart/form-data content-type.

Form parameter Description

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`.

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 'X-Requested-By : ThoughtSpot' \
--header 'Cookie : JSESSIONID=0f534ede-f096-44d0-966a-f02be91dcb68; clientId=5ea75049-cbc9-4443-b083-2d148059c235; userGUID=a0d4311a-d123-48e5-806b-8bdc35e3e835' \
--header 'Accept: application/json' \
-F 'privilege=DATADOWNLOADING' \
-F 'groupNames=%5B%22TS%20Group%22%2C%20%22All%22%5D;type=application/json' \
https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/group/addprivilege

Request URL

https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/group/addprivilege

Response codes

HTTP status code	Description
200	Privilege added
204	Successful operation
401	Failure/Unauthorized request

HTTP status code

Description

200

Privilege added

204

Successful operation

401

Failure/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

Form parameter Description

Form parameter	Description
`privilege`	String. The currently assigned 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 `All`, specify `All`.

privilege

String. The currently assigned 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 All, specify All.

Example request

cURL

curl -X POST \
--header 'X-Requested-By : ThoughtSpot' \
--header 'Cookie : JSESSIONID=0f534ede-f096-44d0-966a-f02be91dcb68; clientId=5ea75049-cbc9-4443-b083-2d148059c235; userGUID=a0d4311a-d123-48e5-806b-8bdc35e3e835' \
--header 'Accept: application/json' \
-F 'privilege=DATADOWNLOADING' \
-F 'groupNames=%5B%22TS%20Group%22%2C%20%22All%22%5D;type=application/json' \
'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
200	Privilege removed
204	Successful operation
401	Failure/Unauthorized request

HTTP status code

Description

200

Privilege removed

204

Successful operation

401

Failure/Unauthorized request

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

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 group.

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 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
403	Forbidden client
500	Invalid group or user ID

HTTP status code

Description

204

Successful operation

403

Forbidden client

500

Invalid group or user ID

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

Path Parameter	Description
`groupid`	String. The GUID of the user group to query.

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
  }
]

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

Path Parameter	Description
`groupid`	String. The GUID of the user group from which you want to remove the user.
`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.

userid

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

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	Forbidden client
500	Invalid group or user ID

HTTP status code

Description

204

Successful operation

403

Forbidden client

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

Path Parameter	Description
`groupid`	String. The GUID of the user group to delete.

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

HTTP status code

Description

204

Successful operation

403

Forbidden client

500

Invalid group ID

Was this page helpful?Give us feedback!

ThoughtSpot is the Modern Analytics Cloud company. Our Live Analytics services deliver personalized, actionable insights at the point of impact for every user, at every level.

Product

By Role

By Department

Solutions

About Us

Connect

(800) 508-7008