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

# List all machines



## OpenAPI

````yaml /openapi.yaml get /v1/machines
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/machines:
    get:
      tags:
        - Machines
      summary: List all machines
      operationId: listMachines
      parameters:
        - name: state
          in: query
          required: false
          description: >-
            Filter machines by state. Multiple states may be supplied as a
            single comma-separated list (e.g. `running,paused`). Valid states:
            creating, running, paused, destroyed, error. The server parses this
            as one comma-separated string parameter.
          schema:
            type: string
        - name: limit
          in: query
          required: false
          description: Maximum number of machines to return when using cursor pagination.
          schema:
            type: integer
            minimum: 1
            maximum: 100
        - name: next_token
          in: query
          required: false
          description: Cursor token returned by a previous paginated list response.
          schema:
            type: string
        - name: template
          in: query
          required: false
          description: Filter machines by template ref.
          schema:
            type: string
        - name: metadata
          in: query
          required: false
          description: JSON object whose key/value pairs must match machine metadata.
          schema:
            type: string
        - $ref: '#/components/parameters/MachineFields'
      responses:
        '200':
          description: >-
            List of machines. Calls without list filters, pagination, or field
            masks return the legacy bare array; filtered or paginated calls
            return a paginated object.
          content:
            application/json:
              schema:
                oneOf:
                  - type: array
                    items:
                      $ref: '#/components/schemas/MachineInfo'
                  - $ref: '#/components/schemas/ListMachinesResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  parameters:
    MachineFields:
      name: fields
      in: query
      required: false
      schema:
        type: string
      description: >
        Comma-separated field mask for machine list/get responses. Supported
        fields: id, status, config, template, metadata, started_at, timeout_ms,
        timeout_at, expires_at, timeout_action, created_at, cwd, snapshot_id,
        traffic_access_token.
  schemas:
    MachineInfo:
      type: object
      required:
        - id
        - status
        - config
        - template
        - created_at
      properties:
        id:
          type: string
        status:
          $ref: '#/components/schemas/MachineStatus'
        config:
          $ref: '#/components/schemas/MachineConfig'
        template:
          type: string
        metadata:
          type: object
          additionalProperties: true
          description: >-
            Machine metadata. Attached volume state is exposed under
            `volume_attachments` in request order. Free-form user-supplied
            object stored verbatim; deliberately open.
        started_at:
          type: string
          format: date-time
        timeout_ms:
          type: integer
          format: int64
        timeout_at:
          type: string
          format: date-time
        expires_at:
          type: string
          format: date-time
          description: >-
            Alias of `timeout_at` for clients that expect an expiry timestamp
            field.
        remaining_ms:
          type: integer
          format: int64
          description: >-
            Milliseconds remaining until `timeout_at` (clamped at 0), computed
            at response time. Lets callers schedule a timeout refresh without
            re-deriving the deadline from `timeout_at` themselves.
        timeout_action:
          $ref: '#/components/schemas/MachineTimeoutAction'
        last_active_at:
          type: string
          format: date-time
          nullable: true
          description: >-
            Most recent activity timestamp (edge ingress or
            exec/file/pty/process traffic). Drives inactivity-relative
            deadlines. Absent if no activity has been observed yet.
        inactivity_timeout_ms:
          type: integer
          format: int64
          nullable: true
          description: >-
            Effective idle timeout in milliseconds, if an inactivity policy is
            set.
        auto_delete_after_ms:
          type: integer
          format: int64
          nullable: true
          description: Effective auto-delete window in milliseconds, if set.
        ephemeral:
          type: boolean
          description: >-
            Whether the machine is ephemeral (destroyed, never hibernated, on
            idle).
        created_at:
          type: string
          format: date-time
        cwd:
          type: string
          description: >-
            Normalized default working directory for this machine when one was
            configured.
        snapshot_id:
          type: string
          description: >-
            Present only when status is `paused`. The snapshot ID needed to
            resume this machine.
        warm_pool_checkout:
          $ref: '#/components/schemas/WarmPoolCheckoutResult'
    ListMachinesResponse:
      type: object
      required:
        - items
        - has_next
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/MachineInfo'
        next_token:
          type: string
          description: Cursor token for the next page when `has_next` is true.
        has_next:
          type: boolean
          description: Whether another page is available.
    MachineStatus:
      type: string
      enum:
        - creating
        - running
        - paused
        - destroyed
        - error
    MachineConfig:
      type: object
      properties:
        vcpus:
          type: integer
        memory_mb:
          type: integer
        disk_mb:
          type: integer
    MachineTimeoutAction:
      type: string
      enum:
        - destroy
        - hibernate
    WarmPoolCheckoutResult:
      type: object
      required:
        - source
        - hit
      description: >-
        Create-time warm-pool checkout result. Omitted when create did not
        consider a warm pool.
      properties:
        source:
          type: string
          enum:
            - ready_instance
            - cold_create
            - bypassed
          description: >-
            `ready_instance` means a parked VM was claimed, `cold_create` means
            create continued with a new VM, and `bypassed` means the request
            explicitly skipped warm pools.
        hit:
          type: boolean
          description: True only when `source` is `ready_instance`.
        id:
          type: string
          description: Warm-pool id that was claimed or attempted when available.
        mode:
          type: string
          enum:
            - prefer
            - require
            - bypass
          description: >-
            Requested checkout mode. Built-in automatic pool hits report
            `prefer`.
    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:
    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
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key passed as Bearer token

````