Templates

To get more detailed information about some the contents of the requested/returned representation of resources related to templates, see also Template (including Template.data) and Revision. For possible role values, see also the Miscellaneous endpoints.

GET

GET /api/templates	Search and filter for templates.
GET /api/templates/(int:id)	Get the template specified by the given id.
GET /api/templates/(int:id)/export/(export_type)	Export the template specified by the given id.
GET /api/templates/(int:id)/revisions	Get the revisions of the template specified by the given id.
GET /api/templates/(int:id)/roles/groups	Get the group roles of the template specified by the given id.
GET /api/templates/(int:id)/roles/users	Get the user roles of the template specified by the given id.
GET /api/templates/(int:template_id)/revisions/(int:revision_id)	Get a template revision.
GET /api/templates/identifier/(identifier:identifier)	Get the template specified by the given identifier.

GET /api/templates

Search and filter for templates.

Versions: v1 (latest)

Required scopes: template.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 templates with.

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

user - 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 - A type value to filter the templates with. One of record or extras.

Status codes

200 (OK) - Return a paginated list of templates.

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

Get the template specified by the given id.

Versions: v1 (latest)

Required scopes: template.read

Status codes

200 (OK) - Return the template.

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

Export the template specified by the given id.

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

Versions: v1 (latest)

Required scopes: template.read

Query parameters

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

Status codes

200 (OK) - Return the exported template data.

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

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

Versions: v1 (latest)

Required scopes: template.read

Query parameters

page - The current result page. (Default: 1)

per_page - Number of results per page, limited to a maximum of 100. (Default: 10)

Status codes

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

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

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

Versions: v1 (latest)

Required scopes: template.read and group.read

Query parameters

page - The current result page. (Default: 1)

per_page - Number of results per page, limited to a maximum of 100. (Default: 10)

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

Status codes

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

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

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

Versions: v1 (latest)

Required scopes: template.read and user.read

Query parameters

page - The current result page. (Default: 1)

per_page - Number of results per page, limited to a maximum of 100. (Default: 10)

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

exclude - User IDs to exclude. (Can be specified more than once.)

Status codes

200 (OK) - Return a paginated list of user roles, sorted by role name and then by user ID in ascending order. The creator will always be listed first.

GET /api/templates/(int: template_id)/revisions/(int: 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.

Versions: v1 (latest)

Required scopes: template.read

Query parameters

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

Status codes

200 (OK) - Return the revision.

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

Get the template specified by the given identifier.

Versions: v1 (latest)

Required scopes: template.read

Status codes

200 (OK) - Return the template.

POST

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

POST /api/templates

Create a new template.

Versions: v1 (latest)

Required scopes: template.create

Request JSON object

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

data (Required) - Any

identifier (Required) - String

title (Required) - String

type (Required) - String

description - String

visibility - String

Status codes

201 (Created) - Return the new template.

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

Purge a deleted template specified by the given id.

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

Versions: v1 (latest)

Required scopes: misc.manage_trash

Status codes

204 (No Content) - Template purged successfully.

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

Restore the deleted template specified by the given id.

Only the creator of a template can restore it.

Versions: v1 (latest)

Required scopes: misc.manage_trash

Status codes

200 (OK) - Return the restored template.

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

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

Versions: v1 (latest)

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

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

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

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

Versions: v1 (latest)

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

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

PATCH

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

PATCH /api/templates/(int: id)

Update the template specified by the given id.

Versions: v1 (latest)

Required scopes: template.update

Request JSON object

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

data - Any

description - String

identifier - String

title - String

visibility - String

Status codes

200 (OK) - Return the updated template.

PATCH /api/templates/(int: template_id)/roles/groups/(int: 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.

Versions: v1 (latest)

Required scopes: template.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/templates/(int: template_id)/roles/users/(int: 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.

Versions: v1 (latest)

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

DELETE

DELETE /api/templates/(int:id)	Mark the template specified by the given id as deleted.
DELETE /api/templates/(int:template_id)/roles/groups/(int:group_id)	Remove a group role from a template.
DELETE /api/templates/(int:template_id)/roles/users/(int:user_id)	Remove a user role from a template.

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

Mark the template specified by the given id as deleted.

Versions: v1 (latest)

Required scopes: template.delete

Status codes

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

DELETE /api/templates/(int: template_id)/roles/groups/(int: 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.

Versions: v1 (latest)

Required scopes: template.permissions

Status codes

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

DELETE /api/templates/(int: template_id)/roles/users/(int: 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.

Versions: v1 (latest)

Required scopes: template.permissions

Status codes

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

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