Collections

To get more detailed information about the contents of the requested/returned representation of resources related to collections, see also Collection and Revision. Note that for tags (Tag), only their names are relevant for the API. For possible role values, see also the Miscellaneous endpoints.

GET

GET /api/collections	Search and filter for collections.
GET /api/collections/(int:collection_id)/revisions/(int:revision_id)	Get a collection revision.
GET /api/collections/(int:id)	Get the collection specified by the given id.
GET /api/collections/(int:id)/collections	Get child collections of the collection specified by the given id.
GET /api/collections/(int:id)/export/(export_type)	Export the collection specified by the given id.
GET /api/collections/(int:id)/records	Get records the collection specified by the given id contains.
GET /api/collections/(int:id)/revisions	Get revisions of the collection specified by the given id.
GET /api/collections/(int:id)/roles/groups	Get group roles of the collection specified by the given id.
GET /api/collections/(int:id)/roles/users	Get user roles of the collection specified by the given id.
GET /api/collections/identifier/(identifier:identifier)	Get the collection specified by the given identifier.

GET /api/collections

Search and filter for collections.

Versions: v1 (latest)

Required scopes: collection.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 collections 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 collections with. One of private or public.

explicit_permissions - Flag indicating whether only collections with explicit access permissions should be included, independent of their visibility. (Default: False)

user - User IDs to filter the collections with in relation to their creator. All given users are filtered using an OR operation. (Can be specified more than once.)

tag - Tags to filter the collections with. All given tags are filtered using the operator specified via the tag_operator. (Can be specified more than once.)

tag_operator - The operator to filter the tags with. One of or or and. (Default: or)

Status codes

200 (OK) - Return a paginated array of collections.

GET /api/collections/(int: collection_id)/revisions/(int: revision_id)

Get a collection revision.

Will return the revision specified by the given revision_id of the collection specified by the given collection_id.

Versions: v1 (latest)

Required scopes: collection.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/collections/(int: id)

Get the collection specified by the given id.

Versions: v1 (latest)

Required scopes: collection.read

Status codes

200 (OK) - Return the collection.

GET /api/collections/(int: id)/collections

Get child collections of the collection specified by the given id.

Versions: v1 (latest)

Required scopes: 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)

action - Further actions the current user needs permission to perform in the child collections. (Can be specified more than once.)

Status codes

200 (OK) - Return a paginated array of collections.

GET /api/collections/(int: id)/export/(export_type)

Export the collection specified by the given id.

Currently, json, rdf, qr and ro-crate are supported as export types.

Versions: v1 (latest)

Required scopes: collection.read

Query parameters

filter - An URL-encoded JSON object to specify various filters to adjust the returned export data. See the export_filter parameter in kadi.modules.collections.export.get_export_data() for a more detailed description (in Python syntax). (Default: {})

Status codes

200 (OK) - Return the exported collection data.

GET /api/collections/(int: id)/records

Get records the collection specified by the given id contains.

Versions: v1 (latest)

Required scopes: collection.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)

action - Further actions the current user needs permission to perform in the linked records. (Can be specified more than once.)

children - Flag indicating whether records of child collections should be included in the results. (Default: False)

Status codes

200 (OK) - Return a paginated array of records.

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

Get revisions of the collection specified by the given id.

Versions: v1 (latest)

Required scopes: 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)

Status codes

200 (OK) - Return a paginated array of revisions, sorted by revision timestamp in descending order.

GET /api/collections/(int: id)/roles/groups

Get group roles of the collection specified by the given id.

If a user can manage permissions of this collection, all group roles are returned. However, groups that a user can normally not read include only a limited subset of attributes.

Versions: v1 (latest)

Required scopes: collection.read and 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)

filter - A query to filter the groups by their title or identifier.

Status codes

200 (OK) - Return a paginated array of group roles, sorted by role name and then by group ID in ascending order.

GET /api/collections/(int: id)/roles/users

Get user roles of the collection specified by the given id.

Versions: v1 (latest)

Required scopes: collection.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 users 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 user roles, sorted by role name and then by user ID in ascending order. The creator will always be listed first.

GET /api/collections/identifier/(identifier: identifier)

Get the collection specified by the given identifier.

Versions: v1 (latest)

Required scopes: collection.read

Status codes

200 (OK) - Return the collection.

POST

POST /api/collections	Create a new collection.
POST /api/collections/(int:id)/collections	Add a child collection to the collection specified by the given id.
POST /api/collections/(int:id)/purge	Purge the deleted collection specified by the given id.
POST /api/collections/(int:id)/records	Add a record to the collection specified by the given id.
POST /api/collections/(int:id)/restore	Restore the deleted collection specified by the given id.
POST /api/collections/(int:id)/roles/groups	Add a group role to the collection specified by the given id.
POST /api/collections/(int:id)/roles/users	Add a user role to the collection specified by the given id.

POST /api/collections

Create a new collection.

Versions: v1 (latest)

Required scopes: collection.create

Request JSON object

The metadata of the new collection.

identifier (Required) - String

title (Required) - String

description - String

tags - Array [String]

visibility - String

Status codes

201 (Created) - Return the new collection.

409 (Conflict) - A conflict occured while trying to create the collection.

POST /api/collections/(int: id)/collections

Add a child collection to the collection specified by the given id.

Versions: v1 (latest)

Required scopes: collection.link

Request JSON object

The child collection to add to the collection.

id (Required) - Integer

Status codes

201 (Created) - Child collection successfully added to collection.

409 (Conflict) - When trying to link the collection with itself, the child collection already has a parent or it is already a parent of the collection.

POST /api/collections/(int: id)/purge

Purge the deleted collection specified by the given id.

Will delete the collection permanently. Only the creator of a collection can purge it.

Versions: v1 (latest)

Required scopes: misc.manage_trash

Status codes

204 (No Content) - Collection purged successfully.

POST /api/collections/(int: id)/records

Add a record to the collection specified by the given id.

Versions: v1 (latest)

Required scopes: collection.link

Request JSON object

The record to add to the collection.

id (Required) - Integer

Status codes

201 (Created) - Record successfully added to collection.

409 (Conflict) - The link already exists.

POST /api/collections/(int: id)/restore

Restore the deleted collection specified by the given id.

Only the creator of a collection can restore it.

Versions: v1 (latest)

Required scopes: misc.manage_trash

Status codes

200 (OK) - Return the restored collection.

POST /api/collections/(int: id)/roles/groups

Add a group role to the collection specified by the given id.

Versions: v1 (latest)

Required scopes: collection.permissions

Request JSON object

The group and corresponding role to add.

group (Required) - Object

id (Required) - Integer

role (Required) - Object

name (Required) - String

Status codes

201 (Created) - Group role successfully added to collection.

409 (Conflict) - A role for that group already exists.

POST /api/collections/(int: id)/roles/users

Add a user role to the collection specified by the given id.

Versions: v1 (latest)

Required scopes: collection.permissions

Request JSON object

The user and corresponding role to add.

role (Required) - Object

name (Required) - String

user (Required) - Object

id (Required) - Integer

Status codes

201 (Created) - User role successfully added to collection.

409 (Conflict) - A role for that user already exists.

PATCH

PATCH /api/collections/(int:collection_id)/roles/groups/(int:group_id)	Change a group role of a collection.
PATCH /api/collections/(int:collection_id)/roles/users/(int:user_id)	Change a user role of a collection.
PATCH /api/collections/(int:id)	Update the collection specified by the given id.

PATCH /api/collections/(int: collection_id)/roles/groups/(int: group_id)

Change a group role of a collection.

Will change the role of the group specified by the given group_id of the collection specified by the given collection_id.

Versions: v1 (latest)

Required scopes: collection.permissions

Request JSON object

The new group role.

name (Required) - String

Status codes

204 (No Content) - Group role successfully changed.

409 (Conflict) - A conflict occured while trying to change the role.

PATCH /api/collections/(int: collection_id)/roles/users/(int: user_id)

Change a user role of a collection.

Will change the role of the user specified by the given user_id of the collection specified by the given collection_id.

Versions: v1 (latest)

Required scopes: collection.permissions

Request JSON object

The new user role.

name (Required) - String

Status codes

204 (No Content) - User 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/collections/(int: id)

Update the collection specified by the given id.

Versions: v1 (latest)

Required scopes: collection.update

Request JSON object

The new metadata of the collection.

description - String

identifier - String

tags - Array [String]

title - String

visibility - String

Status codes

200 (OK) - Return the updated collection.

409 (Conflict) - A conflict occured while trying to update the collection.

DELETE

DELETE /api/collections/(int:collection_id)/collections/(int:child_id)	Remove a child collection from a collection.
DELETE /api/collections/(int:collection_id)/records/(int:record_id)	Remove a record from a collection.
DELETE /api/collections/(int:collection_id)/roles/groups/(int:group_id)	Remove a group role from a collection.
DELETE /api/collections/(int:collection_id)/roles/users/(int:user_id)	Remove a user role from a collection.
DELETE /api/collections/(int:id)	Mark the collection specified by the given id as deleted.

DELETE /api/collections/(int: collection_id)/collections/(int: child_id)

Remove a child collection from a collection.

Will remove the child collection specified by the given child_id from the collection specified by the given collection_id.

Versions: v1 (latest)

Required scopes: collection.link

Status codes

204 (No Content) - Child successfully removed from collection.

DELETE /api/collections/(int: collection_id)/records/(int: record_id)

Remove a record from a collection.

Will remove the record specified by the given record_id from the collection specified by the given collection_id.

Versions: v1 (latest)

Required scopes: collection.link

Status codes

204 (No Content) - Record successfully removed from collection.

DELETE /api/collections/(int: collection_id)/roles/groups/(int: group_id)

Remove a group role from a collection.

Will remove the role of the group specified by the given group_id from the collection specified by the given collection_id.

Versions: v1 (latest)

Required scopes: collection.permissions

Status codes

204 (No Content) - Group role successfully removed from collection.

DELETE /api/collections/(int: collection_id)/roles/users/(int: user_id)

Remove a user role from a collection.

Will remove the role of the user specified by the given user_id from the collection specified by the given collection_id.

Versions: v1 (latest)

Required scopes: collection.permissions

Status codes

204 (No Content) - User role successfully removed from collection.

409 (Conflict) - When trying to remove the creator’s role.

DELETE /api/collections/(int: id)

Mark the collection specified by the given id as deleted.

Versions: v1 (latest)

Required scopes: collection.delete

Status codes

204 (No Content) - Collection successfully marked as deleted.