Records

To get more detailed information about the contents of the requested/returned representation of resources related to records, see also Record, especially Record.extras, RecordLink, File, Upload and Revision. Note that for tags (Tag) and licenses (License), only their names are relevant for the API. For possible license and role values, see also the Miscellaneous endpoints.

GET

GET /api/records

Search and filter for records.

GET /api/records/(int:id)

Get the record specified by the given id.

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

Get collections the record specified by the given id is part of.

GET /api/records/(int:id)/export/(export_type)

Export the record specified by the given id.

GET /api/records/(int:id)/extras/export/(export_type)

Export the extras of a record specified by the given id.

GET /api/records/(int:id)/files

Get files of the record specified by the given id.

GET /api/records/(int:id)/files/download

Download all files of a record.

GET /api/records/(int:id)/files/revisions

Get file revisions of the record specified by the given id.

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

Get direct record links of the record specified by the given id.

GET /api/records/(int:id)/revisions

Get record revisions of the record specified by the given id.

GET /api/records/(int:id)/roles/groups

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

GET /api/records/(int:id)/roles/users

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

GET /api/records/(int:id)/uploads

Get all active and processing uploads of the record specified by the given id.

GET /api/records/(int:record_id)/files/(uuid:file_id)

Get a file of a record.

GET /api/records/(int:record_id)/files/(uuid:file_id)/download

Download a file of a record.

GET /api/records/(int:record_id)/files/name/(path:filename)

Get a file of a record by its name.

GET /api/records/(int:record_id)/files/revisions/(int:revision_id)

Get a file revision.

GET /api/records/(int:record_id)/records/(int:link_id)

Get a record link.

GET /api/records/(int:record_id)/revisions/(int:revision_id)

Get a record revision.

GET /api/records/(int:record_id)/uploads/(uuid:upload_id)

Get an upload of a record.

GET /api/records/files/(uuid:id)

Get a file of a record directly by its id.

GET /api/records/identifier/(identifier:identifier)

Get the record specified by the given identifier.

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

Get a record link directly by its id.

GET /api/records

Search and filter for records.

Versions: v1 (latest)

Required scopes: record.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 records with. Supports exact matches when surrounded by double quotes.

  • extras - An URL-encoded array of JSON objects to specify the search within the extra metadata of a record. See the extras parameter in kadi.modules.records.utils.search_records() for a more detailed description (in Python syntax). (Default: [])

  • 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 records with. One of private or public.

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

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

  • collection - Collection IDs the searched records need to belong to. All given collections are filtered using an OR operation. (Can be specified more than once.)

  • child_collections - Flag indicating whether the children of the filtered collections should be included. (Default: False)

  • type - Record types to filter the records with. All given types are filtered using an OR operation. (Can be specified more than once.)

  • tag - Tags to filter the records 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)

  • mimetype - MIME types to filter the records with based on their files. All given MIME types are filtered using an OR operation. (Can be specified more than once.)

Status codes

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

GET /api/records/(int: id)

Get the record specified by the given id.

Versions: v1 (latest)

Required scopes: record.read

Status codes

  • 200 (OK) - Return the record.

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

Get collections the record specified by the given id is part of.

Versions: v1 (latest)

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

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

Status codes

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

GET /api/records/(int: id)/export/(export_type)

Export the record specified by the given id.

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

Versions: v1 (latest)

Required scopes: record.read

Query parameters

Status codes

  • 200 (OK) - Return the exported record data.

GET /api/records/(int: id)/extras/export/(export_type)

Export the extras of a record specified by the given id.

Currently, only json is supported as export type.

Versions: v1 (latest)

Required scopes: record.read

Query parameters

Status codes

  • 200 (OK) - Return the exported extras data.

GET /api/records/(int: id)/files

Get files of the record specified by the given id.

Versions: v1 (latest)

Required scopes: 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 files by name.

  • sort - The order of the returned files. One of last_modified, -last_modified, created_at, -created_at, name, -name, size or -size. (Default: -last_modified)

Status codes

  • 200 (OK) - Return a paginated array of files.

GET /api/records/(int: id)/files/download

Download all files of a record.

Will return all files of the record specified by the given id as a ZIP archive as attachment.

Versions: v1 (latest)

Required scopes: record.read

Status codes

  • 200 (OK) - Return the files as attachment.

GET /api/records/(int: id)/files/revisions

Get file revisions of the record specified by the given id.

Versions: v1 (latest)

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

Status codes

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

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

Get direct record links of the record specified by the given id.

Versions: v1 (latest)

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

  • direction - The direction of the record links. out will return outgoing links from the current record, while in will return incoming links to the current record. (Default: out)

  • filter - A query to filter the record links by their link name or the linked records by their title or identifier.

  • sort - The order of the returned record links. One of last_modified, -last_modified, created_at, -created_at, name or -name. (Default: -last_modified)

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

Status codes

  • 200 (OK) - Return a paginated array of record links.

GET /api/records/(int: id)/revisions

Get record revisions of the record specified by the given id.

Versions: v1 (latest)

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

Status codes

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

GET /api/records/(int: id)/roles/groups

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

If a user can manage permissions of this record, 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: record.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/records/(int: id)/roles/users

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

Versions: v1 (latest)

Required scopes: record.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/records/(int: id)/uploads

Get all active and processing uploads of the record specified by the given id.

Only uploads owned by the current user will be returned. For chunked uploads, the required size for uploading chunks (except for the last chunk) is returned as the _meta.chunk_size property of each upload.

Versions: v1 (latest)

Required scopes: record.update

Status codes

  • 200 (OK) - Return the uploads, sorted by creation date in ascending order.

GET /api/records/(int: record_id)/files/(uuid: file_id)

Get a file of a record.

Will return the file specified by the given file_id of the record specified by the given record_id.

Versions: v1 (latest)

Required scopes: record.read

Status codes

  • 200 (OK) - Return the file.

GET /api/records/(int: record_id)/files/(uuid: file_id)/download

Download a file of a record.

Will return the file specified by the given file_id of the record specified by the given record_id as attachment.

Versions: v1 (latest)

Required scopes: record.read

Status codes

  • 200 (OK) - Return the file as attachment.

GET /api/records/(int: record_id)/files/name/(path: filename)

Get a file of a record by its name.

Will return the file specified by the given filename of the record specified by the given record_id.

Versions: v1 (latest)

Required scopes: record.read

Status codes

  • 200 (OK) - Return the file.

GET /api/records/(int: record_id)/files/revisions/(int: revision_id)

Get a file revision.

Will return the file revision specified by the given revision_id of the record specified by the given record_id.

Versions: v1 (latest)

Required scopes: record.read

Query parameters

  • revision - The ID of a revision to compare with instead of the previous one.

Status codes

  • 200 (OK) - Return the file revision.

Get a record link.

Will return the direct (outgoing) record link specified by the given link_id from the record specified by the given record_id.

Versions: v1 (latest)

Required scopes: record.read

Status codes

  • 200 (OK) - Return the record link.

GET /api/records/(int: record_id)/revisions/(int: revision_id)

Get a record revision.

Will return the record revision specified by the given revision_id of the record specified by the given record_id.

Versions: v1 (latest)

Required scopes: record.read

Query parameters

  • revision - The ID of a revision to compare with instead of the previous one.

Status codes

  • 200 (OK) - Return the record revision.

GET /api/records/(int: record_id)/uploads/(uuid: upload_id)

Get an upload of a record.

Will return the upload specified by the given upload_id of the record specified by the given record_id. Only uploads owned by the current user can be retrieved.

For chunked uploads, this endpoint can also be used to query the state of the upload processing task after the upload has been finished. The task will be included as the _meta.task property, and includes its state and, for uploads that have finished processing, either the newly created file when the processing task finished successfully or an error message.

Versions: v1 (latest)

Required scopes: record.update

Status codes

  • 200 (OK) - Return the upload.

GET /api/records/files/(uuid: id)

Get a file of a record directly by its id.

Versions: v1 (latest)

Required scopes: record.read

Status codes

  • 200 (OK) - Return the file.

GET /api/records/identifier/(identifier: identifier)

Get the record specified by the given identifier.

Versions: v1 (latest)

Required scopes: record.read

Status codes

  • 200 (OK) - Return the record.

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

Get a record link directly by its id.

Versions: v1 (latest)

Required scopes: record.read

Status codes

  • 200 (OK) - Return the record link.

POST

POST /api/records

Create a new record.

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

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

POST /api/records/(int:id)/purge

Purge the deleted record specified by the given id.

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

Create a new record link.

POST /api/records/(int:id)/restore

Restore the deleted record specified by the given id.

POST /api/records/(int:id)/roles/groups

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

POST /api/records/(int:id)/roles/users

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

POST /api/records/(int:id)/uploads

Upload a new file to the record specified by the given id.

POST /api/records/(int:record_id)/uploads/(uuid:upload_id)

Finish a chunked upload.

POST /api/records

Create a new record.

Versions: v1 (latest)

Required scopes: record.create

Request JSON object

The metadata of the new record.

  • identifier (Required) - String

  • title (Required) - String

  • description - String

  • extras - Array [Object]

  • license - String

  • tags - Array [String]

  • type - String

  • visibility - String

Status codes

  • 201 (Created) - Return the new record.

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

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

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

Versions: v1 (latest)

Required scopes: record.link

Request JSON object

The collection to add the record to.

  • id (Required) - Integer

Status codes

  • 201 (Created) - Record successfully added to collection.

  • 409 (Conflict) - The link already exists.

POST /api/records/(int: id)/purge

Purge the deleted record specified by the given id.

Will delete the record permanently, including all of its files. The actual deletion process will happen in a background task. Only the creator of a record can purge it.

Versions: v1 (latest)

Required scopes: misc.manage_trash

Status codes

  • 202 (Accepted) - The purge record task was started successfully.

  • 503 (Service Unavailable) - The purge record task could not be started. The record will remain deleted in this case.

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

Create a new record link.

Will create a new direct (outgoing) record link from the record specified by the given id.

Versions: v1 (latest)

Required scopes: record.link

Request JSON object

The metadata of the new record link.

  • name (Required) - String

  • record_to (Required) - Object

    • id (Required) - Integer

  • term - String (Default: null)

Status codes

  • 201 (Created) - Return the new record link.

  • 409 (Conflict) - When trying to link the record with itself or the link already exists.

POST /api/records/(int: id)/restore

Restore the deleted record specified by the given id.

Only the creator of a record can restore it.

Versions: v1 (latest)

Required scopes: misc.manage_trash

Status codes

  • 200 (OK) - Return the restored record.

POST /api/records/(int: id)/roles/groups

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

Versions: v1 (latest)

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

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

POST /api/records/(int: id)/roles/users

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

Versions: v1 (latest)

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

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

POST /api/records/(int: id)/uploads

Upload a new file to the record specified by the given id.

This endpoint will initiate a new upload with the given metadata. The corresponding file data has to be uploaded separately, either directly or via multiple file chunks, depending on the size of the upload. Which method to choose will be indicated by the upload_type property of the returned upload, being either one of "direct" or "chunked".

For both upload types, the following endpoint is used to upload the file data, which is also returned as the _actions.upload_data property of the returned upload. For chunked uploads, the required size for uploading chunks (except for the last chunk) is returned as the _meta.chunk_size property.

Versions: v1 (latest)

Required scopes: record.update

Request JSON object

The metadata of the new upload.

  • name (Required) - String

  • size (Required) - Integer

  • description - String

  • mimetype - String

Status codes

  • 201 (Created) - Return the new upload.

  • 409 (Conflict) - A file with the name of the upload already exists. The file will be returned as part of the error response as the file property.

  • 413 (Request Entity Too Large) - The user’s upload quota was exceeded.

POST /api/records/(int: record_id)/uploads/(uuid: upload_id)

Finish a chunked upload.

Will finish the chunked upload specified by the given upload_id of the record specified by the given record_id. Only uploads owned by the current user can be finished.

The upload will be finished by starting an upload processing task to finalize it. The status of this task can be queried using the following endpoint, which is also returned as the _links.self property of the returned upload.

Versions: v1 (latest)

Required scopes: record.update

Status codes

  • 202 (Accepted) - The upload processing task was started successfully. Also return the updated upload.

  • 503 (Service Unavailable) - The upload processing task could not be started. The upload will remain active in this case.

PATCH

PATCH /api/records/(int:id)

Update the record specified by the given id.

PATCH /api/records/(int:record_id)/files/(uuid:file_id)

Update the metadata of a file of a record.

PATCH /api/records/(int:record_id)/records/(int:link_id)

Update a record link.

PATCH /api/records/(int:record_id)/roles/groups/(int:group_id)

Change a group role of a record.

PATCH /api/records/(int:record_id)/roles/users/(int:user_id)

Change a user role of a record.

PATCH /api/records/(int: id)

Update the record specified by the given id.

Versions: v1 (latest)

Required scopes: record.update

Request JSON object

The new metadata of the record.

  • description - String

  • extras - Array [Object]

  • identifier - String

  • license - String

  • tags - Array [String]

  • title - String

  • type - String

  • visibility - String

Status codes

  • 200 (OK) - Return the updated record.

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

PATCH /api/records/(int: record_id)/files/(uuid: file_id)

Update the metadata of a file of a record.

Will update the file specified by the given file_id of the record specified by the given record_id.

Versions: v1 (latest)

Required scopes: record.update

Request JSON object

The new metadata of the file.

  • description - String

  • mimetype - String

  • name - String

Status codes

  • 200 (OK) - Return the updated file.

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

Update a record link.

Will update the direct (outgoing) record link specified by the given link_id from the record specified by the given record_id.

Versions: v1 (latest)

Required scopes: record.link

Request JSON object

The metadata of the new record link.

  • name - String

  • term - String (Default: null)

Status codes

  • 200 (OK) - Return the updated record link.

  • 409 (Conflict) - The link already exists.

PATCH /api/records/(int: record_id)/roles/groups/(int: group_id)

Change a group role of a record.

Will change the role of the group specified by the given group_id of the record specified by the given record_id.

Versions: v1 (latest)

Required scopes: record.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/records/(int: record_id)/roles/users/(int: user_id)

Change a user role of a record.

Will change the role of the user specified by the given user_id of the record specified by the given record_id.

Versions: v1 (latest)

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

PUT

PUT /api/records/(int:record_id)/files/(uuid:file_id)

Update the data of a file of a record with a new file upload.

PUT /api/records/(int:record_id)/uploads/(uuid:upload_id)

Upload the data of an upload.

PUT /api/records/(int: record_id)/files/(uuid: file_id)

Update the data of a file of a record with a new file upload.

This endpoint will initiate a new upload with the given metadata in the record specified by the given record_id, replacing the data of the file specified by the given file_id once the upload is finished. The corresponding file data has to be uploaded separately in the same way as for new uploads, see the following endpoint.

Versions: v1 (latest)

Required scopes: record.update

Request JSON object

The metadata of the new upload.

  • size (Required) - Integer

  • description - String

  • mimetype - String

Status codes

  • 201 (Created) - Return the new upload.

  • 413 (Request Entity Too Large) - The user’s upload quota was exceeded.

PUT /api/records/(int: record_id)/uploads/(uuid: upload_id)

Upload the data of an upload.

This endpoint is used to upload file data to the upload specified by the given upload_id of the record specified by the given record_id. Only uploads owned by the current user can be uploaded to.

The actual data has to be uploaded as a binary stream of a file’s content, ideally using the generic application/octet-stream content type. Which contents to actually upload depends on the upload type (see also the following endpoint):

  • For direct uploads, the whole file content is uploaded. Once the data is uploaded successfully, the upload process is finished.

  • For chunked uploads, the file content is uploaded in multiple chunks. Once all chunks have been uploaded successfully, the upload has to be finished using the following endpoint, which is also returned as the _actions.finish property of the returned upload.

Versions: v1 (latest)

Required scopes: record.update

Custom request headers

  • Kadi-MD5-Checksum - String

    An MD5 hash of the content of the uploaded data. If given, it will be used to verify the integrity of the data once uploaded.

  • Kadi-Chunk-Index (Required) - Integer

    The index of an uploaded chunk starting at 0. Only relevant for chunked uploads.

  • Kadi-Chunk-Size (Required) - Integer

    The size of an uploaded chunk in bytes. Only relevant for chunked uploads.

Status codes

  • 200 (OK) - Return the updated upload. Only relevant for chunked uploads

  • 201 (Created) - Return the new file. Only relevant for direct uploads.

  • 409 (Conflict) - A conflict occured while completing the upload. Only relevant for direct uploads.

DELETE

DELETE /api/records/(int:id)

Mark the record specified by the given id as deleted.

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

Remove a record from a collection.

DELETE /api/records/(int:record_id)/files/(uuid:file_id)

Delete a file of a record.

DELETE /api/records/(int:record_id)/records/(int:link_id)

Remove a record link.

DELETE /api/records/(int:record_id)/roles/groups/(int:group_id)

Remove a group role from a record.

DELETE /api/records/(int:record_id)/roles/users/(int:user_id)

Remove a user role from a record.

DELETE /api/records/(int:record_id)/uploads/(uuid:upload_id)

Delete an upload of a record.

DELETE /api/records/(int: id)

Mark the record specified by the given id as deleted.

Versions: v1 (latest)

Required scopes: record.delete

Status codes

  • 204 (No Content) - Record successfully marked as deleted.

DELETE /api/records/(int: record_id)/collections/(int: collection_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: record.link

Status codes

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

DELETE /api/records/(int: record_id)/files/(uuid: file_id)

Delete a file of a record.

Will delete the file specified by the given file_id of the record specified by the given record_id.

Versions: v1 (latest)

Required scopes: record.update

Status codes

  • 204 (No Content) - File deleted successfully.

Remove a record link.

Will remove the direct (outgoing) record link specified by the given link_id from the record specified by the given record_id.

Versions: v1 (latest)

Required scopes: record.link

Status codes

  • 204 (No Content) - Record link removed successfully.

DELETE /api/records/(int: record_id)/roles/groups/(int: group_id)

Remove a group role from a record.

Will remove the role of the group specified by the given group_id from the record specified by the given record_id.

Versions: v1 (latest)

Required scopes: record.permissions

Status codes

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

DELETE /api/records/(int: record_id)/roles/users/(int: user_id)

Remove a user role from a record.

Will remove the role of the user specified by the given user_id from the record specified by the given record_id.

Versions: v1 (latest)

Required scopes: record.permissions

Status codes

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

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

DELETE /api/records/(int: record_id)/uploads/(uuid: upload_id)

Delete an upload of a record.

Will delete the upload specified by the given upload_id of the record specified by the given record_id. Only uploads owned by the current user can be deleted.

Versions: v1 (latest)

Required scopes: record.update

Status codes

  • 204 (No Content) - Upload deleted successfully.