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
Search and filter for records. |
|
Get the record specified by the given id. |
|
Get collections the record specified by the given id is part of. |
|
Export the record specified by the given id. |
|
Export the extras of a record specified by the given id. |
|
Get files of the record specified by the given id. |
|
Download all files of a record. |
|
Get file revisions of the record specified by the given id. |
|
Get direct record links of the record specified by the given id. |
|
Get record revisions of the record specified by the given id. |
|
Get group roles of the record specified by the given id. |
|
Get user roles of the record specified by the given id. |
|
Get all active and processing uploads of the record specified by the given 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 a file of a record by its name. |
|
GET /api/records/(int:record_id)/files/revisions/(int:revision_id) |
Get a file revision. |
Get a record link. |
|
GET /api/records/(int:record_id)/revisions/(int:revision_id) |
Get a record revision. |
Get an upload of a record. |
|
Get a file of a record directly by its id. |
|
Get the record specified by the given identifier. |
|
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 inkadi.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
orpublic
.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
orand
. (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
andcollection.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
andro-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 inkadi.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 inkadi.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 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, whilein
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
andgroup.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
anduser.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 /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 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 itsstate
and, for uploads that have finished processing, either the newly createdfile
when the processing task finished successfully or anerror
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
Create a new record. |
|
Add the record specified by the given id to a collection. |
|
Purge the deleted record specified by the given id. |
|
Create a new record link. |
|
Restore the deleted record specified by the given id. |
|
Add a group role to the record specified by the given id. |
|
Add a user role to the record specified by the given id. |
|
Upload a new file to the record specified by the given 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
Update the record specified by the given id. |
|
Update the metadata of a file of a record. |
|
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.
- 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 (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
Update the data of a file of a record with a new file upload. |
|
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 followingendpoint
):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
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 a file of a record. |
|
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.