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

GET /api/groups	Search and filter for groups.
GET /api/groups/(int:group_id)/revisions/(int:revision_id)	Get a group revision.
GET /api/groups/(int:id)	Get the group specified by the given id.
GET /api/groups/(int:id)/collections	Get collections shared with the group with the given id.
GET /api/groups/(int:id)/members	Get members of the group specified by the given id.
GET /api/groups/(int:id)/records	Get records shared with the group with the given id.
GET /api/groups/(int:id)/revisions	Get revisions of the group specified by the given id.
GET /api/groups/(int:id)/templates	Get templates shared with the group with the given id.
GET /api/groups/identifier/(identifier:identifier)	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 or public.

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 and collection.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 and user.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 and record.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 and template.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

POST /api/groups	Create a new group.
POST /api/groups/(int:id)/members	Add a member to the group specified by the given id.
POST /api/groups/(int:id)/purge	Purge the deleted group specified by the given id.
POST /api/groups/(int:id)/restore	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

PATCH /api/groups/(int:group_id)/members/(int:user_id)	Change a member’s role of a group.
PATCH /api/groups/(int:id)	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

DELETE /api/groups/(int:group_id)/members/(int:user_id)	Remove a member from a group.
DELETE /api/groups/(int:id)	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.