API: Groups - TestRail

API: Groups

Use the following API methods to request details about groups.

On this page:

    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": integer,
        "name": string,
        "user_ids": [integer list]
    }
    

    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_groups

    Response content

    {
        "offset": integer,
        "limit": integer,
        "size": integer,
        "_links": {
       	 "next": URL or null,
       	 "prev": URL or null,
        }
        "groups": [
       	 {
       		 //Entry consistent with get_group
       	 },...
        ]
    }
    

    Response codes

    Status Code Description
    200 Success, the groups were retrieved

    add_group

    Creates a new group

    POST index.php?/api/v2/add_group

    Request example

    Also see below for an example on 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.

    info Note: 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.