Groups API
10 endpoints. Request and response schemas are described on the schemas page; the other tags are listed in the API index.
Endpoints
GET /api/v1/groups
List groups
List all groups
Responses
| Status | Description | Body |
|---|---|---|
200 | List of groups | application/json: object |
403 | Forbidden | application/json: Error |
Fields of the 200 response (application/json):
| Field | Type | Required | Description |
|---|---|---|---|
data | array of Group | no | - |
POST /api/v1/groups
Create group
Create a new group
Request body (required)
application/json: object
| Field | Type | Required | Description |
|---|---|---|---|
description | string | no | - |
name | string | yes | - |
Responses
| Status | Description | Body |
|---|---|---|
201 | Group created | application/json: Group |
400 | Invalid request | application/json: Error |
403 | Forbidden | application/json: Error |
GET /api/v1/groups/{id}
Get group
Get details of a specific group
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | - |
Responses
| Status | Description | Body |
|---|---|---|
200 | Group details | application/json: Group |
400 | Invalid request, including a NUL byte in the URL or the body | application/json: Error |
403 | Forbidden | application/json: Error |
404 | Group not found | - |
PATCH /api/v1/groups/{id}
Update group
Update a group
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | - |
Request body (required)
application/json: object
| Field | Type | Required | Description |
|---|---|---|---|
description | string | no | - |
name | string | no | - |
Responses
| Status | Description | Body |
|---|---|---|
200 | Group updated | application/json: Group |
400 | Invalid request, including a NUL byte in the URL or the body | application/json: Error |
403 | Forbidden | application/json: Error |
404 | Group not found | - |
DELETE /api/v1/groups/{id}
Delete group
Delete a group
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | - |
Responses
| Status | Description | Body |
|---|---|---|
204 | Group deleted | - |
400 | Invalid request, including a NUL byte in the URL or the body | application/json: Error |
403 | Forbidden | application/json: Error |
404 | Group not found | - |
GET /api/v1/groups/{id}/members
List group members
List members of a group
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | - |
Responses
| Status | Description | Body |
|---|---|---|
200 | List of group members | application/json: object |
400 | Invalid request, including a NUL byte in the URL or the body | application/json: Error |
403 | Forbidden | application/json: Error |
404 | Group not found | - |
Fields of the 200 response (application/json):
| Field | Type | Required | Description |
|---|---|---|---|
members | array of GroupMember | no | - |
PUT /api/v1/groups/{id}/members
Set group members
Replace all members of a group
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | - |
Request body (required)
application/json: object
| Field | Type | Required | Description |
|---|---|---|---|
members | array of string (uuid) | yes | - |
Responses
| Status | Description | Body |
|---|---|---|
204 | Members updated | - |
400 | Invalid request | application/json: Error |
403 | Forbidden | application/json: Error |
404 | Group not found | - |
POST /api/v1/groups/{id}/members/{userId}
Add group member
Add a user to a group
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | - |
userId | path | string (uuid) | yes | - |
Responses
| Status | Description | Body |
|---|---|---|
200 | Member added | - |
400 | Invalid request, including a NUL byte in the URL or the body | application/json: Error |
403 | Forbidden | application/json: Error |
404 | Group or user not found | - |
DELETE /api/v1/groups/{id}/members/{userId}
Remove group member
Remove a user from a group
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | - |
userId | path | string (uuid) | yes | - |
Responses
| Status | Description | Body |
|---|---|---|
204 | Member removed | - |
400 | Invalid request, including a NUL byte in the URL or the body | application/json: Error |
403 | Forbidden | application/json: Error |
404 | Group or user not found | - |
GET /api/v1/users/{id}/groups
List user's groups
List groups that a user belongs to
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | - |
Responses
| Status | Description | Body |
|---|---|---|
200 | List of groups | application/json: object |
400 | Invalid request, including a NUL byte in the URL or the body | application/json: Error |
403 | Forbidden | application/json: Error |
404 | User not found | - |
Fields of the 200 response (application/json):
| Field | Type | Required | Description |
|---|---|---|---|
data | array of Group | no | - |