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

# 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`.




## OpenAPI

````yaml /openapi.yaml post /v1/templates/builds
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/builds:
    post:
      tags:
        - Templates
      summary: Start a background template build
      description: >
        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`.
      operationId: startTemplateBuild
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTemplateRequest'
      responses:
        '202':
          description: Build accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateBuild'
        '400':
          description: >-
            Invalid request or build-context blob failure before the build is
            accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalidRequest:
                  summary: Invalid payload
                  value:
                    error: template name contains invalid characters
                    code: invalid_request
                    request_id: req_123
                emptyTags:
                  summary: Empty tag list
                  value:
                    error: template tags must not be empty
                    code: invalid_request
                    request_id: req_123
                fileUploadError:
                  summary: Build-context blob failure
                  value:
                    error: blob preflight failed
                    code: file_upload_error
                    request_id: req_123
                    error_detail:
                      code: file_upload_error
                      message: blob preflight failed
                      phase: preflight
                      retryable: true
                      suggested_action: >-
                        Re-preflight the build context and upload any missing
                        blobs.
                      request_id: req_123
                      details:
                        reason: missing_blob
        '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
    TemplateBuild:
      type: object
      required:
        - build_id
        - template_id
        - name
        - tags
        - status
        - build_backend
        - source_type
        - canonical_ref
        - namespace_slug
        - visibility
        - created_at
        - updated_at
      properties:
        build_id:
          type: string
        template_id:
          type: string
        name:
          type: string
        tags:
          type: array
          items:
            type: string
        status:
          $ref: '#/components/schemas/TemplateBuildStatus'
        build_backend:
          $ref: '#/components/schemas/TemplateBuildBackend'
        source_type:
          $ref: '#/components/schemas/TemplateBuildSourceType'
        source_digest:
          type: string
        context_digest:
          type: string
        dockerfile_digest:
          type: string
        build_config:
          $ref: '#/components/schemas/TemplateBuildConfig'
        triggered_by:
          type: string
        queued_at:
          type: string
          format: date-time
        started_at:
          type: string
          format: date-time
        finished_at:
          type: string
          format: date-time
        duration_ms:
          type: integer
          format: uint64
        failure_phase:
          type: string
        cache_summary:
          $ref: '#/components/schemas/TemplateBuildCacheSummary'
        artifact_availability:
          $ref: '#/components/schemas/TemplateBuildArtifactAvailability'
        promotability:
          $ref: '#/components/schemas/TemplateBuildPromotability'
        retention_expires_at:
          type: string
          format: date-time
        runtime_defaults:
          $ref: '#/components/schemas/TemplateRuntimeDefaults'
        oci_metadata:
          $ref: '#/components/schemas/TemplateOciImageMetadata'
        artifact_ids:
          type: array
          items:
            type: string
        retry_of_build_id:
          type: string
        original_build_id:
          type: string
        cancel_requested_at:
          type: string
          format: date-time
        cancel_requested_by:
          type: string
        cancellation_reason:
          type: string
        error:
          type: string
        error_detail:
          $ref: '#/components/schemas/TemplateFailureDetail'
        canonical_ref:
          type: string
        namespace_slug:
          type: string
        visibility:
          $ref: '#/components/schemas/TemplateVisibility'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    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
    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
    TemplateBuildStatus:
      type: string
      enum:
        - waiting
        - building
        - ready
        - error
        - cancelled
    TemplateBuildSourceType:
      type: string
      enum:
        - declarative
        - dockerfile
        - oci_import
        - template_base
    TemplateBuildCacheSummary:
      type: object
      properties:
        final_artifact_hits:
          type: integer
        final_artifact_misses:
          type: integer
        final_artifact_bypasses:
          type: integer
        final_artifact_stores:
          type: integer
        layer_hits:
          type: integer
        layer_misses:
          type: integer
        layer_bypasses:
          type: integer
        layer_stores:
          type: integer
        file_blob_hits:
          type: integer
        file_blob_misses:
          type: integer
        file_blob_bypasses:
          type: integer
        file_blob_stores:
          type: integer
    TemplateBuildArtifactAvailability:
      type: object
      required:
        - status
      properties:
        status:
          $ref: '#/components/schemas/TemplateBuildArtifactAvailabilityStatus'
        reason:
          type: string
    TemplateBuildPromotability:
      type: object
      required:
        - status
        - promotable
      properties:
        status:
          $ref: '#/components/schemas/TemplateBuildPromotabilityStatus'
        promotable:
          type: boolean
        reason:
          type: string
    TemplateRuntimeDefaults:
      type: object
      description: >-
        Effective runtime defaults retained for a built template. Environment
        values are intentionally omitted; only keys are exposed.
      properties:
        default_env_keys:
          type: array
          items:
            type: string
        start_cmd:
          type: string
        default_user:
          type: string
        default_workdir:
          type: string
        readiness:
          $ref: '#/components/schemas/TemplateReadinessProbe'
    TemplateOciImageMetadata:
      type: object
      description: >-
        OCI image metadata retained from Dockerfile or OCI imports. Volume
        declarations are metadata only and do not create persistent Nullspace
        volumes.
      properties:
        labels:
          type: object
          additionalProperties:
            type: string
        exposed_ports:
          type: array
          items:
            type: string
        volumes:
          type: array
          items:
            type: string
        healthcheck:
          $ref: '#/components/schemas/TemplateOciHealthcheckMetadata'
    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`.
    TemplateVisibility:
      type: string
      enum:
        - private
        - public
    ErrorDetail:
      oneOf:
        - $ref: '#/components/schemas/TemplateFailureDetail'
        - $ref: '#/components/schemas/UploadFailureDetail'
    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.
    TemplateBuildArtifactAvailabilityStatus:
      type: string
      enum:
        - available
        - publishing
        - warming
        - unavailable
        - failed
    TemplateBuildPromotabilityStatus:
      type: string
      enum:
        - promotable
        - not_ready
        - expired
        - purged
        - unavailable
    TemplateOciHealthcheckMetadata:
      type: object
      properties:
        test:
          type: array
          items:
            type: string
        interval_ns:
          type: integer
          format: int64
        timeout_ns:
          type: integer
          format: int64
        start_period_ns:
          type: integer
          format: int64
        retries:
          type: integer
          format: int32
        mapped_readiness:
          $ref: '#/components/schemas/TemplateReadinessProbe'
    TemplateFailurePhase:
      type: string
      enum:
        - auth
        - preflight
        - blob_upload
        - prepare
        - build_step
        - readiness
        - snapshot
        - finalize
        - interrupted
    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.
    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
    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

````