Groups
User groups — named bundles of users used for organizational structure, role assignment, and permission grouping. Group records plus membership operations are managed here.
Scopes
| Scope | Reach |
|---|---|
groups:read | Listing, reading groups and their members. |
groups:write | Creating, modifying, deleting groups; managing membership. |
Endpoints
List Groups
GET /api/admin/groups/
Returns a page of group records.
Required scope: groups:read · also accepts API key
Query parameters — standard pagination set; see Conventions › Pagination. Defaults: sort_by=created, sort_order=desc, hydrate=true.
Response 200 — GroupInDbCursorPage
Get Group Filter Metadata
GET /api/admin/groups/filters
Returns filter/operator/sort options for List Groups.
Required scope: groups:read
Response 200 — open metadata object.
Get Group by ID
GET /api/admin/groups/{id}
Returns a single group record.
Required scope: groups:read · also accepts API key
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | Group ID. |
Response 200 — GroupRead
Get Group Users
GET /api/admin/groups/{id}/users
Returns the list of users belonging to a group.
Required scope: groups:read
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | Group ID. |
Response 200 — list of user records.
Create Group
POST /api/admin/groups/
Creates a new group.
Required scope: groups:write
Request body — GroupWriteCreate
Response 201 — GroupRead
Update Group by ID
PUT /api/admin/groups/{id}
Replaces the group record.
Required scope: groups:write
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | Group ID. |
Request body — GroupWriteReplace
Response 200 — GroupRead
Patch Group
PATCH /api/admin/groups/{id}
Partial group update.
Required scope: groups:write
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | Group ID. |
Request body — GroupWriteUpdate
Response 200 — GroupRead
Delete Group by ID
DELETE /api/admin/groups/{id}
Removes a group. Users that were members remain — only the group record (and their membership of it) goes away.
Required scope: groups:write
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | Group ID. |
Response 204 — empty.
Add User to Group
POST /api/admin/groups/{id}/users/{user_id}
Adds a user to a group.
Required scope: groups:write
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | Group ID. |
user_id | string | yes | User ID. |
Response 201 — UserRead (the user record, now reflecting group membership).
Remove User from Group
DELETE /api/admin/groups/{id}/users/{user_id}
Removes a user from a group.
Required scope: groups:write
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | Group ID. |
user_id | string | yes | User ID. |
Response 200 — confirmation payload.
See also
- Users — user records added to / removed from groups here.
- Scope Sets — attach scope bundles to groups via a group's scope-set membership (see the group record schema).