Skip to main content
POST
/
v1
/
templates
/
validate
Validate a template build request without starting a build
import requests

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

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

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

print(response.text)
{
  "valid": true,
  "errors": [
    {
      "code": "<string>",
      "message": "<string>",
      "phase": "<string>"
    }
  ],
  "warnings": [
    "<string>"
  ]
}

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

​
build_envs
object

Environment variables available during template build only

​
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

​
build_config
object

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

​
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.

​
build_target
string

Optional Dockerfile target stage for BuildKit builds.

​
runtime_config
object

Firecracker-only runtime defaults baked into the built template

​
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.

​
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.

​
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.

​
skip_cache
boolean

Firecracker-only whole-build cache bypass

​
claim_token
string

Optional reserved template-name claim token

Response

Validation result

​
valid
boolean
required
​
errors
object[]
required
​
warnings
string[]
required