Groups

To get more detailed information about some 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 all collections shared with the group with the given id.
GET /api/groups/(int:id)/members	Get the members of the group specified by the given id.
GET /api/groups/(int:id)/records	Get all records shared with the group with the given id.
GET /api/groups/(int:id)/revisions	Get the revisions of the group specified by the given id.
GET /api/groups/(int:id)/templates	Get all records 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.

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.

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.)

member_only - Flag indicating whether groups without membership should be excluded in the results. (Default: False)

Status codes

200 (OK) - Return a paginated list 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 all 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.

GET /api/groups/(int: id)/members

Get the 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 list 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 all 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.

GET /api/groups/(int: id)/revisions

Get the 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 list of revisions, sorted by revision timestamp in descending order.

GET /api/groups/(int: id)/templates

Get all records 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.

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 a 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 a 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.