Templates

To get more detailed information about the contents of the requested/returned representation of resources related to templates, see also Template, especially 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 revisions of the template specified by the given id.

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

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

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

Get 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. Supports exact matches when surrounded by double quotes.

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

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

  • 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 array 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 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 array of revisions, sorted by revision timestamp in descending order.

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

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

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

Get 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 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/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 the 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) - Object | Array [Object]

  • 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 the 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 - Object | Array [Object]

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