# Build with the Templates API

The Templates API manages the configuration templates that Live API resources depend on for encoding, composition, and stream conditioning. Templates are versioned: each upload creates a new version, and the most recent version is always tagged `latest`.

## API overview

<table>
  <thead>
    <tr>
      <th>Detail</th>
      <th>Value</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Base path</td>
      <td><code>/api/v1/projects/{project_name}/templating/</code></td>
    </tr>
    <tr>
      <td>Scope</td>
      <td>Project</td>
    </tr>
    <tr>
      <td>Reference</td>
      <td><a href="/api-reference/templates-api">Templates API reference</a></td>
    </tr>
  </tbody>
</table>

Every endpoint the Templates API has, in full:

<table>
  <thead>
    <tr>
      <th>Endpoint</th>
      <th>What it does</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><code>GET /templating/types</code></td>
      <td>Lists the config types your project supports</td>
    </tr>
    <tr>
      <td><code>GET /templating/configs</code>, <code>GET /templating/configs/{config_type}</code></td>
      <td>List your own configs, across all types or filtered to one</td>
    </tr>
    <tr>
      <td><code>GET /templating/configs/{config_type}/{name}</code></td>
      <td>Read the latest version of one config</td>
    </tr>
    <tr>
      <td><code>PUT /templating/configs/{config_type}/{name}</code></td>
      <td>Create a config, or a new version of one that already exists</td>
    </tr>
    <tr>
      <td><code>DELETE /templating/configs/{config_type}/{name}</code></td>
      <td>Delete a config and every version of it</td>
    </tr>
    <tr>
      <td><code>GET /templating/configs/{config_type}/{name}/versions</code></td>
      <td>List every version of a config</td>
    </tr>
    <tr>
      <td><code>GET /templating/configs/{config_type}/{name}/versions/{version}</code></td>
      <td>Read one specific version, by hash or tag</td>
    </tr>
    <tr>
      <td><code>DELETE /templating/configs/{config_type}/{name}/versions/{version}</code></td>
      <td>Delete one specific version</td>
    </tr>
    <tr>
      <td><code>GET /templating/presets</code>, <code>GET /templating/presets/{config_type}</code></td>
      <td>List MediaKind's presets, across all types or filtered to one</td>
    </tr>
    <tr>
      <td><code>GET /templating/presets/{config_type}/{name}</code></td>
      <td>Read one specific preset</td>
    </tr>
  </tbody>
</table>

That's the complete list. Presets have no PUT, POST, or DELETE anywhere, everything writable lives under `/configs`.

## How templates connect to live resources

### Reference a config

A template is referenced by name and version in a Live API resource's transform spec. For example, an `encodingLive` template is required by every `LiveChannel`, `LiveEvent`, `StaticMultiviewChannel`, and `StaticMultiviewEvent`. A `multiviewComposing` template is optional but provides a way to separate composition layout from encoding settings in multiview workflows.

Reference a template from a live resource like this:

```json
"encodingLive": {
  "configRef": {
    "name": "my-encoding-template",
    "version": "latest"
  }
}
```

Use `"version": "latest"` to always reference the most recently uploaded version. Pin to a specific version hash when you need stable, reproducible deployments.

### Start from a preset

A live resource's `configRef` always points at a **config**, the template you create and own. It never points at a **preset**, a separate, read-only, MediaKind-managed starting point you can optionally copy into a config. See [Configs and presets](/mkio/api-guides/how-to/templates/manage-templates#configs-and-presets) for how the two relate.

Use this sequence for a preset-based Live API workflow:

1. List the presets available to the project.
2. Create a customer config from the selected preset.
3. Retrieve the created config and copy its input or output pin names.
4. Reference the customer config from the Live API resource.

A Live API resource cannot reference the preset directly. For production, use a version hash instead of the mutable `latest` tag when the broadcast must use reproducible configuration.

### Customize a live resource

Alongside `configRef`, a live resource can set **`configValues`**, named values for any parameters the template declares, and **`configOverrides`**, JSON Patch operations against the template's content directly.

Prefer `configValues` where the template supports it: it's checked against parameters the template author explicitly declared, while `configOverrides` can touch any path and requires knowing the template's internal structure in detail. See [Set per-instance parameter values](/mkio/api-guides/how-to/live/manage-live#set-per-instance-parameter-values) and [Declare parameters on a config](/mkio/api-guides/how-to/templates/manage-templates#declare-parameters-on-a-config).

## Template types

<table>
  <thead>
    <tr>
      <th>Config type</th>
      <th>Purpose</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><code>encodingLive</code></td>
      <td>Live encoding configuration. Required by <code>liveChannels</code>, <code>liveEvents</code>, <code>staticMultiviewChannels</code>, <code>staticMultiviewEvents</code>.</td>
    </tr>
    <tr>
      <td><code>multiviewComposing</code></td>
      <td>Composition layout, optional on <code>staticMultiviewChannels</code> and <code>staticMultiviewEvents</code>.</td>
    </tr>
    <tr>
      <td><code>streamConditioning</code></td>
      <td>Optional stream conditioning settings, usable on any of the four resource types.</td>
    </tr>
  </tbody>
</table>

Call the types endpoint for the full list of types supported by your project. It is the source of truth, since types can be added over time.

`config_type` is a string path parameter. Choose a type returned by `GET /api/v1/projects/{project_name}/templating/types` and supported by the resource you plan to create. The [Live API reference](/api-reference/live-api) defines the four resource transforms and their accepted config types.

## Guides

[Manage templates](/mkio/api-guides/how-to/templates/manage-templates)

Create, version, tag, delete, and reference configuration templates. Use presets as a starting point.