Managing groups¶

A group is a named set of users. Content items, channels and sessions can be restricted to groups, so a group decides who sees what. This guide covers the requests that change a group's life: create it, hand it to other owners, and delete it once nothing depends on it.

None of these requests send an email. The web app emails a group's owners when someone else changes it. The API does not.

Create a group¶

POST /api/v2/groups/ creates a group, and the user your token belongs to becomes its first owner.

curl -X POST https://acme.plusplus.app/api/v2/groups/ \
  -H "Authorization: Bearer your_token_here" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Platform Guild", "description": "Engineers who own the platform services." }'

A group is private unless you send "is_private": false. Only its owners and Admins can see a private group.
Only Admins and Organizers can create a public group.
The name may not match, ignoring case, the name of a group you can see. A clash returns 409 with code name_taken, and the message names the existing group's public_id. Use that group or choose another name.

Add members with POST /api/v2/groups/{public_id}/members/.

Keep at least one owner¶

Owners manage a group: its members, owners, name and description. They can also delete it. Add owners before you remove one:

Add the new owner with POST /api/v2/groups/{public_id}/owners/ and { "owner_ids": ["<user public_id>"] }.
Remove the old owner with DELETE /api/v2/groups/{public_id}/owners/{owner_public_id}/.

If the removal would leave the group with no owner that GET /api/v2/groups/{public_id}/owners/ lists, the request returns 409 with code last_owner and changes nothing. Terminated and pending accounts are not listed, so they do not count as owners.

Delete a group that nothing uses¶

DELETE /api/v2/groups/{public_id}/ deletes a group. There is no undo: neither the API nor the web app can restore it.

Two kinds of group cannot be deleted:

Code	Group	Why
`managed_group`	A group synced from an HR integration (`source` is not `plusplus`).	The next sync creates the group again with a new `public_id`, and nothing restricted to the old group follows it. Remove the group from the integration instead.
`group_in_use`	A group that content items, channels, sessions, mentorship programs or navigation tabs are restricted to, or that an automated rule fills.	A deleted group still restricts these objects in lists but not when someone opens one by link. Their next edit removes the restriction, which opens them to everyone.

The group_in_use message counts each kind, for example 2 content items it restricts and 1 channel it restricts. To delete the group:

Find the channels restricted to the group with GET /api/v2/channels/?group=<group public_id>, and remove the group from each with DELETE /api/v2/channels/{public_id}/groups/{group_public_id}/.
Remove the group from the content items with DELETE /api/v2/content-items/bulk/access-policy/, or one item at a time with DELETE /api/v2/content-items/{public_id}/access-policy/groups/{group_public_id}/. An item left with no groups becomes open to everyone, so add the replacement group first if the item must stay restricted.
Change the automated rules that fill the group with the automated rules endpoints.
Remove the group from sessions, mentorship programs and navigation tabs in the web app.
Send the DELETE again.