Use the following API methods to request details about groups.
Groups endpoints are only available in TestRail 7.5 or later.
get_group
Returns an existing group.
GET index.php?/api/v2/get_group/{group_id}Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| group_id | integer | true | The ID of the group |
Response content
{
"id": 1,
"name": "New group",
"user_ids": [1, 2, 3, 4, 5]
}
The following fields are included in the response:
| Name | Type | Description |
|---|---|---|
| id | integer | The unique ID of the group |
| name | string | The name of the group |
| user_ids | array | An array of user IDs. Each ID is a user belonging to this group |
Response codes
| Status Code | Description |
|---|---|
| 200 | Success (the group was retrieved) |
| 400 |
Invalid group_id parameter |
get_groups
Returns the list of available groups.
GET index.php?/api/v2/get_groupsResponse content
{
"offset": 0,
"limit": 250,
"size": 0,
"_links": {
"next": null,
"prev": null,
},
"groups": [
{
"id": 1,
"name": "New group",
"user_ids": [1, 2, 3, 4, 5]
}
]
}Response codes
| Status Code | Description |
|---|---|
| 200 | Success (the groups were retrieved) |
add_group
Creates a new group.
POST index.php?/api/v2/add_groupRequest example
Also, see below for an example of how to create a new group
{
"name": "New Group",
"user_ids": [1, 2, 3, 4, 5]
}Response content
If successful, this method returns the new group using the same response format as get_group.
The following fields are included in the response:
| Name | Type | Description |
|---|---|---|
| name | string | The name of the group |
| user_ids | array | An array of user IDs. Each ID is a user belonging to this group |
Response codes
| Status Code | Description |
|---|---|
| 200 | Success (the group was created) |
| 400 |
Invalid field value, such as an invalid ID in the user_ids array |
| 403 |
No permission to create user groups |
update_group
Updates an existing group.
POST index.php?/api/v2/update_group/{group_id}Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| group_id | integer | true | The ID of the group |
This endpoint supports the same fields as add_group.
Using update_group will set the group’s members to match the user_ids array provided. It is not possible to add or remove users. The user_ids array submitted should always be the full list of users in the group.
Response content
If successful, this method returns the new group using the same response format as get_group.
Response codes
| Status Code | Description |
|---|---|
| 200 | Success (the group was updated) |
| 400 |
Invalid field value, such as an invalid ID in the user_ids array |
| 403 |
No permission to edit user groups |
delete_group
Deletes an existing group.
POST index.php?/api/v2/delete_group/{group_id}Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| group_id | integer | true | The ID of the group |
Response content
This endpoint does not return any group data.
Response codes
| Status Code | Description |
|---|---|
| 200 | Success (the group was deleted) |
| 400 | Invalid group_id |
| 403 | No permission to delete user groups |