# Roles

This resource lets you work with roles in YouTrack.

Available since YouTrack 2026.1.

|  Resource  |     ```GENERIC /api/roles ```    |
| --- | --- |
|  Returned entity  |  [Role](api-entity-Role.html). For the description of the entity attributes, see [Supported Fields](#Role-supported-fields) section.  |
|  Supported methods  |      * `GET`: [Read a List of Roles](#get_all-Role-method).    * `POST`: [Add a New Role](#create-Role-method).    |

## Role attributes

Represents a role in YouTrack.

Available since YouTrack 2026.1.

### Attributes

This table describes attributes of the `Role` entity.

* To receive an attribute in the response from the server, specify it explicitly in the `fields` request parameter.

* To update an attribute, provide it in the body of a POST request.

|  Field  |  Type  |  Description  |
| --- | --- | --- |
|  id  |  String  |  The database ID of the role. `Read-only`.  |
|  name  |  String  |  The name of the role.  |
|  description  |  String  |  The description of the role. `Can be null`.  |
|  permissions  |  [Array of Permissions](api-entity-Permission.html)  |  The list of permissions included in the role. `Read-only`.  |
|  immutable  |  Boolean  |  True if the role is immutable, otherwise false. Immutable roles cannot be updated or deleted. `Read-only`.  |

## Read a List of Roles

Get all roles.

### Required permissions

Requires Read permission in at least one scope (Low-level Admin Read, Read Organization, or Read Project), Update Organization, or Admin Read App.

### Request syntax

```GENERIC
GET /api/roles?{fields}&{$top}&{$skip}
```

|  null  |  The database ID of Role  |
| --- | --- |

### Request parameters

|  Parameter  |  Type  |  Description  |
| --- | --- | --- |
|  fields  |  String  |  A list of Role attributes that should be returned in the response. If no field is specified, only the `entityID` is returned.  |
|  $skip  |  Int  |  Optional. Lets you set a number of returned entities to skip before returning the first one.  |
|  $top  |  Int  |     Optional. Lets you specify the maximum number of entries that are returned in the response. If you don't set the $top value, the server limits the maximum number of returned entries.       The server returns a maximum of 42 entries for most resources that return collections. For more information, see [Pagination](api-concept-pagination.html).     |

## Add a New Role

Create a new role.

### Required permissions

Requires Admin Update App permission.

### Request syntax

```GENERIC
POST /api/roles?{fields}
```

|  null  |  The database ID of Role  |
| --- | --- |

### Request parameters

|  Parameter  |  Type  |  Description  |
| --- | --- | --- |
|  fields  |  String  |  A list of Role attributes that should be returned in the response. If no field is specified, only the `entityID` is returned.  |