v1 (stable)

This section documents the endpoints of the stable version v1 of the HTTP API of Kadi4Mat. This version also marks the current default API version, whenever no explicit version is requested.

Records

The following subsections describe all endpoints related to records, grouped by HTTP method. 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 and Upload. 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/v1/records	Search and filter for records.
GET /api/v1/records/files/{id}	Get a file of a record directly by its ID.
GET /api/v1/records/identifier/{identifier}	Get the record specified by the given identifier.
GET /api/v1/records/records/{id}	Get a record link directly by its ID.
GET /api/v1/records/{id}	Get the record specified by the given ID.
GET /api/v1/records/{id}/collections	Get collections the record specified by the given ID is part of.
GET /api/v1/records/{id}/export/{export_type}	Export the record specified by the given ID using the given export type.
GET /api/v1/records/{id}/extras/export/{export_type}	Export the extras of a record specified by the given ID.
GET /api/v1/records/{id}/files	Get files of the record specified by the given ID.
GET /api/v1/records/{id}/files/download	Download all files of a record.
GET /api/v1/records/{id}/files/revisions	Get file revisions of the record specified by the given ID.
GET /api/v1/records/{id}/records	Get the record links of the record specified by the given ID.
GET /api/v1/records/{id}/revisions	Get record revisions of the record specified by the given ID.
GET /api/v1/records/{id}/roles/groups	Get group roles of the record specified by the given ID.
GET /api/v1/records/{id}/roles/users	Get user roles of the record specified by the given ID.
GET /api/v1/records/{id}/uploads	Get all active and processing uploads of the record specified by the given ID.
GET /api/v1/records/{record_id}/files/name/{filename}	Get a file of a record by its name.
GET /api/v1/records/{record_id}/files/revisions/{revision_id}	Get a file revision.
GET /api/v1/records/{record_id}/files/{file_id}	Get a file of a record.
GET /api/v1/records/{record_id}/files/{file_id}/download	Download a file of a record.
GET /api/v1/records/{record_id}/records/{link_id}	Get a record link.
GET /api/v1/records/{record_id}/revisions/{revision_id}	Get a record revision.
GET /api/v1/records/{record_id}/uploads/{upload_id}	Get an upload of a record.

GET /api/v1/records

Search and filter for records.

Required scopes

record.read

Query parameters

page: integer (default: 1)

The current result page.

Minimum: 1

Maximum: 100

per_page: integer (default: 10)

Number of results per page.

Minimum: 1

Maximum: 100

query: string

A query to search the records with. Supports exact matches when surrounded by double quotes.

extras: string (default: [])

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

sort: string (default: _score)

The order of the search results. Falls back to -last_modified if no search query is given.

One of: _score, last_modified, -last_modified, created_at, -created_at, title, -title, identifier, -identifier.

visibility: string

A visibility value to filter the records with.

One of: private, public.

explicit_permissions: boolean (default: False)

Flag indicating whether only records with explicit access permissions should be included, independent of their visibility.

user: array<integer>

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: array<integer>

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: boolean (default: False)

Flag indicating whether the children of the filtered collections should be included.

type: array<string>

Record types to filter the records with. All given types are filtered using an OR operation.

Can be specified more than once.

tag: array<string>

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: string (default: or)

The operator to filter the tags with.

One of: or, and.

mimetype: array<string>

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.

instance: string

The name of an external Kadi4Mat instance to search instead.

Responses

200 - OK

Return a paginated array of records.

400 - Bad Request

The specified external Kadi4Mat instance is invalid or has not yet been connected to the current user's account.

502 - Bad Gateway

The request to the specified external Kadi4Mat instance failed.

GET /api/v1/records/files/{id}

Get a file of a record directly by its ID.

Required scopes

record.read

Path parameters

id: string

Responses

200 - OK

Return the file.

GET /api/v1/records/identifier/{identifier}

Get the record specified by the given identifier.

Required scopes

record.read

Path parameters

identifier: string

Responses

200 - OK

Return the record.

GET /api/v1/records/records/{id}

Get a record link directly by its ID.

Required scopes

record.read

Path parameters

id: integer

Responses

200 - OK

Return the record link.

GET /api/v1/records/{id}

Get the record specified by the given ID.

Required scopes

record.read

Path parameters

id: integer

Responses

200 - OK

Return the record.

GET /api/v1/records/{id}/collections

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

Required scopes

record.read
collection.read

Path parameters

id: integer

Query parameters

page: integer (default: 1)

The current result page.

Minimum: 1

per_page: integer (default: 10)

Number of results per page.

Minimum: 1

Maximum: 100

filter: string

A query to filter the collections by their title or identifier.

sort: string (default: -last_modified)

The order of the returned collections.

One of: last_modified, -last_modified, created_at, -created_at, title, -title, identifier, -identifier.

action: array<string>

Further actions the current user needs permission to perform in the linked collections.

Can be specified more than once.

Responses

200 - OK

Return a paginated array of collections.

GET /api/v1/records/{id}/export/{export_type}

Export the record specified by the given ID using the given export type.

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

Required scopes

record.read

Path parameters

id: integer

export_type: string

Query parameters

filter: string (default: {})

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

Responses

200 - OK

Return the exported record data.

GET /api/v1/records/{id}/extras/export/{export_type}

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

Currently, only json is supported as export type.

Required scopes

record.read

Path parameters

id: integer

export_type: string

Query parameters

filter: string (default: {})

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

Responses

200 - OK

Return the exported extras data.

GET /api/v1/records/{id}/files

Get files of the record specified by the given ID.

Required scopes

record.read

Path parameters

id: integer

Query parameters

page: integer (default: 1)

The current result page.

Minimum: 1

per_page: integer (default: 10)

Number of results per page.

Minimum: 1

Maximum: 100

filter: string

A query to filter the files by name.

sort: string (default: -last_modified)

The order of the returned files.

One of: last_modified, -last_modified, created_at, -created_at, name, -name, size, -size.

Responses

200 - OK

Return a paginated array of files.

GET /api/v1/records/{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.

Required scopes

record.read

Path parameters

id: integer

Responses

200 - OK

Return the files as attachment.

GET /api/v1/records/{id}/files/revisions

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

Required scopes

record.read

Path parameters

id: integer

Query parameters

page: integer (default: 1)

The current result page.

Minimum: 1

per_page: integer (default: 10)

Number of results per page.

Minimum: 1

Maximum: 100

Responses

200 - OK

Return a paginated array of file revisions, sorted by revision timestamp in descending order.

GET /api/v1/records/{id}/records

Get the record links of the record specified by the given ID.

Required scopes

record.read

Path parameters

id: integer

Query parameters

page: integer (default: 1)

The current result page.

Minimum: 1

per_page: integer (default: 10)

Number of results per page.

Minimum: 1

Maximum: 100

direction: string (default: out)

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. Depending on direction, linked records will be included as record_to or record_from respectively.

filter: string

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

sort: string (default: -last_modified)

The order of the returned record links.

One of: last_modified, -last_modified, created_at, -created_at, name, -name.

action: array<string>

Further actions the current user needs permission to perform in the linked records.

Can be specified more than once.

Responses

200 - OK

Return a paginated array of record links.

GET /api/v1/records/{id}/revisions

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

Required scopes

record.read

Path parameters

id: integer

Query parameters

page: integer (default: 1)

The current result page.

Minimum: 1

per_page: integer (default: 10)

Number of results per page.

Minimum: 1

Maximum: 100

Responses

200 - OK

Return a paginated array of record revisions, sorted by revision timestamp in descending order.

GET /api/v1/records/{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 (id, title, identifier and visibility).

Required scopes

record.read
group.read

Path parameters

id: integer

Query parameters

page: integer (default: 1)

The current result page.

Minimum: 1

per_page: integer (default: 10)

Number of results per page.

Minimum: 1

Maximum: 100

filter: string

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

Responses

200 - OK

Return a paginated array of group roles, sorted by role name and then by group ID in ascending order.

GET /api/v1/records/{id}/roles/users

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

Required scopes

record.read
user.read

Path parameters

id: integer

Query parameters

page: integer (default: 1)

The current result page.

Minimum: 1

per_page: integer (default: 10)

Number of results per page.

Minimum: 1

Maximum: 100

filter: string

A query to filter the users by their username or display name.

exclude: array<integer>

User IDs to exclude.

Can be specified more than once.

Responses

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/v1/records/{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. The required size for uploading chunks (except for the final chunk for chunked uploads) is returned as the _meta.chunk_size property of each upload. For direct uploads, the chunk size is always equal to the total upload size.

Required scopes

record.update

Path parameters

id: integer

Responses

200 - OK

Return the uploads, sorted by creation date in ascending order.

GET /api/v1/records/{record_id}/files/name/{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.

Required scopes

record.read

Path parameters

record_id: integer

filename: string

Responses

200 - OK

Return the file.

GET /api/v1/records/{record_id}/files/revisions/{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.

Required scopes

record.read

Path parameters

record_id: integer

revision_id: integer

Query parameters

revision: integer

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

Responses

200 - OK

Return the file revision.

GET /api/v1/records/{record_id}/files/{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.

Required scopes

record.read

Path parameters

record_id: integer

file_id: string

Responses

200 - OK

Return the file.

GET /api/v1/records/{record_id}/files/{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.

Required scopes

record.read

Path parameters

record_id: integer

file_id: string

Responses

200 - OK

Return the file as attachment.

GET /api/v1/records/{record_id}/records/{link_id}

Get a record link.

Will return the outgoing record link specified by the given link ID from the record specified by the given record ID.

Required scopes

record.read

Path parameters

record_id: integer

link_id: integer

Responses

200 - OK

Return the record link.

GET /api/v1/records/{record_id}/revisions/{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.

Required scopes

record.read

Path parameters

record_id: integer

revision_id: integer

Query parameters

revision: integer

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

Responses

200 - OK

Return the record revision.

GET /api/v1/records/{record_id}/uploads/{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 otherwise.

Required scopes

record.update

Path parameters

record_id: integer

upload_id: string

Responses

200 - OK

Return the upload.

POST

POST /api/v1/records	Create a new record.
POST /api/v1/records/{id}/collections	Add the record specified by the given ID to a collection.
POST /api/v1/records/{id}/purge	Purge the deleted record specified by the given ID.
POST /api/v1/records/{id}/records	Create a new record link.
POST /api/v1/records/{id}/restore	Restore the deleted record specified by the given ID.
POST /api/v1/records/{id}/roles/groups	Add a group role to the record specified by the given ID.
POST /api/v1/records/{id}/roles/users	Add a user role to the record specified by the given ID.
POST /api/v1/records/{id}/uploads	Upload a new file to the record specified by the given ID.
POST /api/v1/records/{record_id}/uploads/{upload_id}	Finish a chunked upload.

POST /api/v1/records

Create a new record.

Required scopes

record.create

Request body (JSON object)

The metadata of the new record.

identifier: string (required)

title: string (required)

description: string

extras: array<object>

license: string

tags: array<string>

type: string

visibility: string

Responses

201 - Created

Return the new record.

409 - Conflict

A conflict occured while trying to create the record.

POST /api/v1/records/{id}/collections

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

Required scopes

record.link

Path parameters

id: integer

Request body (JSON object)

The collection to add the record to.

id: integer (required)

Responses

201 - Created

Record successfully added to collection.

409 - Conflict

The link already exists.

POST /api/v1/records/{id}/purge

Purge the deleted record specified by the given ID.

Will remove 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.

Required scopes

misc.manage_trash

Path parameters

id: integer

Responses

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/v1/records/{id}/records

Create a new record link.

Will create a new outgoing record link from the record specified by the given ID.

Required scopes

record.link

Path parameters

id: integer

Request body (JSON object)

The metadata of the new record link.

name: string (required)

record_to: object (required)

id: integer (required)

term: string

Responses

201 - Created

Return the new record link.

409 - Conflict

When trying to link the record with itself or the link already exists.

POST /api/v1/records/{id}/restore

Restore the deleted record specified by the given ID.

Only the creator of a record can restore it.

Required scopes

misc.manage_trash

Path parameters

id: integer

Responses

200 - OK

Return the restored record.

POST /api/v1/records/{id}/roles/groups

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

Required scopes

record.permissions

Path parameters

id: integer

Request body (JSON object)

The group and corresponding role to add.

group: object (required)

id: integer (required)

role: object (required)

name: string (required)

Responses

201 - Created

Group role successfully added to record.

409 - Conflict

A role for that group already exists.

POST /api/v1/records/{id}/roles/users

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

Required scopes

record.permissions

Path parameters

id: integer

Request body (JSON object)

The user and corresponding role to add.

role: object (required)

name: string (required)

user: object (required)

id: integer (required)

Responses

201 - Created

User role successfully added to record.

409 - Conflict

A role for that user already exists.

POST /api/v1/records/{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 endpoint PUT /api/v1/records/{record_id}/uploads/{upload_id} is used to upload the file data, which is also returned as the _actions.upload_data property of the returned upload. The required size for uploading chunks (except for the final chunk for chunked uploads) is returned as the _meta.chunk_size property of the returned upload. For direct uploads, the chunk size is always equal to the total upload size.

Required scopes

record.update

Path parameters

id: integer

Request body (JSON object)

The metadata of the new upload.

name: string (required)

size: integer (required)

description: string

mimetype: string

Responses

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 and can be updated using the endpoint PUT /api/v1/records/{record_id}/files/{file_id}, which is also returned as the _actions.edit_data property of the returned file.

413 - Request Entity Too Large

The user's upload quota was exceeded.

POST /api/v1/records/{record_id}/uploads/{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 endpoint GET /api/v1/records/{record_id}/uploads/{upload_id}, which is also returned as the _links.self property of the returned upload.

Required scopes

record.update

Path parameters

record_id: integer

upload_id: string

Responses

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/v1/records/{id}	Update the record specified by the given ID.
PATCH /api/v1/records/{record_id}/files/{file_id}	Update the metadata of a file of a record.
PATCH /api/v1/records/{record_id}/records/{link_id}	Update a record link.
PATCH /api/v1/records/{record_id}/roles/groups/{group_id}	Change a group role of a record.
PATCH /api/v1/records/{record_id}/roles/users/{user_id}	Change a user role of a record.

PATCH /api/v1/records/{id}

Update the record specified by the given ID.

Required scopes

record.update

Path parameters

id: integer

Request body (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

Responses

200 - OK

Return the updated record.

409 - Conflict

A conflict occured while trying to update the record.

PATCH /api/v1/records/{record_id}/files/{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.

Required scopes

record.update

Path parameters

record_id: integer

file_id: string

Request body (JSON object)

The new metadata of the file.

description: string

mimetype: string

name: string

Responses

200 - OK

Return the updated file.

409 - Conflict

A conflict occured while trying to update the file.

PATCH /api/v1/records/{record_id}/records/{link_id}

Update a record link.

Will update the outgoing record link specified by the given link ID from the record specified by the given record ID.

Required scopes

record.link

Path parameters

record_id: integer

link_id: integer

Request body (JSON object)

The metadata of the new record link.

name: string

record_to: object

id: integer

term: string

Responses

200 - OK

Return the updated record link.

409 - Conflict

The link already exists.

PATCH /api/v1/records/{record_id}/roles/groups/{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.

Required scopes

record.permissions

Path parameters

record_id: integer

group_id: integer

Request body (JSON object)

The new group role.

name: string (required)

Responses

204 - No Content

Group role successfully changed.

409 - Conflict

A conflict occured while trying to change the role.

PATCH /api/v1/records/{record_id}/roles/users/{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.

Required scopes

record.permissions

Path parameters

record_id: integer

user_id: integer

Request body (JSON object)

The new user role.

name: string (required)

Responses

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/v1/records/{record_id}/files/{file_id}	Update the data of a file of a record.
PUT /api/v1/records/{record_id}/uploads/{upload_id}	Upload the data of an upload.

PUT /api/v1/records/{record_id}/files/{file_id}

Update the data of a file of a record.

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 when using the endpoint POST /api/v1/records/{id}/uploads for new uploads.

Required scopes

record.update

Path parameters

record_id: integer

file_id: string

Request body (JSON object)

The metadata of the new upload.

size: integer (required)

description: string

mimetype: string

Responses

201 - Created

Return the new upload.

413 - Request Entity Too Large

The user's upload quota was exceeded.

PUT /api/v1/records/{record_id}/uploads/{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 using the generic application/octet-stream content type. Which contents to actually upload depends on the upload type:

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 endpoint POST /api/v1/records/{record_id}/uploads/{upload_id}, which is also returned as the _actions.finish property of the returned upload.

Required scopes

record.update

Path parameters

record_id: integer

upload_id: string

Header parameters

Kadi-Chunk-Index: integer (required)

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

Kadi-Chunk-Size: integer (required)

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

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.

Responses

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/v1/records/{id}	Mark the record specified by the given ID as deleted.
DELETE /api/v1/records/{record_id}/collections/{collection_id}	Remove a record from a collection.
DELETE /api/v1/records/{record_id}/files/{file_id}	Delete a file of a record.
DELETE /api/v1/records/{record_id}/records/{link_id}	Remove a record link.
DELETE /api/v1/records/{record_id}/roles/groups/{group_id}	Remove a group role from a record.
DELETE /api/v1/records/{record_id}/roles/users/{user_id}	Remove a user role from a record.
DELETE /api/v1/records/{record_id}/uploads/{upload_id}	Delete an upload of a record.

DELETE /api/v1/records/{id}

Mark the record specified by the given ID as deleted.

Until being removed automatically, a deleted record may be restored or purged using the endpoints POST /api/v1/records/{id}/restore or POST /api/v1/records/{id}/purge, respectively.

Required scopes

record.delete

Path parameters

id: integer

Responses

204 - No Content

Record successfully marked as deleted.

DELETE /api/v1/records/{record_id}/collections/{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.

Required scopes

record.link

Path parameters

record_id: integer

collection_id: integer

Responses

204 - No Content

Record successfully removed from collection.

DELETE /api/v1/records/{record_id}/files/{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.

Required scopes

record.update

Path parameters

record_id: integer

file_id: string

Responses

204 - No Content

File deleted successfully.

DELETE /api/v1/records/{record_id}/records/{link_id}

Remove a record link.

Will remove the outgoing record link specified by the given link ID from the record specified by the given record ID.

Required scopes

record.link

Path parameters

record_id: integer

link_id: integer

Responses

204 - No Content

Record link removed successfully.

DELETE /api/v1/records/{record_id}/roles/groups/{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.

Required scopes

record.permissions

Path parameters

record_id: integer

group_id: integer

Responses

204 - No Content

Group role successfully removed from record.

DELETE /api/v1/records/{record_id}/roles/users/{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.

Required scopes

record.permissions

Path parameters

record_id: integer

user_id: integer

Responses

204 - No Content

User role successfully removed from record.

409 - Conflict

When trying to remove the creator's role.

DELETE /api/v1/records/{record_id}/uploads/{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.

Required scopes

record.update

Path parameters

record_id: integer

upload_id: string

Responses

204 - No Content

Upload deleted successfully.

Collections

The following subsections describe all endpoints related to collections, grouped by HTTP method. To get more detailed information about the contents of the requested/returned representation of resources related to collections, see also Collection. 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/v1/collections	Search and filter for collections.
GET /api/v1/collections/identifier/{identifier}	Get the collection specified by the given identifier.
GET /api/v1/collections/{collection_id}/revisions/{revision_id}	Get a collection revision.
GET /api/v1/collections/{id}	Get the collection specified by the given ID.
GET /api/v1/collections/{id}/collections	Get child collections of the collection specified by the given ID.
GET /api/v1/collections/{id}/export/{export_type}	Export the collection specified by the given ID using the given export type.
GET /api/v1/collections/{id}/records	Get records the collection specified by the given ID contains.
GET /api/v1/collections/{id}/revisions	Get revisions of the collection specified by the given ID.
GET /api/v1/collections/{id}/roles/groups	Get group roles of the collection specified by the given ID.
GET /api/v1/collections/{id}/roles/users	Get user roles of the collection specified by the given ID.

GET /api/v1/collections

Search and filter for collections.

Required scopes

collection.read

Query parameters

page: integer (default: 1)

The current result page.

Minimum: 1

Maximum: 100

per_page: integer (default: 10)

Number of results per page.

Minimum: 1

Maximum: 100

query: string

A query to search the collections with. Supports exact matches when surrounded by double quotes.

sort: string (default: _score)

The order of the search results. Falls back to -last_modified if no search query is given.

One of: _score, last_modified, -last_modified, created_at, -created_at, title, -title, identifier, -identifier.

visibility: string

A visibility value to filter the collections with.

One of: private, public.

explicit_permissions: boolean (default: False)

Flag indicating whether only collections with explicit access permissions should be included, independent of their visibility.

user: array<integer>

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: array<string>

Tags to filter the collections with. All given tags are filtered using the operator specified via the tag_operator parameter.

Can be specified more than once.

tag_operator: string (default: or)

The operator to filter the tags with.

One of: or, and.

instance: string

The name of an external Kadi4Mat instance to search instead.

Responses

200 - OK

Return a paginated array of collections.

400 - Bad Request

The specified external Kadi4Mat instance is invalid or has not yet been connected to the current user's account.

502 - Bad Gateway

The request to the specified external Kadi4Mat instance failed.

GET /api/v1/collections/identifier/{identifier}

Get the collection specified by the given identifier.

Required scopes

collection.read

Path parameters

identifier: string

Responses

200 - OK

Return the collection.

GET /api/v1/collections/{collection_id}/revisions/{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.

Required scopes

collection.read

Path parameters

collection_id: integer

revision_id: integer

Query parameters

revision: integer

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

Responses

200 - OK

Return the revision.

GET /api/v1/collections/{id}

Get the collection specified by the given ID.

Required scopes

collection.read

Path parameters

id: integer

Responses

200 - OK

Return the collection.

GET /api/v1/collections/{id}/collections

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

Required scopes

collection.read

Path parameters

id: integer

Query parameters

page: integer (default: 1)

The current result page.

Minimum: 1

per_page: integer (default: 10)

Number of results per page.

Minimum: 1

Maximum: 100

filter: string

A query to filter the collections by their title or identifier.

sort: string (default: -last_modified)

The order of the returned collections.

One of: last_modified, -last_modified, created_at, -created_at, title, -title, identifier, -identifier.

action: array<string>

Further actions the current user needs permission to perform in the child collections.

Can be specified more than once.

Responses

200 - OK

Return a paginated array of collections.

GET /api/v1/collections/{id}/export/{export_type}

Export the collection specified by the given ID using the given export type.

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

Required scopes

collection.read

Path parameters

id: integer

export_type: string

Query parameters

filter: string (default: {})

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

Responses

200 - OK

Return the exported collection data.

GET /api/v1/collections/{id}/records

Get records the collection specified by the given ID contains.

Required scopes

collection.read
record.read

Path parameters

id: integer

Query parameters

page: integer (default: 1)

The current result page.

Minimum: 1

per_page: integer (default: 10)

Number of results per page.

Minimum: 1

Maximum: 100

filter: string

A query to filter the records by their title or identifier.

sort: string (default: -last_modified)

The order of the returned records.

One of: last_modified, -last_modified, created_at, -created_at, title, -title, identifier, -identifier.

action: array<string>

Further actions the current user needs permission to perform in the linked records.

Can be specified more than once.

children: boolean (default: False)

Flag indicating whether records of child collections should be included in the results.

Responses

200 - OK

Return a paginated array of records.

GET /api/v1/collections/{id}/revisions

Get revisions of the collection specified by the given ID.

Required scopes

collection.read

Path parameters

id: integer

Query parameters

page: integer (default: 1)

The current result page.

Minimum: 1

per_page: integer (default: 10)

Number of results per page.

Minimum: 1

Maximum: 100

Responses

200 - OK

Return a paginated array of revisions, sorted by revision timestamp in descending order.

GET /api/v1/collections/{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 (id, title, identifier and visibility).

Required scopes

collection.read
group.read

Path parameters

id: integer

Query parameters

page: integer (default: 1)

The current result page.

Minimum: 1

per_page: integer (default: 10)

Number of results per page.

Minimum: 1

Maximum: 100

filter: string

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

Responses

200 - OK

Return a paginated array of group roles, sorted by role name and then by group ID in ascending order.

GET /api/v1/collections/{id}/roles/users

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

Required scopes

collection.read
user.read

Path parameters

id: integer

Query parameters

page: integer (default: 1)

The current result page.

Minimum: 1

per_page: integer (default: 10)

Number of results per page.

Minimum: 1

Maximum: 100

filter: string

A query to filter the users by their username or display name.

exclude: array<integer>

User IDs to exclude.

Can be specified more than once.

Responses

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.

POST

POST /api/v1/collections	Create a new collection.
POST /api/v1/collections/{id}/collections	Add a child collection to the collection specified by the given ID.
POST /api/v1/collections/{id}/purge	Purge the deleted collection specified by the given ID.
POST /api/v1/collections/{id}/records	Add a record to the collection specified by the given ID.
POST /api/v1/collections/{id}/restore	Restore the deleted collection specified by the given ID.
POST /api/v1/collections/{id}/roles/groups	Add a group role to the collection specified by the given ID.
POST /api/v1/collections/{id}/roles/users	Add a user role to the collection specified by the given ID.

POST /api/v1/collections

Create a new collection.

Required scopes

collection.create

Request body (JSON object)

The metadata of the new collection.

identifier: string (required)

title: string (required)

description: string

tags: array<string>

visibility: string

Responses

201 - Created

Return the new collection.

409 - Conflict

A conflict occured while trying to create the collection.

POST /api/v1/collections/{id}/collections

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

Required scopes

collection.link

Path parameters

id: integer

Request body (JSON object)

The child collection to add to the collection.

id: integer (required)

Responses

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/v1/collections/{id}/purge

Purge the deleted collection specified by the given ID.

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

Required scopes

misc.manage_trash

Path parameters

id: integer

Responses

204 - No Content

Collection purged successfully.

POST /api/v1/collections/{id}/records

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

Required scopes

collection.link

Path parameters

id: integer

Request body (JSON object)

The record to add to the collection.

id: integer (required)

Responses

201 - Created

Record successfully added to collection.

409 - Conflict

The link already exists.

POST /api/v1/collections/{id}/restore

Restore the deleted collection specified by the given ID.

Only the creator of a collection can restore it.

Required scopes

misc.manage_trash

Path parameters

id: integer

Responses

200 - OK

Return the restored collection.

POST /api/v1/collections/{id}/roles/groups

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

Required scopes

collection.permissions

Path parameters

id: integer

Request body (JSON object)

The group and corresponding role to add.

group: object (required)

id: integer (required)

role: object (required)

name: string (required)

Responses

201 - Created

Group role successfully added to collection.

409 - Conflict

A role for that group already exists.

POST /api/v1/collections/{id}/roles/users

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

Required scopes

collection.permissions

Path parameters

id: integer

Request body (JSON object)

The user and corresponding role to add.

role: object (required)

name: string (required)

user: object (required)

id: integer (required)

Responses

201 - Created

User role successfully added to collection.

409 - Conflict

A role for that user already exists.

PATCH

PATCH /api/v1/collections/{collection_id}/roles/groups/{group_id}	Change a group role of a collection.
PATCH /api/v1/collections/{collection_id}/roles/users/{user_id}	Change a user role of a collection.
PATCH /api/v1/collections/{id}	Update the collection specified by the given ID.

PATCH /api/v1/collections/{collection_id}/roles/groups/{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.

Required scopes

collection.permissions

Path parameters

collection_id: integer

group_id: integer

Request body (JSON object)

The new group role.

name: string (required)

Responses

204 - No Content

Group role successfully changed.

409 - Conflict

A conflict occured while trying to change the role.

PATCH /api/v1/collections/{collection_id}/roles/users/{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.

Required scopes

collection.permissions

Path parameters

collection_id: integer

user_id: integer

Request body (JSON object)

The new user role.

name: string (required)

Responses

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/v1/collections/{id}

Update the collection specified by the given ID.

Required scopes

collection.update

Path parameters

id: integer

Request body (JSON object)

The new metadata of the collection.

description: string

identifier: string

tags: array<string>

title: string

visibility: string

Responses

200 - OK

Return the updated collection.

409 - Conflict

A conflict occured while trying to update the collection.

DELETE

DELETE /api/v1/collections/{collection_id}/collections/{child_id}	Remove a child collection from a collection.
DELETE /api/v1/collections/{collection_id}/records/{record_id}	Remove a record from a collection.
DELETE /api/v1/collections/{collection_id}/roles/groups/{group_id}	Remove a group role from a collection.
DELETE /api/v1/collections/{collection_id}/roles/users/{user_id}	Remove a user role from a collection.
DELETE /api/v1/collections/{id}	Mark the collection specified by the given ID as deleted.

DELETE /api/v1/collections/{collection_id}/collections/{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.

Required scopes

collection.link

Path parameters

collection_id: integer

child_id: integer

Responses

204 - No Content

Child successfully removed from collection.

DELETE /api/v1/collections/{collection_id}/records/{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.

Required scopes

collection.link

Path parameters

collection_id: integer

record_id: integer

Responses

204 - No Content

Record successfully removed from collection.

DELETE /api/v1/collections/{collection_id}/roles/groups/{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.

Required scopes

collection.permissions

Path parameters

collection_id: integer

group_id: integer

Responses

204 - No Content

Group role successfully removed from collection.

DELETE /api/v1/collections/{collection_id}/roles/users/{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.

Required scopes

collection.permissions

Path parameters

collection_id: integer

user_id: integer

Responses

204 - No Content

User role successfully removed from collection.

409 - Conflict

When trying to remove the creator's role.

DELETE /api/v1/collections/{id}

Mark the collection specified by the given ID as deleted.

Until being removed automatically, a deleted collection may be restored or purged using the endpoints POST /api/v1/collections/{id}/restore or POST /api/v1/collections/{id}/purge, respectively.

Required scopes

collection.delete

Path parameters

id: integer

Responses

204 - No Content

Collection successfully marked as deleted.

Templates

The following subsections describe all endpoints related to templates, grouped by HTTP method. To get more detailed information about the contents of the requested/returned representation of resources related to templates, see also Template, especially Template.data. For possible role values, see also the Miscellaneous endpoints.

GET

GET /api/v1/templates	Search and filter for templates.
GET /api/v1/templates/identifier/{identifier}	Get the template specified by the given identifier.
GET /api/v1/templates/{id}	Get the template specified by the given ID.
GET /api/v1/templates/{id}/export/{export_type}	Export the template specified by the given ID using the given export type.
GET /api/v1/templates/{id}/revisions	Get revisions of the template specified by the given ID.
GET /api/v1/templates/{id}/roles/groups	Get group roles of the template specified by the given ID.
GET /api/v1/templates/{id}/roles/users	Get user roles of the template specified by the given ID.
GET /api/v1/templates/{template_id}/revisions/{revision_id}	Get a template revision.

GET /api/v1/templates

Search and filter for templates.

Required scopes

template.read

Query parameters

page: integer (default: 1)

The current result page.

Minimum: 1

Maximum: 100

per_page: integer (default: 10)

Number of results per page.

Minimum: 1

Maximum: 100

query: string

A query to search the templates with. Supports exact matches when surrounded by double quotes.

sort: string (default: _score)

The order of the search results. Falls back to -last_modified if no search query is given.

One of: _score, last_modified, -last_modified, created_at, -created_at, title, -title, identifier, -identifier.

visibility: string

A visibility value to filter the templates with.

One of: private, public.

explicit_permissions: boolean (default: False)

Flag indicating whether only templates with explicit access permissions should be included, independent of their visibility.

user: array<integer>

User IDs to filter the templates with in relation to their creator. All given users are filtered using an OR operation.

Can be specified more than once.

type: string

A type value to filter the templates with.

One of: record, extras.

instance: string

The name of an external Kadi4Mat instance to search instead.

Responses

200 - OK

Return a paginated array of templates.

400 - Bad Request

The specified external Kadi4Mat instance is invalid or has not yet been connected to the current user's account.

502 - Bad Gateway

The request to the specified external Kadi4Mat instance failed.

GET /api/v1/templates/identifier/{identifier}

Get the template specified by the given identifier.

Required scopes

template.read

Path parameters

identifier: string

Responses

200 - OK

Return the template.

GET /api/v1/templates/{id}

Get the template specified by the given ID.

Required scopes

template.read

Path parameters

id: integer

Responses

200 - OK

Return the template.

GET /api/v1/templates/{id}/export/{export_type}

Export the template specified by the given ID using the given export type.

Currently, json, json-schema and shacl are supported as export types.

Required scopes

template.read

Path parameters

id: integer

export_type: string

Query parameters

filter: string (default: {})

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

Responses

200 - OK

Return the exported template data.

GET /api/v1/templates/{id}/revisions

Get revisions of the template specified by the given ID.

Required scopes

template.read

Path parameters

id: integer

Query parameters

page: integer (default: 1)

The current result page.

Minimum: 1

per_page: integer (default: 10)

Number of results per page.

Minimum: 1

Maximum: 100

Responses

200 - OK

Return a paginated array of revisions, sorted by revision timestamp in descending order.

GET /api/v1/templates/{id}/roles/groups

Get group roles of the template specified by the given ID.

If a user can manage permissions of this template, all group roles are returned. However, groups that a user can normally not read include only a limited subset of attributes (id, title, identifier and visibility).

Required scopes

template.read
group.read

Path parameters

id: integer

Query parameters

page: integer (default: 1)

The current result page.

Minimum: 1

per_page: integer (default: 10)

Number of results per page.

Minimum: 1

Maximum: 100

filter: string

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

Responses

200 - OK

Return a paginated array of group roles, sorted by role name and then by group ID in ascending order.

GET /api/v1/templates/{id}/roles/users

Get user roles of the template specified by the given ID.

Required scopes

template.read
user.read

Path parameters

id: integer

Query parameters

page: integer (default: 1)

The current result page.

Minimum: 1

per_page: integer (default: 10)

Number of results per page.

Minimum: 1

Maximum: 100

filter: string

A query to filter the users by their username or display name.

exclude: array<integer>

User IDs to exclude.

Can be specified more than once.

Responses

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/v1/templates/{template_id}/revisions/{revision_id}

Get a template revision.

Will return the revision specified by the given revision ID of the template specified by the given template ID.

Required scopes

template.read

Path parameters

template_id: integer

revision_id: integer

Query parameters

revision: integer

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

Responses

200 - OK

Return the revision.

POST

POST /api/v1/templates	Create a new template.
POST /api/v1/templates/{id}/purge	Purge the deleted template specified by the given ID.
POST /api/v1/templates/{id}/restore	Restore the deleted template specified by the given ID.
POST /api/v1/templates/{id}/roles/groups	Add a group role to the template specified by the given ID.
POST /api/v1/templates/{id}/roles/users	Add a user role to the template specified by the given ID.

POST /api/v1/templates

Create a new template.

Required scopes

template.create

Request body (JSON object)

The metadata and data of the new template, depending on its type.

data: object | array<object> (required)

identifier: string (required)

title: string (required)

type: string (required)

description: string

visibility: string

Responses

201 - Created

Return the new template.

POST /api/v1/templates/{id}/purge

Purge the deleted template specified by the given ID.

Will remove the template permanently. Only the creator of a template can purge it.

Required scopes

misc.manage_trash

Path parameters

id: integer

Responses

204 - No Content

Template purged successfully.

POST /api/v1/templates/{id}/restore

Restore the deleted template specified by the given ID.

Only the creator of a template can restore it.

Required scopes

misc.manage_trash

Path parameters

id: integer

Responses

200 - OK

Return the restored template.

POST /api/v1/templates/{id}/roles/groups

Add a group role to the template specified by the given ID.

Required scopes

template.permissions

Path parameters

id: integer

Request body (JSON object)

The group and corresponding role to add.

group: object (required)

id: integer (required)

role: object (required)

name: string (required)

Responses

201 - Created

Group role successfully added to template.

409 - Conflict

A role for that group already exists.

POST /api/v1/templates/{id}/roles/users

Add a user role to the template specified by the given ID.

Required scopes

template.permissions

Path parameters

id: integer

Request body (JSON object)

The user and corresponding role to add.

role: object (required)

name: string (required)

user: object (required)

id: integer (required)

Responses

201 - Created

User role successfully added to template.

409 - Conflict

A role for that user already exists.

PATCH

PATCH /api/v1/templates/{id}	Update the template specified by the given ID.
PATCH /api/v1/templates/{template_id}/roles/groups/{group_id}	Change a group role of a template.
PATCH /api/v1/templates/{template_id}/roles/users/{user_id}	Change a user role of a template.

PATCH /api/v1/templates/{id}

Update the template specified by the given ID.

Required scopes

template.update

Path parameters

id: integer

Request body (JSON object)

The new metadata and data of the template, depending on its type.

data: object | array<object>

description: string

identifier: string

title: string

visibility: string

Responses

200 - OK

Return the updated template.

PATCH /api/v1/templates/{template_id}/roles/groups/{group_id}

Change a group role of a template.

Will change the role of the group specified by the given group ID of the template specified by the given template ID.

Required scopes

template.permissions

Path parameters

template_id: integer

group_id: integer

Request body (JSON object)

The new group role.

name: string (required)

Responses

204 - No Content

Group role successfully changed.

409 - Conflict

A conflict occured while trying to change the role.

PATCH /api/v1/templates/{template_id}/roles/users/{user_id}

Change a user role of a template.

Will change the role of the user specified by the given user ID of the template specified by the given template ID.

Required scopes

template.permissions

Path parameters

template_id: integer

user_id: integer

Request body (JSON object)

The new user role.

name: string (required)

Responses

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.

DELETE

DELETE /api/v1/templates/{id}	Mark the template specified by the given ID as deleted.
DELETE /api/v1/templates/{template_id}/roles/groups/{group_id}	Remove a group role from a template.
DELETE /api/v1/templates/{template_id}/roles/users/{user_id}	Remove a user role from a template.

DELETE /api/v1/templates/{id}

Mark the template specified by the given ID as deleted.

Until being removed automatically, a deleted template may be restored or purged using the endpoints POST /api/v1/templates/{id}/restore or POST /api/v1/templates/{id}/purge, respectively.

Required scopes

template.delete

Path parameters

id: integer

Responses

204 - No Content

Template successfully marked as deleted.

DELETE /api/v1/templates/{template_id}/roles/groups/{group_id}

Remove a group role from a template.

Will remove the role of the group specified by the given group ID from the template specified by the given template ID.

Required scopes

template.permissions

Path parameters

template_id: integer

group_id: integer

Responses

204 - No Content

Group role successfully removed from template.

DELETE /api/v1/templates/{template_id}/roles/users/{user_id}

Remove a user role from a template.

Will remove the role of the user specified by the given user ID from the template specified by the given template ID.

Required scopes

template.permissions

Path parameters

template_id: integer

user_id: integer

Responses

204 - No Content

User role successfully removed from template.

409 - Conflict

When trying to remove the creator's role.

Users

The following subsections describe all endpoints related to users, grouped by HTTP method. To get more detailed information about some the contents of the requested/returned representation of resources related to users, see also User and the different Identity classes.

GET

GET /api/v1/users	Get registered users.
GET /api/v1/users/me	Get the currently authenticated user.
GET /api/v1/users/{identity_type}/{username}	Get the user specified by the given identity type and username.
GET /api/v1/users/{id}	Get the user specified by the given ID.
GET /api/v1/users/{id}/collections	Get created or shared collections of the user specified by the given ID.
GET /api/v1/users/{id}/groups	Get created or common groups of the user specified by the given ID.
GET /api/v1/users/{id}/identities	Get all identities of the user specified by the given ID.
GET /api/v1/users/{id}/records	Get created or shared records of the user specified by the given ID.
GET /api/v1/users/{id}/templates	Get created or shared templates of the user specified by the given ID.

GET /api/v1/users

Get registered users.

Required scopes

user.read

Query parameters

page: integer (default: 1)

The current result page.

Minimum: 1

per_page: integer (default: 10)

Number of results per page.

Minimum: 1

Maximum: 100

filter: string

A query to filter the users by their display name or username.

inactive: boolean (default: False)

Flag indicating whether inactive users should be returned as well.

Responses

200 - OK

Return a paginated array of users, sorted by creation date in descending order.

GET /api/v1/users/me

Get the currently authenticated user.

Required scopes

user.read

Responses

200 - OK

Return the current user.

GET /api/v1/users/{identity_type}/{username}

Get the user specified by the given identity type and username.

Required scopes

user.read

Path parameters

identity_type: string

username: string

Responses

200 - OK

Return the user.

GET /api/v1/users/{id}

Get the user specified by the given ID.

Required scopes

user.read

Path parameters

id: integer

Responses

200 - OK

Return the user.

GET /api/v1/users/{id}/collections

Get created or shared collections of the user specified by the given ID.

Required scopes

user.read
collection.read

Path parameters

id: integer

Query parameters

page: integer (default: 1)

The current result page.

Minimum: 1

per_page: integer (default: 10)

Number of results per page.

Minimum: 1

Maximum: 100

filter: string

A query to filter the collections by their title or identifier.

sort: string (default: -last_modified)

The order of the returned collections.

One of: last_modified, -last_modified, created_at, -created_at, title, -title, identifier, -identifier.

shared: boolean (default: False)

Flag indicating whether collections the user created should be returned or collections created by the current user that were explicitly shared with the user.

Responses

200 - OK

Return a paginated array of collections.

GET /api/v1/users/{id}/groups

Get created or common groups of the user specified by the given ID.

Required scopes

user.read
group.read

Path parameters

id: integer

Query parameters

page: integer (default: 1)

The current result page.

Minimum: 1

per_page: integer (default: 10)

Number of results per page.

Minimum: 1

Maximum: 100

filter: string

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

sort: string (default: -last_modified)

The order of the returned groups.

One of: last_modified, -last_modified, created_at, -created_at, title, -title, identifier, -identifier.

common: boolean (default: False)

Flag indicating whether groups the user created should be returned or groups that the current user and the specified user have in common regarding group membership.

Responses

200 - OK

Return a paginated array of groups.

GET /api/v1/users/{id}/identities

Get all identities of the user specified by the given ID.

Required scopes

user.read

Path parameters

id: integer

Responses

200 - OK

Return an array of identities, sorted by creation date in ascending order.

GET /api/v1/users/{id}/records

Get created or shared records of the user specified by the given ID.

Required scopes

user.read
record.read

Path parameters

id: integer

Query parameters

page: integer (default: 1)

The current result page.

Minimum: 1

per_page: integer (default: 10)

Number of results per page.

Minimum: 1

Maximum: 100

filter: string

A query to filter the records by their title or identifier.

sort: string (default: -last_modified)

The order of the returned records.

One of: last_modified, -last_modified, created_at, -created_at, title, -title, identifier, -identifier.

shared: boolean (default: False)

Flag indicating whether records the user created should be returned or records created by the current user that were explicitly shared with the user.

Responses

200 - OK

Return a paginated array of records.

GET /api/v1/users/{id}/templates

Get created or shared templates of the user specified by the given ID.

Required scopes

user.read
template.read

Path parameters

id: integer

Query parameters

page: integer (default: 1)

The current result page.

Minimum: 1

per_page: integer (default: 10)

Number of results per page.

Minimum: 1

Maximum: 100

filter: string

A query to filter the templates by their title or identifier.

sort: string (default: -last_modified)

The order of the returned templates.

One of: last_modified, -last_modified, created_at, -created_at, title, -title, identifier, -identifier.

shared: boolean (default: False)

Flag indicating whether templates the user created should be returned or templates created by the current user that were explicitly shared with the user.

Responses

200 - OK

Return a paginated array of templates.

Groups

The following subsections describe all endpoints related to groups, grouped by HTTP method. To get more detailed information about the contents of the requested/returned representation of resources related to groups, see also Group. For possible role values, see also the Miscellaneous endpoints.

GET

GET /api/v1/groups	Search and filter for groups.
GET /api/v1/groups/identifier/{identifier}	Get the group specified by the given identifier.
GET /api/v1/groups/{group_id}/revisions/{revision_id}	Get a group revision.
GET /api/v1/groups/{id}	Get the group specified by the given ID.
GET /api/v1/groups/{id}/collections	Get collections shared with the group with the given ID.
GET /api/v1/groups/{id}/members	Get members of the group specified by the given ID.
GET /api/v1/groups/{id}/records	Get records shared with the group with the given ID.
GET /api/v1/groups/{id}/revisions	Get revisions of the group specified by the given ID.
GET /api/v1/groups/{id}/templates	Get templates shared with the group with the given ID.

GET /api/v1/groups

Search and filter for groups.

Required scopes

group.read

Query parameters

page: integer (default: 1)

The current result page.

Minimum: 1

Maximum: 100

per_page: integer (default: 10)

Number of results per page.

Minimum: 1

Maximum: 100

query: string

A query to search the groups with. Supports exact matches when surrounded by double quotes.

sort: string (default: _score)

The order of the search results. Falls back to -last_modified if no search query is given.

One of: _score, last_modified, -last_modified, created_at, -created_at, title, -title, identifier, -identifier.

visibility: string

A visibility value to filter the groups with.

One of: private, public.

member_only: boolean (default: False)

Flag indicating whether only groups with membership should be included, independent of their visibility.

user: array<integer>

User IDs to filter the groups with in relation to their creator. All given users are filtered using an OR operation.

Can be specified more than once.

Responses

200 - OK

Return a paginated array of groups.

GET /api/v1/groups/identifier/{identifier}

Get the group specified by the given identifier.

Required scopes

group.read

Path parameters

identifier: string

Responses

200 - OK

Return the group.

GET /api/v1/groups/{group_id}/revisions/{revision_id}

Get a group revision.

Will return the revision specified by the given revision ID of the group specified by the given group ID.

Required scopes

group.read

Path parameters

group_id: integer

revision_id: integer

Query parameters

revision: integer

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

Responses

200 - OK

Return the revision.

GET /api/v1/groups/{id}

Get the group specified by the given ID.

Required scopes

group.read

Path parameters

id: integer

Responses

200 - OK

Return the group.

GET /api/v1/groups/{id}/collections

Get collections shared with the group with the given ID.

Shared means that the group needs to have explicit read permission for a collection.

Required scopes

group.read
collection.read

Path parameters

id: integer

Query parameters

page: integer (default: 1)

The current result page.

Minimum: 1

per_page: integer (default: 10)

Number of results per page.

Minimum: 1

Maximum: 100

filter: string

A query to filter the collections by their title or identifier.

sort: string (default: -last_modified)

The order of the returned collections.

One of: last_modified, -last_modified, created_at, -created_at, title, -title, identifier, -identifier.

Responses

200 - OK

Return a paginated array of collections.

GET /api/v1/groups/{id}/members

Get members of the group specified by the given ID.

Required scopes

group.read
user.read

Path parameters

id: integer

Query parameters

page: integer (default: 1)

The current result page.

Minimum: 1

per_page: integer (default: 10)

Number of results per page.

Minimum: 1

Maximum: 100

filter: string

A query to filter the members by their username or display name.

exclude: array<integer>

User IDs to exclude.

Can be specified more than once.

Responses

200 - OK

Return a paginated array of members, sorted by role name and then by user ID in ascending order. The creator will always be listed first.

GET /api/v1/groups/{id}/records

Get records shared with the group with the given ID.

Shared means that the group needs to have explicit read permission for a record.

Required scopes

group.read
record.read

Path parameters

id: integer

Query parameters

page: integer (default: 1)

The current result page.

Minimum: 1

per_page: integer (default: 10)

Number of results per page.

Minimum: 1

Maximum: 100

filter: string

A query to filter the records by their title or identifier.

sort: string (default: -last_modified)

The order of the returned records.

One of: last_modified, -last_modified, created_at, -created_at, title, -title, identifier, -identifier.

Responses

200 - OK

Return a paginated array of records.

GET /api/v1/groups/{id}/revisions

Get revisions of the group specified by the given ID.

Required scopes

group.read

Path parameters

id: integer

Query parameters

page: integer (default: 1)

The current result page.

Minimum: 1

per_page: integer (default: 10)

Number of results per page.

Minimum: 1

Maximum: 100

Responses

200 - OK

Return a paginated array of revisions, sorted by revision timestamp in descending order.

GET /api/v1/groups/{id}/templates

Get templates shared with the group with the given ID.

Shared means that the group needs to have explicit read permission for a template.

Required scopes

group.read
template.read

Path parameters

id: integer

Query parameters

page: integer (default: 1)

The current result page.

Minimum: 1

per_page: integer (default: 10)

Number of results per page.

Minimum: 1

Maximum: 100

filter: string

A query to filter the templates by their title or identifier.

sort: string (default: -last_modified)

The order of the returned templates.

One of: last_modified, -last_modified, created_at, -created_at, title, -title, identifier, -identifier.

Responses

200 - OK

Return a paginated array of templates.

POST

POST /api/v1/groups	Create a new group.
POST /api/v1/groups/{id}/members	Add a member to the group specified by the given ID.
POST /api/v1/groups/{id}/purge	Purge the deleted group specified by the given ID.
POST /api/v1/groups/{id}/restore	Restore the deleted group specified by the given ID.

POST /api/v1/groups

Create a new group.

Required scopes

group.create

Request body (JSON object)

The metadata of the new group.

identifier: string (required)

title: string (required)

description: string

visibility: string

Responses

201 - Created

Return the new group.

409 - Conflict

A conflict occured while trying to create the group.

POST /api/v1/groups/{id}/members

Add a member to the group specified by the given ID.

Required scopes

group.members

Path parameters

id: integer

Request body (JSON object)

The member and corresponding role to add.

role: object (required)

name: string (required)

user: object (required)

id: integer (required)

Responses

201 - Created

Member successfully added to group.

409 - Conflict

Member already exists.

POST /api/v1/groups/{id}/purge

Purge the deleted group specified by the given ID.

Will remove the group permanently. Only the creator of a group can purge it.

Required scopes

misc.manage_trash

Path parameters

id: integer

Responses

204 - No Content

Group purged successfully.

POST /api/v1/groups/{id}/restore

Restore the deleted group specified by the given ID.

Only the creator of a group can restore it.

Required scopes

misc.manage_trash

Path parameters

id: integer

Responses

200 - OK

Return the restored group.

PATCH

PATCH /api/v1/groups/{group_id}/members/{user_id}	Change a member’s role of a group.
PATCH /api/v1/groups/{id}	Update the group specified by the given ID.

PATCH /api/v1/groups/{group_id}/members/{user_id}

Change a member’s role of a group.

Will change the role of the member specified by the given user ID of the group specified by the given group ID.

Required scopes

group.members

Path parameters

group_id: integer

user_id: integer

Request body (JSON object)

The new member.

name: string (required)

Responses

204 - No Content

Member's role successfully changed.

409 - Conflict

When trying to change the creator's role or a conflict occured while trying to change the role.

PATCH /api/v1/groups/{id}

Update the group specified by the given ID.

Required scopes

group.update

Path parameters

id: integer

Request body (JSON object)

The new metadata of the group.

description: string

identifier: string

title: string

visibility: string

Responses

200 - OK

Return the updated group.

409 - Conflict

A conflict occured while trying to update the group.

DELETE

DELETE /api/v1/groups/{group_id}/members/{user_id}	Remove a member from a group.
DELETE /api/v1/groups/{id}	Mark the group specified by the given ID as deleted.

DELETE /api/v1/groups/{group_id}/members/{user_id}

Remove a member from a group.

Will remove the member specified by the given user ID from the group specified by the given group ID.

Required scopes

group.members

Path parameters

group_id: integer

user_id: integer

Responses

204 - No Content

Member successfully removed from group.

409 - Conflict

When trying to remove the creator.

DELETE /api/v1/groups/{id}

Mark the group specified by the given ID as deleted.

Until being removed automatically, a deleted group may be restored or purged using the endpoints POST /api/v1/groups/{id}/restore or POST /api/v1/groups/{id}/purge, respectively.

Required scopes

group.delete

Path parameters

id: integer

Responses

204 - No Content

Group successfully marked as deleted.

Miscellaneous

The following subsections describe all miscellaneous endpoints, grouped by HTTP method. To get more detailed information about the contents of the requested/returned representation of resources, see also License, Role and Tag.

GET

GET /api/v1	Get all base API endpoints.
GET /api/v1/info	Get information about the Kadi instance.
GET /api/v1/licenses	Get available licenses.
GET /api/v1/roles	Get all possible roles and corresponding permissions/actions of all resources.
GET /api/v1/tags	Get tags of resources the current user can access.
GET /api/v1/trash	Get deleted resources the current user created.

GET /api/v1

Get all base API endpoints.

Responses

200 - OK

Return the API endpoints.

GET /api/v1/info

Get information about the Kadi instance.

Responses

200 - OK

Return the information about the Kadi instance.

GET /api/v1/licenses

Get available licenses.

Query parameters

page: integer (default: 1)

The current result page.

Minimum: 1

per_page: integer (default: 10)

Number of results per page.

Minimum: 1

Maximum: 100

filter: string

A query to filter the licenses by their title or name.

Responses

200 - OK

Return a paginated array of licenses, sorted by title in ascending order.

GET /api/v1/roles

Get all possible roles and corresponding permissions/actions of all resources.

Responses

200 - OK

Return the resource roles and permissions.

GET /api/v1/tags

Get tags of resources the current user can access.

Query parameters

page: integer (default: 1)

The current result page.

Minimum: 1

per_page: integer (default: 10)

Number of results per page.

Minimum: 1

Maximum: 100

filter: string

A query to filter the tags by their name.

type: string

A resource type to limit the tags to.

One of: record, collection.

Responses

200 - OK

Return a paginated array of tags, sorted by name in ascending order.

GET /api/v1/trash

Get deleted resources the current user created.

Only the id and identifier of the resources are returned. Additionally, each resource contains its resource type (type), its deletion date (deleted_at) as well as endpoints to restore (_actions.restore) or purge (_actions.purge) the resource.

Required scopes

misc.manage_trash

Query parameters

page: integer (default: 1)

The current result page.

Minimum: 1

per_page: integer (default: 10)

Number of results per page.

Minimum: 1

Maximum: 100

filter: string

A query to filter the deleted resources by their identifier.

Responses

200 - OK

Return a paginated array of deleted resources, sorted by deletion date in descending order.