Groups : Swarm Groups
Support for APIs older than v9 will be removed in the Swarm 2022.2 release.
Get List of Groups
Summary
Get List of Groups
GET /api/v9/groups/
Description
Returns the complete list of groups in Swarm.
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 |
string |
query |
No |
|
max |
Maximum number of groups to return. This does not guarantee that |
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"
Swarm 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 Swarm.
curl -u "username:password" "https://myswarm.url/api/v9/groups?keywords=test-group&fields=Group,config&max=2&lastSeen=test-group2"
Swarm 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"
Swarm 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"
Swarm 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 Swarm.
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 Helix Core Server (
p4d
), or users with admin privileges inp4d
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, Swarm 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 Swarm. 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 Helix Core 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, Swarm 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, Swarm
responds with the id
of the deleted group:
HTTP/1.1 200 OK
{
"id": "my-group"
}