Templates

Manage templates, their versions and release channels (templates as code), and check data against them.

📄️List templates

The workspace's templates that are not archived, most recently changed first, a page at a time. Needs `template:read`.

📄️Create a template

Creates a template with its first version, a draft unless `publish` is `true`. Requires the

📄️Get a template

One template that is not archived, with the numbers of its published and its latest version. Needs `template:read`.

📄️Update template metadata

Changes the name, description and tags; fields left out stay as they are, and at least one is needed (400 `invalid_request` otherwise). The slug, kind and engine cannot change, and a body that names only them counts as empty. Needs `template:write`.

📄️Archive a template

Archives the template: it leaves `GET /templates`, the Templates API answers 404 for it, and

📄️List versions

Every version of the template, newest first, all of them in one answer and without their content (`html`, `css`, `head`, settings, data, partials); get one version for that. Needs `template:read`.

📄️Create a draft version

Saves a new version with the next number, as a draft. With `publish: true` it is published

📄️Get a version with its files

`which` is `published`, `latest` (the newest version, whatever its status; usually the draft the editor works on, and `draft` means the same), a version number or the name of a release channel (its main version). The CLI pulls `latest` with `--draft` and `published` otherwise. A `which` that is none of these answers 400, a channel the template does not have 404 `channel_not_found`. Needs `template:read`.

📄️Download the file of a Word or PowerPoint template

`which` as for getting a version. Requires `template:read`. The file is served only here, never from the CDN, as a download named `<slug>-v<number>.docx` or `.pptx`. A template of another kind answers 404 `not_found`.

📄️Publish a version

Makes this version the one served by the API; the same as moving the `published` channel. The previously published version is archived and becomes the channel's `previous_version`. When both versions store a data schema and the new one breaks callers of the old one (a new required field, a narrower type, a removed enum value), the request answers 409 `schema_breaking_change` unless it sends `allow_breaking: true`. Renders pick the version up within a minute. Needs `template:write`.

📄️List release channels

`published` first, then the named channels, with the renders of the last 24 hours per version and the plan's allowance (`channels` per template besides published, `null` for unlimited, and whether canaries are allowed). Needs `template:read`.

📄️Create or move a channel

Points the channel at `version`, optionally with a `canary` that receives `percent` of its renders (Pro and above). On `published` this publishes. The schema check of publishing applies to the main and the canary version. Starter allows 2 channels per template besides published, Pro and Business 10; the Free plan renders the published version only. A plan without channels or canaries, or one more channel than the plan holds, answers 403 `forbidden` with the `feature`. Renders pick up the move within a minute. Needs `template:write`.

📄️Delete a channel

Not for `published` (400). Refused with 409 `channel_in_use` while renders of the last hour used the channel, unless `force=true`. Renders that still name the channel answer 404 `channel_not_found` once it is gone. Needs `template:write`.

📄️Promote the canary

The canary version becomes the channel's main version and the canary is cleared; the old main version becomes `previous_version`. A channel without a canary answers 400 `invalid_request`. The schema check of publishing applies (409 `schema_breaking_change` unless `allow_breaking`). Needs `template:write`.

📄️Roll a channel back

Returns the channel to `previous_version` and clears its canary. A second rollback returns to where the first started; a channel without a previous version answers 400 `invalid_request`. The schema check of publishing applies (409 `schema_breaking_change` unless `allow_breaking`). Needs `template:write`.

📄️Get the data schema

JSON Schema (draft 2020-12) describing the `data` object the template expects: the one stored with the published (or latest) version, or with the version `version` names, else one inferred from its sample data the way the editor does; 404 when the version has neither. With `format=make` the schema comes back as Make parameter definitions (one `data` collection, plus a `version` select listing the release channels when the template has any besides `published`), which the Make app loads as dynamic fields; a template with neither schema nor sample data then gets a single JSON field instead of a 404. With `format=swagger` it comes back as `{ 'schema': … }` in the OpenAPI 2.0 dialect (one type per property, no `nullable` or `oneOf`, a label in `x-ms-summary`), which the Power Platform connector loads as dynamic fields; without schema or sample data that is an object without properties. Needs `template:read`.

📄️Validate a template with data

Checks a template version and data without rendering: syntax and analysis of the body, header and footer, includes without a stored partial, errors that only happen when the template runs with the data, and the data against the stored data schema (when the version stores one). For Word and PowerPoint templates the tags of the stored file are checked instead of HTML, and their diagnostics name the part and paragraph. Free; not metered and not rate limited. Problems with the template are diagnostics in a 200 response, not errors. Needs `template:read`.