# User Groups

This resource lets you work with the groups added to the project team.
Available since YouTrack 2026.1.

|  Resource  |     ```GENERIC /api/admin/projects/{projectID}/team/groups ```    |
| --- | --- |
|  Returned entity  |  [UserGroup](api-entity-UserGroup.html). For the description of the entity attributes, see [Supported Fields](#UserGroup-supported-fields) section.  |
|  Supported methods  |      * `GET`: [Read a List of UserGroups](#get_all-UserGroup-method).    * `POST`: [Add a New UserGroup](#create-UserGroup-method).    |

## UserGroup attributes

Represents a group of users.

### Related Resources

Below you can find the list of resources that let you work with this entity.

* [User Groups](resource-api-groups.html)

* [User Groups in the User Bundle](resource-api-admin-customFieldSettings-bundles-user-bundleID-groups.html)

### Attributes

This table describes attributes of the `UserGroup` 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 ID of the user group. `Read-only`.  |
|  name  |  String  |  The name of the group.  |
|  ringId  |  String  |  ID of the group in Hub. Use this ID for operations in Hub, and for matching groups between YouTrack and Hub. `Read-only`. `Can be null`.  |
|  usersCount  |  Long  |  The number of users in the group. `Read-only`.  |
|  icon  |  String  |  The URL of the group logo. `Read-only`. `Can be null`.  |
|  allUsersGroup  |  Boolean  |  True if this group contains all users, otherwise false. `Read-only`.  |
|  users  |  [Array of Users](api-entity-User.html)  |  All users in this group, including transitive users. `Read-only`.  |

## Read a List of UserGroups

Read the list of groups added to the project team.

### Required permissions

Requires permissions: Read Project.

Alternatively, requires Read Project Basic permission and access to the "Read Groups" feature, Update Project permission, or Low-Level Admin Read permission.

### Request syntax

```GENERIC
GET /api/admin/projects/{projectID}/team/groups?{fields}&{$top}&{$skip}
```

|  null  |  The database ID of UserGroup  |
| --- | --- |

### Request parameters

|  Parameter  |  Type  |  Description  |
| --- | --- | --- |
|  fields  |  String  |  A list of UserGroup 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).     |

### Sample

#### Sample request

```CURL
https://example.youtrack.cloud/api/admin/projects/0-6/team/groups?fields=id,name
```

#### Sample response body

```JSON
[
  {
    "name": "Developers",
    "id": "23-1",
    "$type": "NestedGroup"
  }
]
```

## Add a Group to the Project Team

Add a group to the project team.

### Required permissions

Requires permissions: Update Project.

### Request syntax

```GENERIC
POST /api/admin/projects/{projectID}/team/groups?{fields}
```

|  null  |  The database ID of UserGroup  |
| --- | --- |

### Request parameters

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

### Sample

#### Sample request

```CURL
https://example.youtrack.cloud/api/admin/projects/0-6/team/groups?fields=id,name
```

#### Sample request body

```JSON
{
  "id": "23-2",
  "$type": "NestedGroup"
}
```

#### Sample response body

```JSON
{
  "name": "QA Engineers",
  "id": "23-2",
  "$type": "NestedGroup"
}
```