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

# Stop Workspace

> Gracefully shut down a running workspace. State is preserved on disk.



## OpenAPI

````yaml POST /api/v1/workspaces/{id}/stop
openapi: 3.1.0
info:
  title: Rigbox Public API
  description: >-
    Gateway-owned public API for Rigbox. The gateway composes its local
    lifecycle API with service-owned exported specs.
  contact:
    name: Rigbox
    url: https://rigbox.dev
  license:
    name: ''
  version: 1.0.0
servers:
  - url: https://api.rigbox.dev
    description: Production gateway
security: []
tags:
  - name: Workspaces
  - name: CLI
  - name: Observability
  - name: Auth
  - name: API Keys
  - name: Access Control
  - name: Apps
  - name: App Catalog
  - name: Logs
  - name: AI
  - name: Tools
  - name: Snapshots
  - name: SSH Keys
  - name: Templates
  - name: Setup Scripts
  - name: Service Specs
  - name: Deploy
  - name: Community
  - name: User Settings
  - name: Roadmap
  - name: System
paths:
  /api/v1/workspaces/{id}/stop:
    post:
      tags:
        - Workspaces
      summary: Stop a workspace.
      description: Stop the workspace VM while preserving its disk and configuration.
      operationId: stop_vm
      parameters:
        - name: id
          in: path
          description: Workspace ID
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Workspace stop queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetWorkspaceResponse'
      security:
        - bearer: []
components:
  schemas:
    GetWorkspaceResponse:
      type: object
      required:
        - vm
      properties:
        failure:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/WorkspaceFailure'
              description: >-
                Structured failure info when `vm.status == Failed`. `None`
                otherwise.

                Computed from the workspace's `failure_code`, `failure_reason`,
                and

                `creation_attempts` fields plus the retryable allowlist policy.
        vm:
          $ref: '#/components/schemas/Vm'
    WorkspaceFailure:
      type: object
      description: >-
        Structured failure surface returned by the workspace API when a
        workspace

        is in `Failed` status. Phase 4 Task 4.3 wires this into the response.
      required:
        - code
        - message
        - retryable
        - occurred_at
        - attempts
      properties:
        attempts:
          type: integer
          format: int32
        code:
          type: string
        message:
          type: string
        occurred_at:
          type: string
          format: date-time
        retryable:
          type: boolean
    Vm:
      type: object
      required:
        - id
        - user_id
        - node_id
        - name
        - status
        - image
        - ram_mb
        - vcpu_count
        - disk_size_mb
        - created_at
        - updated_at
      properties:
        ai_mode:
          type:
            - string
            - 'null'
          description: |-
            Per-workspace override for the AI mode (`managed` or `byok`).
            `None` means inherit from `users.ai_mode` (the per-account default).
        cloned_from:
          type:
            - string
            - 'null'
          description: >-
            Bluegreen preview lineage. `None` = a normal workspace.
            `Some(source_id)`

            = this VM is a COW clone of `source_id`, booted as a hidden preview;

            promote repoints the prod subdomain's edge route to it. See

            [`Vm::is_preview`].
        created_at:
          type: string
          format: date-time
        creation_attempts:
          type: integer
          format: int32
        creation_started_at:
          type:
            - string
            - 'null'
          format: date-time
        disk_size_mb:
          type: integer
          format: int32
          minimum: 0
        env_vars:
          type:
            - object
            - 'null'
          additionalProperties:
            type: string
          propertyNames:
            type: string
        failure_code:
          type:
            - string
            - 'null'
        failure_reason:
          type:
            - string
            - 'null'
        id:
          type: string
        image:
          type: string
        image_digest:
          type:
            - string
            - 'null'
          description: >-
            Content-addressed image this workspace is pinned to. When set, the

            workspace boots from this registry image (staged as the rootfs on
            first

            boot) instead of the named base in `image`. `None` = the named-base
            path.
        ip_address:
          type:
            - string
            - 'null'
        name:
          type: string
        node_id:
          type: string
        ram_mb:
          type: integer
          format: int32
          minimum: 0
        service_spec_ids:
          type:
            - array
            - 'null'
          items:
            type: string
        setup_script_ids:
          type:
            - array
            - 'null'
          items:
            type: string
        status:
          $ref: '#/components/schemas/VmStatus'
        template_id:
          type:
            - string
            - 'null'
        updated_at:
          type: string
          format: date-time
        user_id:
          type: string
        vcpu_count:
          type: integer
          format: int32
          minimum: 0
    VmStatus:
      type: string
      enum:
        - provisioned
        - provisioning
        - starting
        - running
        - stopping
        - stopped
        - deleting
        - failed
  securitySchemes:
    bearer:
      type: http
      scheme: bearer

````