# REST API v1 - Role API endpoints > For the complete documentation index, see [llms.txt](https://developers.thoughtspot.com/docs/llms.txt) Source: https://developers.thoughtspot.com/docs/role-api-v1 # REST API v1 - Role API endpoints > **IMPORTANT:** The REST API v1 endpoints are deprecated and replaced with the REST API v2 endpoints. Your existing integrations with REST API v1 endpoints will continue to function without disruption until further notice. ThoughtSpot strongly recommends migrating your integrations to the REST API v2 endpoints. ## Supported operations Use the Role API endpoints to programmatically create and manage role objects in ThoughtSpot. | API endpoint | Available from | | --- | --- | | `[**POST** /api/rest/2.0/roles/create]({{navprefix}}/{{roles-api}}#createRole)` Creates a Role. | ThoughtSpot Cloud 9.7.0.cl ThoughtSpot Software Not available | | `[**PUT** /tspublic/v1/role/{role_identifier}]({{navprefix}}/{{roles-api}}#editRole)` Edits the properties of a Role object. | ThoughtSpot Cloud 9.7.0.cl ThoughtSpot Software Not available | | [`**POST** /tspublic/v1/role/search`]({{navprefix}}/{{roles-api}}#searchRole) Gets Role objects. | ThoughtSpot Cloud 9.7.0.cl ThoughtSpot Software Not available | | [`**DELETE** /tspublic/v1/role/{role_identifier}`]({{navprefix}}/{{roles-api}}#deleteRole) Removes a Role object from ThoughtSpot. | ThoughtSpot Cloud 9.7.0.cl ThoughtSpot Software Not available | ## Required permissions - To create and manage roles, you need `ROLE_ADMINISTRATION`. - To assign roles to a group object, you need `GROUP_ADMINISTRATION` and `ROLE_ADMINISTRATION` privileges. ## Create a Role To create a Role, send a `POST` request to the `/tspublic/v1/role` API endpoint. ### Resource URL POST /tspublic/v1/role ### Request parameters | Form parameter | Description | | --- | --- | | `name` | _String_. Name of the Role. The Role name string must be unique. Make sure the name string length does not exceed 48 characters. | | `description` | _String_. Description of the Role. Make sure the description text does not exceed 124 characters. | | `privileges` | _Array of strings_. A JSON array of [Role privileges]({{navprefix}}/{{roles}}#_role_privileges). | ### Example request **cURL** curl -X POST / --header 'Content-Type: application/x-www-form-urlencoded' / --header 'Accept: application/json' / -d 'name=Role12&privileges=%5BA3ANALYSIS%2CDATAMANAGEMENT%5D' / 'https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/role' **Request URL** https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/role ### Example response ```JSON { "data": { "id": "15e2a628-f3b8-4709-8be2-ccc32365011a", "name": "Role_Analyst", "description": "Analyst Role", "privileges": [ "DATAMANAGEMENT", "A3ANALYSIS" ], "permission": "MODIFY", "author_id": "59481331-ee53-42be-a548-bd87be6ddd4a", "modifier_id": "59481331-ee53-42be-a548-bd87be6ddd4a", "creation_time_in_millis": 1698050499277, "modification_time_in_millis": 1698050499277, "deleted": false, "hidden": false, "deprecated": false, "external": false, "shared_via_connection": false } } ``` ### Response codes | HTTP status code | Description | | --- | --- | | **200** | Successful operation | | **400** | Invalid parameter | | **401** | Unauthorized access | | **403** | Forbidden access | | **500** | Internal error | ## Update a role object To edit the properties of a Role object, send a `POST` request to the `/tspublic/v1/role` API endpoint. ### Resource URL PUT /tspublic/v1/role/{role\_identifier} ### Request parameters | Parameter | Type | Description | | --- | --- | --- | | `role_identifier` | Path parameter | _String_. GUID of the role object to edit. | | `name` | Form parameter | _String_. Name of the Role that you want to edit. | | `description` | Form parameter | _String_. Description of the Role. | | `privileges` | Form parameter | _Array of strings_. A JSON array of [Role privileges]({{navprefix}}/{{roles}}#_role_privileges). | ### Example request **cURL** curl -X PUT / --header 'Content-Type: application/x-www-form-urlencoded' / --header 'Accept: application/json' / -d 'name=Role\_Analyst&description=Analyst%20Role&privileges=%5BJOBSCHEDULING%5D'/ 'https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/role/15e2a628-f3b8-4709-8be2-ccc32365011a' **Request URL** https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/role/15e2a628-f3b8-4709-8be2-ccc32365011a ### Example response ```JSON { "data": { "id": "15e2a628-f3b8-4709-8be2-ccc32365011a", "name": "Role_Analyst", "description": "Analyst Role", "privileges": [ "JOBSCHEDULING" "DATAMANAGEMENT", "A3ANALYSIS" ], "permission": "MODIFY", "author_id": "59481331-ee53-42be-a548-bd87be6ddd4a", "modifier_id": "59481331-ee53-42be-a548-bd87be6ddd4a", "creation_time_in_millis": 1698050499277, "modification_time_in_millis": 1698050499277, "deleted": false, "hidden": false, "deprecated": false, "external": false, "shared_via_connection": false } } ``` ### Response codes | HTTP status code | Description | | --- | --- | | **200** | Successful operation | | **400** | Invalid parameter | | **401** | Unauthorized access | | **403** | Forbidden access | | **500** | Internal error | ## Get role objects To get Role objects, send a `POST` request to the `/tspublic/v1/role/search` API endpoint. ### Resource URL POST /tspublic/v1/role/search ### Request parameters | Form parameter | Description | | --- | --- | | `role_identifiers` | _Array of strings_. A JSON array of the GUIDs or names of the Role objects. If no value is specified, the API returns all Role objects. | | `org_identifiers` | _Array of strings_. A JSON array of Org names or GUIDs. Applicable to instances with Orgs. If no value is specified, the API returns the Roles for the Org context from which the API request is sent. NOTE: Cluster administrators with the `Super admin` Role can query Role objects for different Orgs. The cluster administrator can switch to an Org context via an API call to the `/tspublic/v1/session/orgs` endpoint, and then specify the Org name or ID in the API request. | | `group_identifiers` | _Array of strings_. A JSON array of group names or GUIDs. | | `privileges` | _Array of strings_. A JSON array of [Role privileges]({{navprefix}}/{{roles}}#_role_privileges). | ### Example request **cURL** curl -X POST / --header 'Content-Type: application/x-www-form-urlencoded' / --header 'Accept: application/json' / 'https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/role/search' **Request URL** https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/role/search ### Example response ```JSON { "data": [ { "id": "298b1cad-44d6-4316-985d-8bdd331c8758", "name": "_Can download data", "description": "Can download data", "privileges": [ "DATADOWNLOADING" ], "groups": [ { "id": "d0326b56-ef23-4c8a-8327-a30e99bcc72b", "name": "Administrator" }, { "id": "280a2235-3721-43fc-aa25-5d33549ecc90", "name": "DataDownloader" } ], "permission": "MODIFY", "author_id": "0f0dd0f7-7411-4195-a4aa-0dc6b58413c9", "modifier_id": "0f0dd0f7-7411-4195-a4aa-0dc6b58413c9", "creation_time_in_millis": 1698049765805, "modification_time_in_millis": 1698049765805, "deleted": false, "hidden": false, "deprecated": false, "external": false, "shared_via_connection": false }, { "id": "aee60b22-9225-4120-8f8c-f094d81a8ced", "name": "_Can manage data", "description": "Can manage data", "privileges": [ "DATAMANAGEMENT" ], "groups": [ { "id": "d0326b56-ef23-4c8a-8327-a30e99bcc72b", "name": "Administrator" } ], "permission": "MODIFY", "author_id": "0f0dd0f7-7411-4195-a4aa-0dc6b58413c9", "modifier_id": "0f0dd0f7-7411-4195-a4aa-0dc6b58413c9", "creation_time_in_millis": 1698049765823, "modification_time_in_millis": 1698049765823, "deleted": false, "hidden": false, "deprecated": false, "external": false, "shared_via_connection": false }, { "id": "2c90269e-e09c-433f-b4b5-995564dfad70", "name": "_Can share with all users", "description": "Can share with all users", "privileges": [ "SHAREWITHALL" ], "groups": [ { "id": "d0326b56-ef23-4c8a-8327-a30e99bcc72b", "name": "Administrator" }, { "id": "983ddaab-15cf-4c95-a21e-67383a67b6d1", "name": "ShareWithAll" } ], "permission": "MODIFY", "author_id": "0f0dd0f7-7411-4195-a4aa-0dc6b58413c9", "modifier_id": "0f0dd0f7-7411-4195-a4aa-0dc6b58413c9", "creation_time_in_millis": 1698049765823, "modification_time_in_millis": 1698049765823, "deleted": false, "hidden": false, "deprecated": false, "external": false, "shared_via_connection": false }, { "id": "df1202a2-12c3-4748-9ee2-b2b9a6564618", "name": "_Can upload user data", "description": "Can upload user data", "privileges": [ "USERDATAUPLOADING" ], "groups": [ { "id": "d0326b56-ef23-4c8a-8327-a30e99bcc72b", "name": "Administrator" }, { "id": "314ac3fe-c5e1-4898-9cf7-29d9d455f052", "name": "UserDataUploader" } ], "permission": "MODIFY", "author_id": "0f0dd0f7-7411-4195-a4aa-0dc6b58413c9", "modifier_id": "0f0dd0f7-7411-4195-a4aa-0dc6b58413c9", "creation_time_in_millis": 1698049765821, "modification_time_in_millis": 1698049765821, "deleted": false, "hidden": false, "deprecated": false, "external": false, "shared_via_connection": false }, { "id": "3ca25423-4109-4cbc-aff3-e6310bf03095", "name": "_Has spotIQ privilege", "description": "Has spotIQ privilege", "privileges": [ "A3ANALYSIS" ], "groups": [ { "id": "d0326b56-ef23-4c8a-8327-a30e99bcc72b", "name": "Administrator" }, { "id": "c241143a-0e2b-44b6-9cbc-c2b3cff8c57d", "name": "Analyst" } ], "permission": "MODIFY", "author_id": "0f0dd0f7-7411-4195-a4aa-0dc6b58413c9", "modifier_id": "0f0dd0f7-7411-4195-a4aa-0dc6b58413c9", "creation_time_in_millis": 1698049765772, "modification_time_in_millis": 1698049765772, "deleted": false, "hidden": false, "deprecated": false, "external": false, "shared_via_connection": false }, { "id": "2e3ab92a-d0a6-4d6e-85b5-e6fe44fb8bfa", "name": "Super Admin", "description": "Role with Super Admin privilege", "privileges": [ "ADMINISTRATION" ], "groups": [ { "id": "d0326b56-ef23-4c8a-8327-a30e99bcc72b", "name": "Administrator" } ], "permission": "READ_ONLY", "author_id": "0f0dd0f7-7411-4195-a4aa-0dc6b58413c9", "modifier_id": "0f0dd0f7-7411-4195-a4aa-0dc6b58413c9", "creation_time_in_millis": 1698049765821, "modification_time_in_millis": 1698049765821, "deleted": false, "hidden": false, "deprecated": false, "external": false, "shared_via_connection": false } ] } ``` ### Response codes | HTTP status code | Description | | --- | --- | | **200** | Successful operation | | **400** | Invalid parameter | | **401** | Unauthorized access | | **403** | Forbidden access | | **500** | Internal error | ## Delete a Role To delete a Role, send a `DELETE` request to the `/tspublic/v1/role/{role_identifier}` API endpoint. ### Resource URL DELETE /tspublic/v1/role/{role\_identifier} ### Request parameters | Parameter | Type | Description | | --- | --- | --- | | `role_identifier` | Path parameter | _String_. GUID of the role object to delete. | ### Example request **cURL** curl -X DELETE / --header 'Accept: application/json' / 'https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/role/7c8446d2-d9f9-427e-953c-8ed5abc0a3bb' **Request URL** https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/role/15e2a628-f3b8-4709-8be2-ccc32365011a ### Example response If the delete operation is successful, the API returns a 204 response. 204 ### Response codes | HTTP status code | Description | | --- | --- | | **200** | Successful operation | | **400** | Invalid parameter | | **401** | Unauthorized access | | **403** | Forbidden access | | **500** | Internal error |