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

# Create a template warm pool

> Creates a tenant-owned warm pool for a template. Public fields use `min_ready` and `max_ready`; the API maps them to controller inventory targets.



## OpenAPI

````yaml /openapi.yaml post /v1/template-warm-pools
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/template-warm-pools:
    post:
      tags:
        - Templates
      summary: Create a template warm pool
      description: >-
        Creates a tenant-owned warm pool for a template. Public fields use
        `min_ready` and `max_ready`; the API maps them to controller inventory
        targets.
      operationId: createTemplateWarmPool
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTemplateWarmPoolRequest'
      responses:
        '201':
          description: Warm pool created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateWarmPool'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/TemplateResourceNotFound'
        '503':
          $ref: '#/components/responses/FeatureUnavailable'
components:
  schemas:
    CreateTemplateWarmPoolRequest:
      type: object
      required:
        - name
        - template_ref
        - min_ready
        - max_ready
        - resources
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 160
        template_ref:
          type: string
          description: >-
            Built-in template name, custom template ref, tag, or build-qualified
            ref.
        template:
          type: string
          deprecated: true
          description: Alias for `template_ref` retained for SDK compatibility.
        min_ready:
          type: integer
          minimum: 0
          description: Minimum ready machines to maintain.
        max_ready:
          type: integer
          minimum: 0
          description: >-
            Maximum warming/ready capacity for this pool. Must be greater than
            or equal to `min_ready`.
        resources:
          $ref: '#/components/schemas/TemplateWarmPoolResources'
        checkout_policy:
          type: string
          enum:
            - prefer
            - require
            - bypass
          default: prefer
        idle_timeout_seconds:
          type: integer
          minimum: 1
          default: 600
        stale_after_seconds:
          type: integer
          minimum: 1
          default: 900
        version_policy:
          type: string
          enum:
            - pinned_build
            - track_tag
          default: pinned_build
        track_tag:
          type: string
          description: >-
            Required when `version_policy` is `track_tag` unless the template
            ref includes a tag.
        host_pool_id:
          type: string
          description: >-
            Optional placement host-pool scope. When set, `cell_id` must also be
            set and the resolved template must have a compatibility key.
        cell_id:
          type: string
          description: >-
            Optional placement cell scope. When set, `host_pool_id` must also be
            set and the resolved template must have a compatibility key.
        labels:
          type: object
          additionalProperties: true
          description: >-
            Free-form user-supplied labels for pool selection/reporting; stored
            verbatim, deliberately open.
        metadata:
          type: object
          additionalProperties: true
          description: >-
            Free-form pool metadata; must be a JSON object and may carry
            poolable runtime keys, otherwise uninterpreted - deliberately open.
    TemplateWarmPool:
      type: object
      required:
        - id
        - name
        - template_ref
        - resolved_template
        - resources
        - min_ready
        - max_ready
        - idle_timeout_seconds
        - stale_after_seconds
        - checkout_policy
        - version_policy
        - rollout_generation
        - rollout_status
        - status
        - state
        - labels
        - metadata
        - created_at
        - updated_at
      properties:
        id:
          type: string
          example: twp_review_pool
        name:
          type: string
        template_ref:
          type: string
        resolved_template:
          type: string
        resolved_template_build_id:
          type: string
          nullable: true
        runtime_artifact_id:
          type: string
          nullable: true
        resources:
          $ref: '#/components/schemas/TemplateWarmPoolResources'
        host_pool_id:
          type: string
          nullable: true
        cell_id:
          type: string
          nullable: true
        compatibility_key:
          type: string
          nullable: true
        min_ready:
          type: integer
        max_ready:
          type: integer
        idle_timeout_seconds:
          type: integer
        stale_after_seconds:
          type: integer
        checkout_policy:
          type: string
          enum:
            - prefer
            - require
            - bypass
        version_policy:
          type: string
          enum:
            - pinned_build
            - track_tag
        track_tag:
          type: string
          nullable: true
        rollout_generation:
          type: integer
          format: int64
        previous_resolved_template:
          type: string
          nullable: true
        previous_resolved_template_build_id:
          type: string
          nullable: true
        previous_runtime_artifact_id:
          type: string
          nullable: true
        rollout_status:
          type: object
          additionalProperties: true
          description: >-
            Server-built rollout/count diagnostics (for example current_counts
            or observed_pool_counts). Deliberately open: the shape tracks the
            warm-pool controller.
        status:
          $ref: '#/components/schemas/TemplateWarmPoolStatusCounts'
        state:
          type: string
          enum:
            - enabled
            - disabled
            - draining
            - deleted
        degraded_reason:
          type: string
          nullable: true
          enum:
            - no_eligible_hosts
            - artifact_not_ready
            - artifact_prewarm_failed
            - quota_exceeded
            - template_build_unavailable
            - controller_disabled
            - drain_active
        labels:
          type: object
          additionalProperties: true
          description: >-
            Stored user-supplied pool labels; uninterpreted by the server,
            deliberately open.
        metadata:
          type: object
          additionalProperties: true
          description: >-
            Stored user-supplied pool metadata; uninterpreted by the server,
            deliberately open.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        enabled_at:
          type: string
          format: date-time
          nullable: true
        disabled_at:
          type: string
          format: date-time
          nullable: true
        drain_requested_at:
          type: string
          format: date-time
          nullable: true
        last_reconciled_at:
          type: string
          format: date-time
          nullable: true
          description: >-
            Last time the warm-pool controller reconciled public status and
            rollout counts for this pool.
        deleted_at:
          type: string
          format: date-time
          nullable: true
    TemplateWarmPoolResources:
      type: object
      required:
        - vcpus
        - memory_mb
      properties:
        vcpus:
          type: integer
          minimum: 1
        memory_mb:
          type: integer
          minimum: 1
        disk_mb:
          type: integer
          minimum: 1
    TemplateWarmPoolStatusCounts:
      type: object
      required:
        - target
        - ready
        - warming
        - claimed
        - draining
        - failed
        - expired
        - unavailable
      properties:
        target:
          type: integer
        ready:
          type: integer
        warming:
          type: integer
        claimed:
          type: integer
        draining:
          type: integer
        failed:
          type: integer
        expired:
          type: integer
        unavailable:
          type: integer
    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
    ErrorDetail:
      oneOf:
        - $ref: '#/components/schemas/TemplateFailureDetail'
        - $ref: '#/components/schemas/UploadFailureDetail'
    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:
    InvalidRequest:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    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

````