Helix Core is now P4 and Helix Swarm is now P4 Code Review. Product user interfaces will be updated soon. Learn more >>

Documentation | 2025.5

# Groups : P4 Code Review Groups

From P4 Code Review 2022.2, P4 Code Review no longer supports APIs older than v9.

## Get List of Groups

### Summary

Get List of Groups

GET /api/v9/groups/

### Description

Returns the complete list of groups in P4 Code Review.

### Parameters

Parameter | Description | Type | Parameter Type | Required | Default Value
--- | --- | --- | --- | --- | ---
after | A group ID to seek to. Groups prior to and including the specified ID are excluded from the results and do not count towards `max`. Useful for pagination. Commonly set to the `lastSeen` property from a previous query. | string | query | No |
max | Maximum number of groups to return. This does not guarantee that `max` groups are returned. It does guarantee that the number of groups returned won’t exceed `max`. | integer | query | No | 100
fields | An optional comma-separated list (or array) of fields to show for each group. Omitting this parameter or passing an empty value shows all fields. | string | query | No |
keywords | Keywords to limit groups on. Only groups where the group ID, group name (if set), or description contain the specified keywords are returned. | string | query | No |
ignoreExcludeList | Determines if the list of groups has the group_exclude_list filter applied or not. Add the parameter to ignore the group_exclude_list filter. | boolean | query | No |

### Example response

#### Successful Response:

    HTTP/1.1 200 OK

    {
      "groups": [
        {
          "Group": "test-group",
          "MaxLockTime": null,
          "MaxResults": null,
          "MaxScanRows": null,
          "Owners": [],
          "PasswordTimeout": null,
          "Subgroups": [],
          "Timeout": 43200,
          "Users": ["bruno"],
          "config": {
            "description": "Our testing group",
            "emailAddress": "test-group3@host.domain",
            "emailFlags": [],
            "name": "Test Group",
            "useMailingList": true
          }
        }
      ]
    }

### Examples of usage

#### Listing groups

To list groups:

    curl -u "username:password" "https://myswarm.url/api/v9/groups?keywords=test-group&fields=Group,Owners,Users,config&max=2"

P4 Code Review responds with a list of groups:

    HTTP/1.1 200 OK

    {
      "groups": [
        {
          "Group": "test-group",
          "Owners": [],
          "Users": ["bruno"],
          "config": {
            "description": "Our testing group",
            "emailAddress": "test-group@host.domain",
            "emailFlags": {
              "reviews": "1",
              "commits": "0"
            },
            "name": "Test Group",
            "useMailingList: true
          }
        },
        {
          "Group": "test-group2",
          "Owners": [],
          "Users": ["bruno"],
          "config": {
            "description": "Our second testing group",
            "emailAddress": "test-group2@host.domain",
            "emailFlags": [],
            "name": "Test Group 2",
            "useMailingList: true
          }
        }
      ],
      "lastSeen": "test-group2"
    }

#### Paginating the groups list

Based on the previous example, we can pass a lastSeen value of `test-group2` to see if there are any subsequent groups in P4 Code Review.

    curl -u "username:password" "https://myswarm.url/api/v9/groups?keywords=test-group&fields=Group,config&max=2&lastSeen=test-group2"

P4 Code Review responds with a list of groups (minus the Owners and Users fields, as we haven’t requested them):

    HTTP/1.1 200 OK

    {
      "groups": [
        {
          "Group": "test-group3",
          "config": {
            "description": "Our 3rd testing group",
            "emailAddress": "test-group3@host.domain",
            "emailFlags": [],
            "name": "Test Group 3",
            "useMailingList": true
          }
        }
      ],
      "lastSeen": "test-group3"
    }

## Get Group Information

### Summary

Get Group Information

GET /api/v9/groups/{id}

### Description

Retrieve information about a group.

### Parameters

Parameter | Description | Type | Parameter Type | Required
--- | --- | --- | --- | ---
id | Group ID | string | path | Yes
fields | An optional comma-separated list (or array) of fields to show for each group. Omitting this parameter or passing an empty value shows all fields. | string | query | No
ignoreExcludeList | Determines if the group_exclude_list filter is applied or not when getting the group information. If the filter is applied and the group specified is present in the group_exclude_list the group information is not included in the response. Add the parameter to ignore the group_exclude_list filter. | boolean | query | No

### Example response

#### Successful Response:

    HTTP/1.1 200 OK

    {
      "group": {
        "Group": "test-group",
        "MaxLockTime": null,
        "MaxResults": null,
        "MaxScanRows": null,
        "Owners": [],
        "PasswordTimeout": null,
        "Subgroups": [],
        "Timeout": 43200,
        "Users": ["bruno"],
        "config": {
          "description": "Our testing group",
          "emailFlags": [],
          "name": "Test Group"
        }
      }
    }

### Examples of usage

#### Fetching a group

To fetch an individual group:

    curl -u "username:password" "https://myswarm.url/api/v9/groups/my-group"

P4 Code Review responds with the group entity:

    HTTP/1.1 200 OK

    {
      "group": {
        "Group": "test-group",
        "LdapConfig": null,
        "LdapSearchQuery": null,
        "LdapUserAttribute": null,
        "MaxLockTime": null,
        "MaxResults": null,
        "MaxScanRows": null,
        "Owners": [],
        "Users": ["bruno"],
        "config": {
          "description": "Our testing group",
          "emailAddress": "test-group@host.domain",
          "emailFlags": {
            "reviews": "1",
            "commits": "0"
          },
          "name": "Test Group",
          "useMailingList": true
        }
      }
    }

#### Limiting returned fields

To limit the returned fields when fetching an individual group:

    curl -u "username:password" "https://myswarm.url/api/v9/groups/my-group?fields=Group,Owners,Users,config"

P4 Code Review responds with the group entity:

    HTTP/1.1 200 OK

    {
      "group": {
        "Group": "test-group",
        "Owners": [],
        "Users": ["bruno"],
        "config": {
          "description": "Our testing group",
          "emailFlags": [],
          "name": "Test Group"
        }
      }
    }

## Create a new Group

### Summary

Create a new Group

POST /api/v9/groups/

### Description

Creates a new group in P4 Code Review.

### Parameters

Parameter | Description | Type | Parameter Type | Required
--- | --- | --- | --- | ---
Group | Group identifier string. | string | form | Yes
Users | An optional array of group users. *At least one of Users, Owners, or Subgroups is required. | array | form | No *See Description
Owners | An optional array of group owners. *At least one of Users, Owners, or Subgroups is required. | array | form | No *See Description
Subgroups | An optional array of subgroups. *At least one of Users, Owners, or Subgroups is required. | array | form | No *See Description
config[name] | An optional full name for the group. | string | form | No
config[description] | An optional group description. | string | form | No
config[emailAddress] | The email address for this group. | string | form | No
config[emailFlags][reviews] | Email members when a new review is requested. | boolean | form | No
config[emailFlags][commits] | Email members when a change is committed. | boolean | form | No
config[useMailingList] | Whether to use the configured email address or expand individual members addresses. | boolean | form | No

### Example response

#### Successful Response:

    HTTP/1.1 200 OK

    {
      "group": {
        "Group": "test-group",
        "MaxLockTime": null,
        "MaxResults": null,
        "MaxScanRows": null,
        "Owners": [],
        "PasswordTimeout": null,
        "Subgroups": [],
        "Timeout": null,
        "Users": ["alice"],
        "config": {
          "description": "Test test test",
          "emailAddress": "test-group@host.domain",
          "emailFlags": [],
          "name": "TestGroup",
          "useMailingList": true
        }
      }
    }

### Example of usage

#### Create a group

- Only users with super privileges in the P4 Server (`p4d`), or users with admin privileges in `p4d` versions 2012.1 or newer, can create groups.
- This API version is only capable of setting specific fields: `Group`, `Users`, `Owners`, `Subgroups`, `config`. Any other fields specified in the creation request are ignored.

To create a new group:

    curl -u "username:password" \
         -X POST \
         -d "Group=my-group" \
         -d "Owners[]=alice" \
         -d "Owners[]=bob" \
         -d "Users[]=bruno" \
         -d "Users[]=user2" \
         -d "config[description]=This group is special to me." \
         -d "config[name]=My Group" \
         -d "config[emailFlags][reviews]=1" \
         -d "config[emailFlags][commits]=0" \
         -d "config[emailAddress]=my-group@host.domain" \
         -d "config[useMailingList]=false" \
         "https://myswarm.url/api/v9/groups"

Assuming that the authenticated user has permission, P4 Code Review responds with the new group entity:

    HTTP/1.1 200 OK

    {
      "group": {
        "Group": "my-group",
        "MaxLockTime": null,
        "MaxResults": null,
        "MaxScanRows": null,
        "Owners": ["username"],
        "PasswordTimeout": null,
        "Subgroups": [],
        "Timeout": null,
        "Users": [],
        "config": {
          "description": "This group is special to me.",
          "emailFlags": {
            "reviews": "1",
            "commits": "0"
          },
          "name": "My Group",
          "useMailingList": true
        }
      }
    }

## Edit a Group

### Summary

Edit a Group

PATCH /api/v9/groups/{id}

### Description

Change the settings of a group in P4 Code Review. Only super users and group owners can perform this action.

### Parameters

Parameter | Description | Type | Parameter Type | Required
--- | --- | --- | --- | ---
id | Group ID | string | path | Yes
Users | An optional array of group users. | array | form | No
Owners | An optional array of group owners. | array | form | No
Subgroups | An optional array of group subgroups. | array | form | No
config[name] | An optional full name for the group. | string | form | No
config[description] | An optional group description. | string | form | No
config[emailAddress] | The email address for this group. | string | form | No
config[emailFlags][commits] | Email members when a change is committed. | boolean | form | No
config[emailFlags][reviews] | Email members when a new review is requested. | boolean | form | No
config[useMailingList] | Whether to use the configured email address or expand individual members addresses. | boolean | form | No

### Example response

#### Successful Response:

    HTTP/1.1 200 OK

    {
      "group": {
        "Group": "test-group",
        "Users": [],
        "Owners": [],
        "Subgroups": [],
        "config": {
          "description": "New Group Description",
          "name": "TestGroup",
          "useMailingList": true
        }
      }
    }

### Example of usage

#### Editing a group

- Only users with super privileges in the P4 Server, or group owners, can edit groups.
- This API version is only capable of modifying specific fields: `Users`, `Owners`, `Subgroups`, `config`. Any other fields specified in the edit request are ignored.

Here is how to update the `name`, `description`, and `emailFlags` configuration of the group `my-group`:

    curl -u "username:password" \
         -X PATCH \
         -d "config[description]=This group is special to me." \
         -d "config[name]=My Group" \
         -d "config[emailFlags][commits]=1" \
         "https://myswarm.url/api/v9/groups/my-group"

Assuming that the authenticated user has permission, P4 Code Review responds with the modified group entity:

    HTTP/1.1 200 OK

    {
      "group": {
        "Group": "my-group",
        "Users": [],
        "Owners": [],
        "Subgroups": [],
        "config": {
          "description": "This group is special to me.",
          "emailAddress": "test-group@host.domain",
          "emailFlags": {
            "reviews": "1",
            "commits": "1"
          },
          "name": "My Group",
          "useMailingList": true
        }
      }
    }

## Delete a Group

### Summary

Delete a Group

DELETE /api/v9/groups/{id}

### Description

Delete a group. Only super users and group owners can perform this action.

### Parameters

Parameter | Description | Type | Parameter Type | Required
--- | --- | --- | --- | ---
id | Group ID. | string | path | Yes

### Example response

#### Successful Response:

    HTTP/1.1 200 OK

    {
      "id": "test-group"
    }

### Example of usage

#### Deleting a group

Only super users and group owners can delete groups.

    curl -u "username:password" -X DELETE "https://myswarm.url/api/v9/groups/my-group"

Assuming that the authenticated user has permission, P4 Code Review responds with the `id` of the deleted group:

    HTTP/1.1 200 OK

    {
      "id": "my-group"
    }

Your search for returned results