Groups
warning
This is a Hub REST API method, which uses the Hub REST API URL.
We're including this page in the YouTrack REST API section for reference. For more details, see Hub REST API reference.
This resource provides access to user groups in Hub and YouTrack.
Resource |
|
Returned entity | UserGroup. For the description of the entity attributes, see UserGroup Attributes. |
Supported methods |
|
Supported sub-resources |
|
Group Attributes
Represents a group in Hub and YouTrack.
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 unique identifier of the group. |
aliases | Set.<alias> | The set of IDs of user groups that have been merged into this group. |
allUsers | Boolean | |
autoJoin | Boolean | Determines whether new users are added to this group automatically. |
autoJoinDomain | String | Stores an optional email domain used for auto-joining users to this group. If the user's email belongs to this domain, they are added to this group automatically. |
description | String | The description of the group. |
iconUrl | String | The URL of the icon of the group. |
name | String | The name of the group. |
organizations | Set.<organization> | The list of organizations that this group belongs to. |
ownUsers | Set.<user> | The list of users that belong to this group directly. |
parent | userGroup | The parent group that this group belongs to. |
project | Set.<project> | The list of projects in which the group is used as a resource. |
projectRoles | Set.<projectRole> | The list of project roles assigned to the users of this group. |
subgroups | Set.<userGroup> | The list of groups that belong to this group as sub-groups. |
userCount | Integer | The number of users that belong to the group. |
users | Set.<user> | The list of all users that belong to this group. |
Read a List of Groups
Get all groups that match the specified query.
tip
Requires permissions: Read Group
Request Syntax
GET <Hub Service URL>/api/rest/usergroups?{fields}&{$top}&{$skip}&{query}&{orderBy}
Request Parameters
Parameter | Type | Description |
---|---|---|
fields | String | Optional. Returns only the specified subset of the fields for each group. Use Fields Syntax to define the subset. |
$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 UserGroups that are returned in the response. |
query | String | Optional. Lets you specify a search query to filter the returned results. See Query Syntax for the definition of supported logical operations syntax. For the UserGroup fields and tuples, see Hub REST API Reference. |
orderBy | String | Optional Returns the list of Users sorted by a specified field. See Sorting Syntax for details. UserGroups support ordering by the following fields: |
Sample
Request
https://example.youtrack.cloud/hub/api/rest/usergroups?fields=id,name,users(id,login),projectRoles(id,project(name),role(name))&top=100
Response Body
{
"type": "UsergroupsPage",
"next": "https://example.youtrack.cloud/hub/api/rest/usergroups?%24skip=100&%24top=100",
"skip": 0,
"top": 100,
"usergroups": [
{
"type": "userGroup",
"id": "fd7a85de-a711-411d-89a7-ce66bda480de",
"name": "All Users",
"users": [
{
"type": "user",
"id": "7845f294-dc19-4082-8d43-e69080f33fe6",
"login": "guest"
},
{
"type": "user",
"id": "c408bf43-ab05-476f-9b36-a9fe0cad45c9",
"login": "john.smith"
},
{
"type": "user",
"id": "320d31a1-352f-48b7-a454-6845300b7e7d",
"login": "Donna_Noble"
},
{
"type": "user",
"id": "7a1573d6-a39e-4724-80e7-081acb8d2c99",
"login": "william.johnson"
},
{
"type": "user",
"id": "55bf83fc-a8c4-47d0-ab72-f39ca7461a55",
"login": "Jane.Doe"
}
]
},
{
"type": "userGroup",
"id": "0e515027-3666-4e37-868f-272fdbae89ff",
"name": "Monitoring Staff",
"projectRoles": [
{
"type": "projectRole",
"id": "6934bda9-5ffb-4029-9d14-2c31230a12df",
"role": {
"name": "Contributor",
"immutable": false
},
"project": {
"name": "Monitoring"
}
}
],
"users": [
{
"type": "user",
"id": "7a1573d6-a39e-4724-80e7-081acb8d2c99",
"login": "william.johnson"
},
{
"type": "user",
"id": "55bf83fc-a8c4-47d0-ab72-f39ca7461a55",
"login": "Jane.Doe"
}
]
}
]
}
Add a Group
Create a group.
Required fields: name
.
tip
Requires permissions: Create Group, Update Group, Update Project
Request Syntax
POST <Hub Service URL>/api/rest/usergroups?fields=string
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 |
Sample
In this example, we create a group with the name Helpdesk
.
Request
https://example.youtrack.cloud/hub/api/rest/usergroups?fields=id,name,users(login)
Request Body
{
"type": "userGroup",
"name": "Helpdesk",
"users": [
{
"type": "user",
"id": "368f7edd-57a6-482a-b0ca-5255af60097a",
"login": "root"
},
{
"type": "user",
"id": "c408bf43-ab05-476f-9b36-a9fe0cad45c9",
"login": "john.smith"
},
{
"type": "user",
"id": "34d6eac2-e1e7-4f47-b2de-dd21d592c5d1",
"login": "minnie.terry"
}
]
}
Response Body
{
"type": "userGroup",
"id": "a17c8030-6f4e-409e-848e-f5c2b711e6af",
"name": "Helpdesk",
"users": [
{
"type": "user",
"login": "root"
},
{
"type": "user",
"login": "john.smith"
},
{
"type": "user",
"login": "minnie"
}
]
}