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

# Cancel a queued or running template build

> Requests cancellation for an active template build. Cancellation is idempotent for terminal builds and returns the current build snapshot.




## OpenAPI

````yaml /openapi.yaml post /v1/templates/builds/{build_id}/cancel
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/{build_id}/cancel:
    parameters:
      - name: build_id
        in: path
        required: true
        schema:
          type: string
    post:
      tags:
        - Templates
      summary: Cancel a queued or running template build
      description: >
        Requests cancellation for an active template build. Cancellation is
        idempotent for terminal builds and returns the current build snapshot.
      operationId: cancelTemplateBuild
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancelTemplateBuildRequest'
      responses:
        '200':
          description: Current build state after cancellation handling
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateBuildStatusSnapshot'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/TemplateResourceNotFound'
        '503':
          $ref: '#/components/responses/FeatureUnavailable'
components:
  schemas:
    CancelTemplateBuildRequest:
      type: object
      properties:
        reason:
          type: string
          description: Optional human-readable cancellation reason recorded on the build.
    TemplateBuildStatusSnapshot:
      type: object
      required:
        - build
        - entries
        - next_offset
      properties:
        build:
          $ref: '#/components/schemas/TemplateBuild'
        entries:
          type: array
          items:
            $ref: '#/components/schemas/TemplateBuildLogEntry'
        next_offset:
          type: integer
          format: uint64
    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
    TemplateBuildLogEntry:
      type: object
      description: A single structured build log entry emitted during template build
      required:
        - build_id
        - template_id
        - offset
        - timestamp
        - kind
        - level
        - message
      properties:
        build_id:
          type: string
        template_id:
          type: string
        offset:
          type: integer
          format: uint64
        timestamp:
          type: string
          format: date-time
        kind:
          $ref: '#/components/schemas/TemplateBuildLogKind'
        level:
          $ref: '#/components/schemas/TemplateBuildLogLevel'
        message:
          type: string
          description: Canonical human-readable log message for this build entry
        error_detail:
          $ref: '#/components/schemas/TemplateFailureDetail'
        result:
          $ref: '#/components/schemas/TemplateInfo'
        result_metadata:
          $ref: '#/components/schemas/TemplateBuildResultMetadata'
        phase:
          type: string
          description: >-
            Build phase: cache, preparing, vm_create, step, sync, startup,
            readiness, snapshot, finalize, cleanup, retry
        step_index:
          type: integer
          description: 1-indexed current build step number
        total_steps:
          type: integer
          description: Total number of build steps
        attempt:
          type: integer
          description: Current retry attempt (1-indexed)
        max_attempts:
          type: integer
          description: Maximum number of retry attempts allowed
        cache_kind:
          type: string
          enum:
            - file_blob
            - layer
            - final_artifact
          description: Cache layer this event describes
        cache_status:
          type: string
          enum:
            - hit
            - miss
            - stored
            - bypass
          description: Cache outcome for this event
        cache_reason:
          type: string
          enum:
            - whole_build_skip_cache
            - builder_cache_boundary
            - force_upload
            - missing_or_incompatible
          description: Optional reason for a cache miss or bypass
        cache_subject:
          type: string
          description: >-
            Human-readable cache target such as a build-context path or step
            description
    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
    TemplateBuildStatus:
      type: string
      enum:
        - waiting
        - building
        - ready
        - error
        - cancelled
    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
    TemplateBuildSourceType:
      type: string
      enum:
        - declarative
        - dockerfile
        - oci_import
        - template_base
    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.
    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
    TemplateBuildLogKind:
      type: string
      enum:
        - start
        - message
        - cache
        - retry
        - warning
        - error
        - cancelled
        - end
    TemplateBuildLogLevel:
      type: string
      enum:
        - debug
        - info
        - warn
        - error
    TemplateInfo:
      type: object
      required:
        - id
        - name
        - description
        - builtin
        - canonical_ref
        - namespace_slug
        - visibility
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        tags:
          type: array
          items:
            type: string
        default_tag:
          type: string
        builtin:
          type: boolean
        canonical_ref:
          type: string
        namespace_slug:
          type: string
        visibility:
          $ref: '#/components/schemas/TemplateVisibility'
        runtime_defaults:
          $ref: '#/components/schemas/TemplateRuntimeDefaults'
    TemplateBuildResultMetadata:
      type: object
      description: >-
        Additional metadata attached to terminal build log entries and durable
        build attempts.
      properties:
        runtime_defaults:
          $ref: '#/components/schemas/TemplateRuntimeDefaults'
        oci_metadata:
          $ref: '#/components/schemas/TemplateOciImageMetadata'
    ErrorDetail:
      oneOf:
        - $ref: '#/components/schemas/TemplateFailureDetail'
        - $ref: '#/components/schemas/UploadFailureDetail'
    TemplateBuildArtifactAvailabilityStatus:
      type: string
      enum:
        - available
        - publishing
        - warming
        - unavailable
        - failed
    TemplateBuildPromotabilityStatus:
      type: string
      enum:
        - promotable
        - not_ready
        - expired
        - purged
        - unavailable
    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
    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.
    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
    TemplateResourceNotFound:
      description: Template or template build not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    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

````