> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ns.rocks/llms.txt
> Use this file to discover all available pages before exploring further.

# Validate a template build request without starting a build

> Parses and normalizes a template build request, validates refs and build context descriptors, checks backend-compatible inputs, and returns structured validation errors without selecting a build executor.




## OpenAPI

````yaml /openapi.yaml post /v1/templates/validate
openapi: 3.1.0
info:
  title: Nullspace API
  version: 0.1.0
  description: |
    Cloud machine platform for AI agents. Create on-demand microVMs,
    execute commands, manage files, automate desktop environments,
    and stream output over WebSocket.
  license:
    name: Apache-2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
  - url: https://api.13-215-85-171.sslip.io
    description: Private beta
  - url: https://nullspace.example
    description: Self-hosted single-host owned-domain
  - url: http://localhost
    description: Self-hosted single-host localhost/no-domain via Caddy
  - url: http://localhost:3000
    description: Local development direct API
security:
  - bearerAuth: []
tags:
  - name: Health
    description: Public process-liveness check (no auth required)
  - name: Machines
    description: Machine lifecycle, execution, and process management
  - name: Files
    description: Filesystem operations within a machine
  - name: Git
    description: First-class structured git operations within a machine
  - name: Desktop
    description: Desktop automation (mouse, keyboard, screenshots)
  - name: Recording
    description: Screen recording management
  - name: PTY
    description: Pseudo-terminal session management
  - name: Templates
    description: Machine template management
  - name: Agent Deployments
    description: Named, versioned agent deployment control plane
  - name: Volumes
    description: Persistent volume control plane and attached volume actions
  - name: WebSocket
    description: Streaming execution and PTY over WebSocket
  - name: Monitor
    description: In-repo WebSocket stream for machine health, metrics, and process updates
  - name: API Keys
    description: Runtime API key metadata and dormant self-serve key management
  - name: Account
    description: Dormant Supabase-session account profile, export, and deletion routes
  - name: Admin
    description: Supabase-session operator console APIs for account support
  - name: Auth
    description: Dormant self-serve Auth proxy routes gated by deployment config
  - name: Code
    description: Stateful code execution via Jupyter kernels (Code Interpreter)
  - name: Internal Operations
    description: Operator-only internal API surfaces; not part of the public SDK contract
paths:
  /v1/templates/validate:
    post:
      tags:
        - Templates
      summary: Validate a template build request without starting a build
      description: >
        Parses and normalizes a template build request, validates refs and build
        context descriptors, checks backend-compatible inputs, and returns
        structured validation errors without selecting a build executor.
      operationId: validateTemplateBuild
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTemplateRequest'
      responses:
        '200':
          description: Validation result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateBuildValidationResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '503':
          $ref: '#/components/responses/FeatureUnavailable'
components:
  schemas:
    CreateTemplateRequest:
      type: object
      properties:
        name:
          type: string
          description: Template name (falls back to alias, then auto-generated)
        dockerfile:
          type: string
          description: Inline Dockerfile content
        base_image:
          type: string
          description: >-
            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:
          type: string
          description: Alternative name field used by SDK builders
        tags:
          type: array
          items:
            type: string
          description: >-
            Tags assigned to the built artifact. Omit this field to use
            ["default"]; explicit empty arrays are invalid.
        steps:
          type: array
          items:
            $ref: '#/components/schemas/TemplateStep'
          description: Declarative builder steps converted to a Dockerfile server-side
        build_envs:
          type: object
          additionalProperties:
            type: string
          description: Environment variables available during template build only
        start_cmd:
          type: string
          description: >-
            Firecracker template start command executed during template build
            before snapshotting; machines later restore the snapshotted running
            state instead of rerunning this command, and create-time env
            injection is not visible to it
        build_context:
          $ref: '#/components/schemas/TemplateBuildContext'
          description: >-
            Explicit local build context used to satisfy COPY/ADD sources during
            template builds
        build_config:
          $ref: '#/components/schemas/TemplateBuildConfig'
          description: Optional build VM configuration (vCPUs, memory, internet access)
        build_backend:
          $ref: '#/components/schemas/TemplateBuildBackend'
          description: >-
            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.
        dockerfile_path:
          type: string
          description: >-
            Relative Dockerfile path inside the uploaded build context for
            BuildKit builds.
        build_args:
          type: object
          additionalProperties:
            type: string
          description: Safe-to-persist Dockerfile build arguments for BuildKit builds.
        build_target:
          type: string
          description: Optional Dockerfile target stage for BuildKit builds.
        runtime_config:
          $ref: '#/components/schemas/TemplateRuntimeConfig'
          description: Firecracker-only runtime defaults baked into the built template
        base_image_auth:
          $ref: '#/components/schemas/TemplateBaseImageAuth'
          description: >-
            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:
          type: array
          items:
            $ref: '#/components/schemas/TemplateRegistryAuth'
          description: >-
            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:
          type: array
          items:
            $ref: '#/components/schemas/TemplateBuildSecret'
          description: >-
            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:
          type: boolean
          description: Firecracker-only whole-build cache bypass
        claim_token:
          type: string
          description: Optional reserved template-name claim token
      example:
        name: tmpl-app
        base_image: ubuntu:22.04
        build_envs:
          APP_ENV: build
        steps:
          - action: copy
            sources:
              - builder-context/src/package.json
              - builder-context/src/package-lock.json
            dst: /workspace/
            user: app
            mode: '0644'
          - action: run
            command: npm ci
            user: app
          - action: git_clone
            url: https://github.com/acme/service.git
            path: /workspace/service
            branch: main
            depth: 1
          - action: npm_install
            packages:
              - tsx
            g: true
        runtime_config:
          default_user: app
          default_workdir: /workspace
          readiness:
            kind: tcp
            port: 3000
            timeout_secs: 30
            interval_ms: 500
            startup_grace_secs: 2
          default_envs:
            PORT: '3000'
        start_cmd: npm run dev
    TemplateBuildValidationResponse:
      type: object
      required:
        - valid
        - errors
        - warnings
      properties:
        valid:
          type: boolean
        errors:
          type: array
          items:
            $ref: '#/components/schemas/TemplateBuildValidationError'
        warnings:
          type: array
          items:
            type: string
    TemplateStep:
      oneOf:
        - $ref: '#/components/schemas/TemplateAptInstallStep'
        - $ref: '#/components/schemas/TemplatePipInstallStep'
        - $ref: '#/components/schemas/TemplateNpmInstallStep'
        - $ref: '#/components/schemas/TemplateBunInstallStep'
        - $ref: '#/components/schemas/TemplateRunStep'
        - $ref: '#/components/schemas/TemplateWorkdirStep'
        - $ref: '#/components/schemas/TemplateUserStep'
        - $ref: '#/components/schemas/TemplateCopyStep'
        - $ref: '#/components/schemas/TemplateCopyItemsStep'
        - $ref: '#/components/schemas/TemplateRemoveStep'
        - $ref: '#/components/schemas/TemplateRenameStep'
        - $ref: '#/components/schemas/TemplateMakeDirStep'
        - $ref: '#/components/schemas/TemplateMakeSymlinkStep'
        - $ref: '#/components/schemas/TemplateGitCloneStep'
        - $ref: '#/components/schemas/TemplateSkipCacheStep'
      discriminator:
        propertyName: action
        mapping:
          apt_install:
            $ref: '#/components/schemas/TemplateAptInstallStep'
          pip_install:
            $ref: '#/components/schemas/TemplatePipInstallStep'
          npm_install:
            $ref: '#/components/schemas/TemplateNpmInstallStep'
          bun_install:
            $ref: '#/components/schemas/TemplateBunInstallStep'
          run:
            $ref: '#/components/schemas/TemplateRunStep'
          workdir:
            $ref: '#/components/schemas/TemplateWorkdirStep'
          user:
            $ref: '#/components/schemas/TemplateUserStep'
          copy:
            $ref: '#/components/schemas/TemplateCopyStep'
          copy_items:
            $ref: '#/components/schemas/TemplateCopyItemsStep'
          remove:
            $ref: '#/components/schemas/TemplateRemoveStep'
          rename:
            $ref: '#/components/schemas/TemplateRenameStep'
          make_dir:
            $ref: '#/components/schemas/TemplateMakeDirStep'
          make_symlink:
            $ref: '#/components/schemas/TemplateMakeSymlinkStep'
          git_clone:
            $ref: '#/components/schemas/TemplateGitCloneStep'
          skip_cache:
            $ref: '#/components/schemas/TemplateSkipCacheStep'
    TemplateBuildContext:
      type: object
      required:
        - files
      properties:
        files:
          type: array
          items:
            $ref: '#/components/schemas/TemplateBuildContextFile'
    TemplateBuildConfig:
      type: object
      description: Build VM resource configuration
      properties:
        vcpus:
          type: integer
          description: Number of vCPUs for the build VM (default 1)
        memory_mib:
          type: integer
          description: Memory in MiB for the build VM (default 512)
        internet_access:
          type: boolean
          description: Whether the build VM has internet access (default true)
        disk_mb:
          type: integer
          minimum: 512
          description: >-
            Minimum rootfs size in MiB baked into the built template. The build
            VM's rootfs is grown to this size before its snapshot is captured,
            so every machine created from the template (cold, warm-pool, fork,
            resume) inherits the larger disk. Omit to use the default headroom.
    TemplateBuildBackend:
      type: string
      description: >-
        Template build backend. `native` is retained for declarative/OCI build
        requests and historical filters; Dockerfile build requests use
        `buildkit`.
      enum:
        - native
        - buildkit
    TemplateRuntimeConfig:
      type: object
      properties:
        default_user:
          type: string
        default_workdir:
          type: string
        default_envs:
          type: object
          additionalProperties:
            type: string
        readiness:
          $ref: '#/components/schemas/TemplateReadinessProbe'
          description: >-
            Readiness gate evaluated during template build before snapshotting;
            when start_cmd is present and readiness is omitted, Firecracker
            applies an implicit timeout probe of 20,000 ms
    TemplateBaseImageAuth:
      oneOf:
        - $ref: '#/components/schemas/TemplateBaseImageAuthBasic'
        - $ref: '#/components/schemas/TemplateBaseImageAuthGcpArtifactRegistry'
        - $ref: '#/components/schemas/TemplateBaseImageAuthAwsEcr'
      discriminator:
        propertyName: kind
        mapping:
          basic:
            $ref: '#/components/schemas/TemplateBaseImageAuthBasic'
          gcp_artifact_registry:
            $ref: '#/components/schemas/TemplateBaseImageAuthGcpArtifactRegistry'
          aws_ecr:
            $ref: '#/components/schemas/TemplateBaseImageAuthAwsEcr'
    TemplateRegistryAuth:
      type: object
      required:
        - registry
        - auth
      properties:
        registry:
          type: string
          description: Registry host such as `registry.example.com` or `docker.io`.
        auth:
          $ref: '#/components/schemas/TemplateBaseImageAuth'
      additionalProperties: false
    TemplateBuildSecret:
      type: object
      required:
        - id
        - value
      properties:
        id:
          type: string
          description: >-
            BuildKit secret ID used by Dockerfile `RUN
            --mount=type=secret,id=<id>` instructions. IDs may contain letters,
            numbers, `.`, `_`, and `-`.
        value:
          type: string
          description: >-
            Request-time secret value. The value is forwarded to the build
            worker as a temporary BuildKit secret file and is not stored.
        source:
          $ref: '#/components/schemas/TemplateBuildSecretSource'
      additionalProperties: false
    TemplateBuildValidationError:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
        message:
          type: string
        phase:
          type: string
    ErrorResponse:
      type: object
      required:
        - error
        - code
      properties:
        error:
          type: string
          description: Human-readable error message
        code:
          type: string
          description: Machine-readable error code
          enum:
            - invalid_request
            - machine_not_found
            - snapshot_not_found
            - template_not_found
            - template_build_not_found
            - template_name_claim_not_found
            - machine_not_ready
            - unauthorized
            - auth_failed
            - auth_locked
            - auth_proxy_error
            - auth_proxy_unavailable
            - invalid_auth_redirect
            - invalid_oauth_provider
            - captcha_required
            - captcha_failed
            - captcha_unavailable
            - disposable_email
            - signup_rate_limited
            - oauth_rate_limited
            - email_action_rate_limited
            - database_error
            - email_not_verified
            - account_deleted
            - operator_required
            - account_not_found
            - account_not_soft_deleted
            - account_hard_delete_active_resources
            - file_upload_error
            - build_error
            - exec_timeout
            - exec_failed
            - file_error
            - not_implemented
            - capacity_exceeded
            - QUOTA_EXCEEDED
            - feature_unavailable
            - snapshot_in_use
            - no_eligible_runtime_host
            - same_host_required
            - incompatible_snapshot
            - rebuild_required
            - rate_limit_exceeded
            - transition_in_progress
            - transition_conflict
            - agent_deployment_not_found
            - agent_deployment_version_not_found
            - agent_run_not_found
            - agent_service_instance_not_found
            - agent_deployment_name_conflict
            - agent_deployment_idempotency_mismatch
            - agent_deployment_invalid_config
            - agent_deployment_invalid_state
            - volume_beta_restriction
            - volume_invalid_mount_path
            - volume_overlapping_mounts
            - volume_backend_capability_unsupported
            - volume_quota_exceeded
            - volume_mount_credential_issue_failed
            - volume_backend_unavailable
            - volume_stale_revision
            - volume_busy
            - volume_read_only
            - volume_limit_exceeded
            - internal_error
        error_detail:
          $ref: '#/components/schemas/ErrorDetail'
        request_id:
          type: string
          description: Request correlation ID returned in the `x-request-id` header
        build_id:
          type: string
          description: Template build ID when the error is associated with a tracked build
    TemplateAptInstallStep:
      type: object
      required:
        - action
        - packages
      properties:
        action:
          type: string
          enum:
            - apt_install
        packages:
          type: array
          items:
            type: string
      additionalProperties: false
    TemplatePipInstallStep:
      type: object
      required:
        - action
        - packages
      properties:
        action:
          type: string
          enum:
            - pip_install
        packages:
          type: array
          items:
            type: string
        g:
          type: boolean
          description: >-
            Set to false to perform a user install instead of the default system
            install.
      additionalProperties: false
    TemplateNpmInstallStep:
      type: object
      required:
        - action
        - packages
      properties:
        action:
          type: string
          enum:
            - npm_install
        packages:
          type: array
          items:
            type: string
        g:
          type: boolean
          description: Set to true to install globally; defaults to local install behavior.
      additionalProperties: false
    TemplateBunInstallStep:
      type: object
      required:
        - action
        - packages
      properties:
        action:
          type: string
          enum:
            - bun_install
        packages:
          type: array
          items:
            type: string
        g:
          type: boolean
          description: Set to true to install globally; defaults to local install behavior.
      additionalProperties: false
    TemplateRunStep:
      type: object
      required:
        - action
        - command
      properties:
        action:
          type: string
          enum:
            - run
        command:
          type: string
        user:
          type: string
      additionalProperties: false
    TemplateWorkdirStep:
      type: object
      required:
        - action
        - path
      properties:
        action:
          type: string
          enum:
            - workdir
        path:
          type: string
      additionalProperties: false
    TemplateUserStep:
      type: object
      required:
        - action
        - user
      properties:
        action:
          type: string
          enum:
            - user
        user:
          type: string
      additionalProperties: false
    TemplateCopyStep:
      type: object
      required:
        - action
        - sources
        - dst
      properties:
        action:
          type: string
          enum:
            - copy
        sources:
          type: array
          items:
            type: string
        dst:
          type: string
        user:
          type: string
        mode:
          $ref: '#/components/schemas/TemplateFileMode'
        force_upload:
          type: boolean
      additionalProperties: false
    TemplateCopyItemsStep:
      type: object
      required:
        - action
        - items
      properties:
        action:
          type: string
          enum:
            - copy_items
        items:
          type: array
          items:
            $ref: '#/components/schemas/TemplateCopyItem'
      additionalProperties: false
    TemplateRemoveStep:
      type: object
      required:
        - action
        - path
      properties:
        action:
          type: string
          enum:
            - remove
        path:
          type: string
        recursive:
          type: boolean
        force:
          type: boolean
      additionalProperties: false
    TemplateRenameStep:
      type: object
      required:
        - action
        - src
        - dst
      properties:
        action:
          type: string
          enum:
            - rename
        src:
          type: string
        dst:
          type: string
        force:
          type: boolean
      additionalProperties: false
    TemplateMakeDirStep:
      type: object
      required:
        - action
        - path
      properties:
        action:
          type: string
          enum:
            - make_dir
        path:
          type: string
        mode:
          $ref: '#/components/schemas/TemplateFileMode'
      additionalProperties: false
    TemplateMakeSymlinkStep:
      type: object
      required:
        - action
        - target
        - path
      properties:
        action:
          type: string
          enum:
            - make_symlink
        target:
          type: string
        path:
          type: string
      additionalProperties: false
    TemplateGitCloneStep:
      type: object
      required:
        - action
        - url
      properties:
        action:
          type: string
          enum:
            - git_clone
        url:
          type: string
        path:
          type: string
        branch:
          type: string
        depth:
          type: integer
          format: int64
      additionalProperties: false
    TemplateSkipCacheStep:
      type: object
      required:
        - action
      properties:
        action:
          type: string
          enum:
            - skip_cache
      additionalProperties: false
    TemplateBuildContextFile:
      type: object
      required:
        - path
        - entry_type
      properties:
        path:
          type: string
          description: Relative context path used by COPY/ADD
        entry_type:
          type: string
          enum:
            - file
            - dir
          description: Build-context entry kind
        content_base64:
          type: string
          description: >-
            Base64-encoded file content for file entries. Mutually exclusive
            with `blob_id`.
        blob_id:
          type: string
          description: >-
            Opaque blob identifier returned by `/v1/templates/blobs/preflight`.
            Mutually exclusive with `content_base64`.
        mode:
          type: string
          description: >-
            Optional octal permission bits for the file or directory (for
            example 0644 or 0755)
    TemplateReadinessProbe:
      oneOf:
        - type: object
          required:
            - kind
            - port
          properties:
            kind:
              type: string
              enum:
                - tcp
            port:
              type: integer
              format: int32
            timeout_secs:
              type: integer
              format: int32
            interval_ms:
              type: integer
              format: int64
            startup_grace_secs:
              type: integer
              format: int32
          example:
            kind: tcp
            port: 3000
            timeout_secs: 30
            interval_ms: 500
            startup_grace_secs: 2
        - type: object
          required:
            - kind
            - timeout_ms
          properties:
            kind:
              type: string
              enum:
                - timeout
            timeout_ms:
              type: integer
              format: int64
          example:
            kind: timeout
            timeout_ms: 20000
        - type: object
          required:
            - kind
            - port
            - path
          properties:
            kind:
              type: string
              enum:
                - http
            port:
              type: integer
              format: int32
            path:
              type: string
            timeout_secs:
              type: integer
              format: int32
            interval_ms:
              type: integer
              format: int64
            startup_grace_secs:
              type: integer
              format: int32
          example:
            kind: http
            port: 3000
            path: /ready
            timeout_secs: 30
            interval_ms: 500
            startup_grace_secs: 2
        - type: object
          required:
            - kind
            - command
          properties:
            kind:
              type: string
              enum:
                - command
            command:
              type: string
            timeout_secs:
              type: integer
              format: int32
            interval_ms:
              type: integer
              format: int64
            startup_grace_secs:
              type: integer
              format: int32
          example:
            kind: command
            command: test -e /tmp/template-ready
            timeout_secs: 30
            interval_ms: 500
            startup_grace_secs: 2
      discriminator:
        propertyName: kind
    TemplateBaseImageAuthBasic:
      type: object
      required:
        - kind
        - username
        - password
      properties:
        kind:
          type: string
          enum:
            - basic
        username:
          type: string
        password:
          type: string
    TemplateBaseImageAuthGcpArtifactRegistry:
      type: object
      required:
        - kind
        - service_account_json
      properties:
        kind:
          type: string
          enum:
            - gcp_artifact_registry
        service_account_json:
          oneOf:
            - type: string
            - type: object
              additionalProperties: true
              description: >-
                Parsed GCP service-account key JSON; the shape is defined by
                Google Cloud, deliberately open.
    TemplateBaseImageAuthAwsEcr:
      type: object
      required:
        - kind
        - access_key_id
        - secret_access_key
        - region
      properties:
        kind:
          type: string
          enum:
            - aws_ecr
        access_key_id:
          type: string
        secret_access_key:
          type: string
        region:
          type: string
        session_token:
          type: string
    TemplateBuildSecretSource:
      type: string
      enum:
        - value
        - env
        - file
      description: >-
        Client-side source hint for the secret value. The API receives a
        request-time value either way; env and file sources should be resolved
        by SDKs or CLIs before submission.
    ErrorDetail:
      oneOf:
        - $ref: '#/components/schemas/TemplateFailureDetail'
        - $ref: '#/components/schemas/UploadFailureDetail'
    TemplateFileMode:
      description: File mode accepted as an octal string like "0755" or as a numeric mode.
      oneOf:
        - type: string
        - type: integer
          format: int32
    TemplateCopyItem:
      type: object
      required:
        - sources
        - dst
      properties:
        sources:
          type: array
          items:
            type: string
        dst:
          type: string
        user:
          type: string
        mode:
          $ref: '#/components/schemas/TemplateFileMode'
        force_upload:
          type: boolean
      additionalProperties: false
    TemplateFailureDetail:
      type: object
      required:
        - code
        - message
        - phase
        - retryable
        - suggested_action
      properties:
        code:
          type: string
          enum:
            - unauthorized
            - file_upload_error
            - build_error
            - internal_error
        message:
          type: string
        phase:
          $ref: '#/components/schemas/TemplateFailurePhase'
        retryable:
          type: boolean
        suggested_action:
          type: string
        step_index:
          type: integer
        attempt:
          type: integer
        max_attempts:
          type: integer
        cache_subject:
          type: string
        build_id:
          type: string
        request_id:
          type: string
          description: >-
            Present on terminal request-originated failures and blocking error
            responses.
        details:
          type: object
          additionalProperties: true
          description: >-
            Stable failure metadata. Includes a `reason` key plus phase-specific
            fields such as `blob_id`, `path`, digest/size mismatch values,
            `command`, or `alias`.
    UploadFailureDetail:
      type: object
      required:
        - reason
        - message
        - retryable
      properties:
        reason:
          $ref: '#/components/schemas/UploadFailureReason'
        message:
          type: string
        retryable:
          type: boolean
        upload_id:
          type: string
        request_id:
          type: string
        path:
          type: string
          description: >-
            Normalized absolute machine path associated with the failed upload
            when available.
        part_number:
          type: integer
          format: uint32
        details:
          type: object
          additionalProperties: true
          description: >-
            Additional failure diagnostics; keys depend on the failure reason,
            deliberately open.
    TemplateFailurePhase:
      type: string
      enum:
        - auth
        - preflight
        - blob_upload
        - prepare
        - build_step
        - readiness
        - snapshot
        - finalize
        - interrupted
    UploadFailureReason:
      type: string
      enum:
        - insufficient_staging_space
        - size_limit_exceeded
        - invalid_part_checksum
        - part_out_of_range
        - part_size_mismatch
        - whole_checksum_mismatch
        - upload_expired
        - upload_aborted
        - upload_already_completed
        - target_conflict
        - directory_extract_invalid_path
        - directory_extract_invalid_symlink
        - directory_extract_unsupported_entry
        - missing_parts
  responses:
    Unauthorized:
      description: Missing or invalid bearer credential
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            unauthorized:
              summary: Missing or invalid bearer credential
              value:
                error: Missing or invalid bearer credential
                code: unauthorized
                request_id: req_123
    FeatureUnavailable:
      description: Feature is unavailable in current deployment mode
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key passed as Bearer token

````