Records

To get more detailed information about some the contents of the requested/returned representation of resources related to records, see also Record (including 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 the 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 the 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 the file revisions of the record specified by the given id.
GET /api/records/(int:id)/records	Get the direct record links of the record specified by the given id.
GET /api/records/(int:id)/revisions	Get the record revisions of the record specified by the given id.
GET /api/records/(int:id)/roles/groups	Get the group roles of the record specified by the given id.
GET /api/records/(int:id)/roles/users	Get the user roles of the record specified by the given id.
GET /api/records/(int:id)/uploads	Get all chunked 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 the status of a chunked upload.
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.

extras - An URL-encoded array of JSON objects to specify the search within the extra metadata of a record. See 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.

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

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 list of collections, sorted by last modification date in descending order.

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

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

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

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

Status codes

200 (OK) - Return the exported extras data.

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

Get the 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, name, -name, size or -size. (Default: -last_modified)

Status codes

200 (OK) - Return a paginated list 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 the 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 list of file revisions, sorted by revision timestamp in descending order.

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

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

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 list of record links, sorted by creation date in descending order.

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

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

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

Get the 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 list of group roles, sorted by role name and then by group ID in ascending order.

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

Get the 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 list 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 chunked uploads of the record specified by the given id.

Only uploads created by the current user will be returned.

Versions: v1 (latest)

Required scopes: record.update

Status codes

200 (OK) - Return the uploads, sorted by creation date in ascending order. Additionally, the required size for uploading file chunks is returned as the _meta.chunk_size property.

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 /api/records/(int: record_id)/records/(int: link_id)

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 the status of a chunked upload.

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

Versions: v1 (latest)

Required scopes: record.update

Status codes

200 (OK) - Return the upload and additional metadata in the _meta property. This property will either contain the new file, the progress of the upload processing task or an error message, depending on the state of 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)/files	Directly upload a file to the record specified by the given id.
POST /api/records/(int:id)/purge	Purge a 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	Initiate a new chunked upload in 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 - Object

license - String

tags - [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)/files

Directly upload a file to the record specified by the given id.

This endpoint can be used to directly upload files smaller than the configured UPLOAD_CHUNKED_BOUNDARY (which defaults to 50 MB), but it does not support resumable uploads. Note that compared to chunked uploads, this endpoint can also be used to directly update the data of existing files.

Versions: v1 (latest)

Required scopes: record.update

Request form data (Encoding: multipart/form-data)

The actual metadata and data of the file to upload. Since the data is streamed, the order of the required fields must match the order in the description. Optional fields should be at the beginning, but can be in any order.

storage_type - String (Default: local)

replace_file - Boolean (Default: false)

mimetype - String

checksum - String

description - String

name (Required) - String

size (Required) - Integer

blob (Required) - File

Status codes

201 (Created) - Return the new file.

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

413 (Request Entity Too Large) - An upload quota was exceeded or the upload is too large to be uploaded via this endpoint.

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

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

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

Initiate a new chunked upload in the record specified by the given id.

Once the new upload is initiated, the actual file chunks can be uploaded by sending one or more PUT requests to the endpoint specified in the _actions.upload_chunk property of the upload.

This endpoint can be used to upload files larger than the configured UPLOAD_CHUNKED_BOUNDARY (which defaults to 50 MB) or when resumable uploads are required.

Versions: v1 (latest)

Required scopes: record.update

Request JSON object

The metadata of the new upload.

name (Required) - String

size (Required) - Integer

checksum - String

description - String

mimetype - String

storage - Object

storage_type - String (Default: "local")

Status codes

201 (Created) - Return the new upload. Additionally, the required size for uploading file chunks is returned as the _meta.chunk_size property.

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) - An upload quota was exceeded.

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

Finish a chunked upload.

Will finish the upload specified by the given upload_id in the record specified by the given record_id. A background task will be started, which will process and finalize the upload. The status of this task can be queried using the endpoint specified in the _links.status property of the upload. Only uploads owned by the current user can be finished.

Versions: v1 (latest)

Required scopes: record.update

Status codes

202 (Accepted) - The upload processing task was started successfully.

413 (Request Entity Too Large) - An upload quota was exceeded.

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 - Object

identifier - String

license - String

tags - [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.

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

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

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)	Change the data of a file of a record via a new chunked upload.
PUT /api/records/(int:record_id)/uploads/(uuid:upload_id)	Upload a chunk of a chunked upload.

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

Change the data of a file of a record via a new chunked upload.

Will initiate a new chunked upload in the record specified by the given record_id replacing the data of the file specified by the given file_id. Once the new upload is initiated, the actual file chunks can be uploaded by sending one or more PUT requests to the endpoint specified in the _actions.upload_chunk property of the upload.

Versions: v1 (latest)

Required scopes: record.update

Request JSON object

The metadata of the new upload.

size (Required) - Integer

checksum - String

description - String

mimetype - String

storage - Object

storage_type - String (Default: "local")

Status codes

201 (Created) - Return the new upload. Additionally, the required size for uploading file chunks is returned as the _meta.chunk_size property.

413 (Request Entity Too Large) - An upload quota was exceeded.

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

Upload a chunk of a chunked upload.

Will upload a chunk of the upload specified by the given upload_id of the record specified by the given record_id. Once all chunks have been uploaded, the upload can be finished by sending a POST request to the endpoint specified in the _actions.finish_upload property of the upload. Only uploads owned by the current user can be updated.

Versions: v1 (latest)

Required scopes: record.update

Request form data (Encoding: multipart/form-data)

The actual data and metadata of the chunk to upload. Indices start at 0 for each file and need to be incremented in order of the file chunks.

checksum - String

index (Required) - Integer

size (Required) - Integer

blob (Required) - File

Status codes

200 (OK) - Return the updated upload.

413 (Request Entity Too Large) - An upload quota was exceeded.

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.

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

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.