Groups
To get more detailed information about the contents of the requested/returned
representation of resources related to groups, see also Group
and
Revision
. For possible role values, see also the Miscellaneous endpoints.
GET
Search and filter for groups. |
|
Get a group revision. |
|
Get the group specified by the given id. |
|
Get collections shared with the group with the given id. |
|
Get members of the group specified by the given id. |
|
Get records shared with the group with the given id. |
|
Get revisions of the group specified by the given id. |
|
Get templates shared with the group with the given id. |
|
Get the group specified by the given identifier. |
- GET /api/groups
Search and filter for groups.
Versions:
v1
(latest)Required scopes:
group.read
Query parameters
page - The current result page, limited to a maximum of
100
. (Default:1
)per_page - Number of results per page, limited to a maximum of
100
. (Default:10
)query - A query to search the groups with. Supports exact matches when surrounded by double quotes.
sort - The order of the search results. One of
_score
,last_modified
,-last_modified
,created_at
,-created_at
,title
,-title
,identifier
or-identifier
. Falls back to-last_modified
if no search query is given. (Default:_score
)visibility - A visibility value to filter the groups with. One of
private
orpublic
.member_only - Flag indicating whether only groups with membership should be included permissions should be included, independent of their visibility. (Default:
False
)user - User IDs to filter the groups with in relation to their creator. All given users are filtered using an OR operation. (Can be specified more than once.)
Status codes
200 (OK) - Return a paginated array of groups.
- GET /api/groups/(int: group_id)/revisions/(int: revision_id)
Get a group revision.
Will return the revision specified by the given revision_id of the group specified by the given group_id.
Versions:
v1
(latest)Required scopes:
group.read
Query parameters
revision - The ID of a revision to compare with instead of the previous one.
Status codes
200 (OK) - Return the revision.
- GET /api/groups/(int: id)
Get the group specified by the given id.
Versions:
v1
(latest)Required scopes:
group.read
Status codes
200 (OK) - Return the group.
- GET /api/groups/(int: id)/collections
Get collections shared with the group with the given id.
Shared means that the group needs to have at least explicit read permission for a collection.
Versions:
v1
(latest)Required scopes:
group.read
andcollection.read
Query parameters
page - The current result page. (Default:
1
)per_page - Number of results per page, limited to a maximum of
100
. (Default:10
)filter - A query to filter the collections by their title or identifier.
sort - The order of the returned collections. One of
last_modified
,-last_modified
,created_at
,-created_at
,title
,-title
,identifier
or-identifier
. (Default:-last_modified
)
Status codes
200 (OK) - Return a paginated array of collections.
- GET /api/groups/(int: id)/members
Get members of the group specified by the given id.
Versions:
v1
(latest)Required scopes:
group.read
anduser.read
Query parameters
page - The current result page. (Default:
1
)per_page - Number of results per page, limited to a maximum of
100
. (Default:10
)filter - A query to filter the members by their username or display name.
exclude - User IDs to exclude. (Can be specified more than once.)
Status codes
200 (OK) - Return a paginated array of members, sorted by role name and then by user ID in ascending order. The creator will always be listed first.
- GET /api/groups/(int: id)/records
Get records shared with the group with the given id.
Shared means that the group needs to have at least explicit read permission for a record.
Versions:
v1
(latest)Required scopes:
group.read
andrecord.read
Query parameters
page - The current result page. (Default:
1
)per_page - Number of results per page, limited to a maximum of
100
. (Default:10
)filter - A query to filter the records by their title or identifier.
sort - The order of the returned records. One of
last_modified
,-last_modified
,created_at
,-created_at
,title
,-title
,identifier
or-identifier
. (Default:-last_modified
)
Status codes
200 (OK) - Return a paginated array of records.
- GET /api/groups/(int: id)/revisions
Get revisions of the group specified by the given id.
Versions:
v1
(latest)Required scopes:
group.read
Query parameters
page - The current result page. (Default:
1
)per_page - Number of results per page, limited to a maximum of
100
. (Default:10
)
Status codes
200 (OK) - Return a paginated array of revisions, sorted by revision timestamp in descending order.
- GET /api/groups/(int: id)/templates
Get templates shared with the group with the given id.
Shared means that the group needs to have at least read permission for a template.
Versions:
v1
(latest)Required scopes:
group.read
andtemplate.read
Query parameters
page - The current result page. (Default:
1
)per_page - Number of results per page, limited to a maximum of
100
. (Default:10
)filter - A query to filter the templates by their title or identifier.
sort - The order of the returned templates. One of
last_modified
,-last_modified
,created_at
,-created_at
,title
,-title
,identifier
or-identifier
. (Default:-last_modified
)
Status codes
200 (OK) - Return a paginated array of templates.
- GET /api/groups/identifier/(identifier: identifier)
Get the group specified by the given identifier.
Versions:
v1
(latest)Required scopes:
group.read
Status codes
200 (OK) - Return the group.
POST
Create a new group. |
|
Add a member to the group specified by the given id. |
|
Purge the deleted group specified by the given id. |
|
Restore the deleted group specified by the given id. |
- POST /api/groups
Create a new group.
Versions:
v1
(latest)Required scopes:
group.create
Request JSON object
The metadata of the new group.
identifier (Required) - String
title (Required) - String
description - String
visibility - String
Status codes
201 (Created) - Return the new group.
409 (Conflict) - A conflict occured while trying to create the group.
- POST /api/groups/(int: id)/members
Add a member to the group specified by the given id.
Versions:
v1
(latest)Required scopes:
group.members
Request JSON object
The member and corresponding role to add.
role (Required) - Object
name (Required) - String
user (Required) - Object
id (Required) - Integer
Status codes
201 (Created) - Member successfully added to group.
409 (Conflict) - Member already exists.
- POST /api/groups/(int: id)/purge
Purge the deleted group specified by the given id.
Will delete the group permanently. Only the creator of a group can purge it.
Versions:
v1
(latest)Required scopes:
misc.manage_trash
Status codes
204 (No Content) - Group purged successfully.
- POST /api/groups/(int: id)/restore
Restore the deleted group specified by the given id.
Only the creator of a group can restore it.
Versions:
v1
(latest)Required scopes:
misc.manage_trash
Status codes
200 (OK) - Return the restored group.
PATCH
Change a member’s role of a group. |
|
Update the group specified by the given id. |
- PATCH /api/groups/(int: group_id)/members/(int: user_id)
Change a member’s role of a group.
Will change the role of the member specified by the given user_id of the group specified by the given group_id.
Versions:
v1
(latest)Required scopes:
group.members
Request JSON object
The new member.
name (Required) - String
Status codes
204 (No Content) - Member’s role successfully changed.
409 (Conflict) - When trying to change the creator’s role or a conflict occured while trying to change the role.
- PATCH /api/groups/(int: id)
Update the group specified by the given id.
Versions:
v1
(latest)Required scopes:
group.update
Request JSON object
The new metadata of the group.
description - String
identifier - String
title - String
visibility - String
Status codes
200 (OK) - Return the updated group.
409 (Conflict) - A conflict occured while trying to update the group.
DELETE
Remove a member from a group. |
|
Mark the group specified by the given id as deleted. |
- DELETE /api/groups/(int: group_id)/members/(int: user_id)
Remove a member from a group.
Will remove the member specified by the given user_id from the group specified by the given group_id.
Versions:
v1
(latest)Required scopes:
group.members
Status codes
204 (No Content) - Member successfully removed from group.
409 (Conflict) - When trying to remove the creator.
- DELETE /api/groups/(int: id)
Mark the group specified by the given id as deleted.
Versions:
v1
(latest)Required scopes:
group.delete
Status codes
204 (No Content) - Group successfully marked as deleted.