Create a template (deprecated blocking convenience)

import requests

url = "https://api.13-215-85-171.sslip.io/v1/templates"

payload = {}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "id": "<string>",
  "name": "<string>",
  "description": "<string>",
  "builtin": true,
  "canonical_ref": "<string>",
  "namespace_slug": "<string>",
  "tags": [
    "<string>"
  ],
  "default_tag": "<string>",
  "runtime_defaults": {
    "default_env_keys": [
      "<string>"
    ],
    "start_cmd": "<string>",
    "default_user": "<string>",
    "default_workdir": "<string>",
    "readiness": {
      "kind": "tcp",
      "port": 3000,
      "timeout_secs": 30,
      "interval_ms": 500,
      "startup_grace_secs": 2
    }
  }
}

Templates

Create a template (deprecated blocking convenience)

deprecated

Legacy blocking template build convenience. This endpoint waits for the build to complete and returns the final template artifact. Prefer POST /v1/templates/build for streaming structured build logs or POST /v1/templates/builds for background builds plus polling. Terminal template failures preserve canonical template-facing codes: file_upload_error for build-context blob/preflight failures and build_error for accepted builds that fail during prepare, build, readiness, snapshot, or finalize.

POST

/

v1

/

templates

Create a template (deprecated blocking convenience)

import requests

url = "https://api.13-215-85-171.sslip.io/v1/templates"

payload = {}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "id": "<string>",
  "name": "<string>",
  "description": "<string>",
  "builtin": true,
  "canonical_ref": "<string>",
  "namespace_slug": "<string>",
  "tags": [
    "<string>"
  ],
  "default_tag": "<string>",
  "runtime_defaults": {
    "default_env_keys": [
      "<string>"
    ],
    "start_cmd": "<string>",
    "default_user": "<string>",
    "default_workdir": "<string>",
    "readiness": {
      "kind": "tcp",
      "port": 3000,
      "timeout_secs": 30,
      "interval_ms": 500,
      "startup_grace_secs": 2
    }
  }
}

Authorizations

Authorization

string

header

required

API key passed as Bearer token

Body

application/json

name

string

Template name (falls back to alias, then auto-generated)

dockerfile

string

Inline Dockerfile content

base_image

string

Base OCI image reference imported directly on the Firecracker path (for example ubuntu:22.04). The importer currently supports raw tar, gzip, and zstd layer media types; regular files, directories, symlinks, and hard links; and Linux OCI User values in user, uid, user:group, user:gid, uid:group, or uid:gid form. OCI special files such as sockets, FIFOs, block devices, and character devices are rejected. For image indexes, the importer prefers exact Firecracker-compatible Linux variants for the current host architecture (amd64/v1 or arm64/v8 / arm64/v8.0) and falls back to a variantless Linux manifest when present; manifests with os.version or non-empty os.features are rejected. Guest boot recreates /dev, /dev/pts, /dev/shm, /proc, and /sys through nullspace-init, so those do not need to come from imported OCI layers.

alias

string

Alternative name field used by SDK builders

tags

string[]

Tags assigned to the built artifact. Omit this field to use ["default"]; explicit empty arrays are invalid.

steps

object[]

Declarative builder steps converted to a Dockerfile server-side

Show child attributes

build_envs

object

Environment variables available during template build only

Show child attributes

start_cmd

string

Firecracker template start command executed during template build before snapshotting; sandboxes later restore the snapshotted running state instead of rerunning this command, and create-time env injection is not visible to it

build_context

object

Explicit local build context used to satisfy COPY/ADD sources during template builds

Show child attributes

build_config

object

Optional build VM configuration (vCPUs, memory, internet access)

Show child attributes

build_backend

enum<string>

Optional template build backend. Dockerfile builds default to BuildKit; declarative and external OCI import inputs use the native backend unless explicitly supported otherwise. Dockerfile input with native is rejected.

Available options:

native,

buildkit

dockerfile_path

string

Relative Dockerfile path inside the uploaded build context for BuildKit builds.

build_args

object

Safe-to-persist Dockerfile build arguments for BuildKit builds.

Show child attributes

build_target

string

Optional Dockerfile target stage for BuildKit builds.

runtime_config

object

Firecracker-only runtime defaults baked into the built template

Show child attributes

base_image_auth

object

Optional credentials for authenticated external OCI base-image imports. Applies to explicit base_image imports and Dockerfile builds that resolve to exactly one external non-template FROM image. Authenticated Dockerfile-backed imports currently reject variable-based FROM, alias-based imported stages, and multiple external registry hosts.

Option 1
Option 2
Option 3

Show child attributes

registry_auth

object[]

Optional per-registry request-time credentials for BuildKit Dockerfile pulls. Each registry must match a registry host used by the Dockerfile or base image. Secret values are forwarded only to the build worker and are not stored in durable build records.

Show child attributes

build_secrets

object[]

Optional request-time BuildKit secrets exposed to Dockerfile RUN --mount=type=secret instructions. Supported only by the BuildKit backend. Values are forwarded only to the build worker and are not persisted in durable build records, cache keys, or context manifests.

Show child attributes

skip_cache

boolean

Firecracker-only whole-build cache bypass

claim_token

string

Optional reserved template-name claim token

Response

Template created

id

string

required

name

string

required

description

string

required

builtin

boolean

required

canonical_ref

string

required

namespace_slug

string

required

visibility

enum<string>

required

Available options:

private,

public

tags

string[]

default_tag

string

runtime_defaults

object

Effective runtime defaults retained for a built template. Environment values are intentionally omitted; only keys are exposed.

Show child attributes

List templates accessible to the caller Get template details