Templates

Templates by name, each with its versions in creation order. Not paginated.

The build state, the reason a build failed, the number of layers and the tail of the build log.

Starts building a new, immutable version from steps and returns at once with state: building (202). Poll getTemplateVersion until the state is ready or failed. The template is created with its first version. A version that already exists returns 409 version_exists, whatever the body; pick a new version instead.

The build runs in a temporary environment on top of from (another ready version of yours) or the platform's default runtime: each run step runs as root inside the runtime with /bin/sh -c, and the files and packages it leaves behind become a layer. Egress during the build is limited to common package registries (Debian, PyPI, npm, crates.io, GitHub releases) plus your developer-level allowlist. A step may run for up to 30 minutes and a whole build for up to an hour. While it runs, the temporary environment appears in your environment list with end_user_id template-build:<name>:<version>; it is destroyed when the build ends. A version with the same base, steps and start as one you already built reuses that build's layer instead of running the steps again. Files written by copy steps are owned by root; add a run step with chown if the agent must write to them. The build log records every command, so do not put secrets in steps.

from must be ready; a base that is still building or failed returns 409 template_not_ready, and one that does not exist returns 404. The request body is limited to 8 MiB.

A version that is still building returns 409 template_building. A version used by an environment that has not been destroyed, or used as the base (from) of another version, returns 409 template_in_use.