Skip to content
Docs

Build with the Templates API

Use the Templates API to create, version, and manage configuration templates used by Live API resources in MK.IO.

Updated View as Markdown

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

Detail Value
Base path /api/v1/projects/{project_name}/templating/
Scope Project
Reference Templates API reference

Every endpoint the Templates API has, in full:

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

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:

"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 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 and Declare parameters on a config.

Template types

Config type Purpose
encodingLive Live encoding configuration. Required by liveChannels, liveEvents, staticMultiviewChannels, staticMultiviewEvents.
multiviewComposing Composition layout, optional on staticMultiviewChannels and staticMultiviewEvents.
streamConditioning Optional stream conditioning settings, usable on any of the four resource types.

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 defines the four resource transforms and their accepted config types.

Guides

Manage templates

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

Edit this page
Navigation