Start a background template build

import requests

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

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

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

print(response.text)

{
  "build_id": "<string>",
  "template_id": "<string>",
  "name": "<string>",
  "tags": [
    "<string>"
  ],
  "canonical_ref": "<string>",
  "namespace_slug": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "source_digest": "<string>",
  "context_digest": "<string>",
  "dockerfile_digest": "<string>",
  "build_config": {
    "vcpus": 123,
    "memory_mib": 123,
    "internet_access": true,
    "disk_mb": 513
  },
  "triggered_by": "<string>",
  "queued_at": "2023-11-07T05:31:56Z",
  "started_at": "2023-11-07T05:31:56Z",
  "finished_at": "2023-11-07T05:31:56Z",
  "duration_ms": 123,
  "failure_phase": "<string>",
  "cache_summary": {
    "final_artifact_hits": 123,
    "final_artifact_misses": 123,
    "final_artifact_bypasses": 123,
    "final_artifact_stores": 123,
    "layer_hits": 123,
    "layer_misses": 123,
    "layer_bypasses": 123,
    "layer_stores": 123,
    "file_blob_hits": 123,
    "file_blob_misses": 123,
    "file_blob_bypasses": 123,
    "file_blob_stores": 123
  },
  "artifact_availability": {
    "reason": "<string>"
  },
  "promotability": {
    "promotable": true,
    "reason": "<string>"
  },
  "retention_expires_at": "2023-11-07T05:31:56Z",
  "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
    }
  },
  "oci_metadata": {
    "labels": {},
    "exposed_ports": [
      "<string>"
    ],
    "volumes": [
      "<string>"
    ],
    "healthcheck": {
      "test": [
        "<string>"
      ],
      "interval_ns": 123,
      "timeout_ns": 123,
      "start_period_ns": 123,
      "retries": 123,
      "mapped_readiness": {
        "kind": "tcp",
        "port": 3000,
        "timeout_secs": 30,
        "interval_ms": 500,
        "startup_grace_secs": 2
      }
    }
  },
  "artifact_ids": [
    "<string>"
  ],
  "retry_of_build_id": "<string>",
  "original_build_id": "<string>",
  "cancel_requested_at": "2023-11-07T05:31:56Z",
  "cancel_requested_by": "<string>",
  "cancellation_reason": "<string>",
  "error": "<string>",
  "error_detail": {
    "message": "<string>",
    "retryable": true,
    "suggested_action": "<string>",
    "step_index": 123,
    "attempt": 123,
    "max_attempts": 123,
    "cache_subject": "<string>",
    "build_id": "<string>",
    "request_id": "<string>",
    "details": {}
  }
}

Templates

Start a background template build

Firecracker-only endpoint. Starts a template build and returns the canonical build handle for later polling. For owned custom-template builds, the returned build_id is scoped to the authenticated caller that created it; reconnect and polling must use the same caller context and deployment/base URL. Accepted builds later surface terminal failures through GET /v1/templates/builds/{build_id} using status=error, legacy error, and structured error_detail.

POST

templates

builds

import requests

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

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

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

print(response.text)

{
  "build_id": "<string>",
  "template_id": "<string>",
  "name": "<string>",
  "tags": [
    "<string>"
  ],
  "canonical_ref": "<string>",
  "namespace_slug": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "source_digest": "<string>",
  "context_digest": "<string>",
  "dockerfile_digest": "<string>",
  "build_config": {
    "vcpus": 123,
    "memory_mib": 123,
    "internet_access": true,
    "disk_mb": 513
  },
  "triggered_by": "<string>",
  "queued_at": "2023-11-07T05:31:56Z",
  "started_at": "2023-11-07T05:31:56Z",
  "finished_at": "2023-11-07T05:31:56Z",
  "duration_ms": 123,
  "failure_phase": "<string>",
  "cache_summary": {
    "final_artifact_hits": 123,
    "final_artifact_misses": 123,
    "final_artifact_bypasses": 123,
    "final_artifact_stores": 123,
    "layer_hits": 123,
    "layer_misses": 123,
    "layer_bypasses": 123,
    "layer_stores": 123,
    "file_blob_hits": 123,
    "file_blob_misses": 123,
    "file_blob_bypasses": 123,
    "file_blob_stores": 123
  },
  "artifact_availability": {
    "reason": "<string>"
  },
  "promotability": {
    "promotable": true,
    "reason": "<string>"
  },
  "retention_expires_at": "2023-11-07T05:31:56Z",
  "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
    }
  },
  "oci_metadata": {
    "labels": {},
    "exposed_ports": [
      "<string>"
    ],
    "volumes": [
      "<string>"
    ],
    "healthcheck": {
      "test": [
        "<string>"
      ],
      "interval_ns": 123,
      "timeout_ns": 123,
      "start_period_ns": 123,
      "retries": 123,
      "mapped_readiness": {
        "kind": "tcp",
        "port": 3000,
        "timeout_secs": 30,
        "interval_ms": 500,
        "startup_grace_secs": 2
      }
    }
  },
  "artifact_ids": [
    "<string>"
  ],
  "retry_of_build_id": "<string>",
  "original_build_id": "<string>",
  "cancel_requested_at": "2023-11-07T05:31:56Z",
  "cancel_requested_by": "<string>",
  "cancellation_reason": "<string>",
  "error": "<string>",
  "error_detail": {
    "message": "<string>",
    "retryable": true,
    "suggested_action": "<string>",
    "step_index": 123,
    "attempt": 123,
    "max_attempts": 123,
    "cache_subject": "<string>",
    "build_id": "<string>",
    "request_id": "<string>",
    "details": {}
  }
}

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

Response

Build accepted

build_id

string

required

template_id

string

required

name

string

required