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

# Update Workspace

Update the configuration of an existing workspace in your Mage Pro cluster.

`PUT /api/workspaces/{workspace_name}`

## Path Parameters

<ParamField path="workspace_name" type="string" required>
  Name of the workspace to update. You can find the workspace name on your Mage Pro cluster's `/apps/workspaces` page.
</ParamField>

## Request Body Parameters

All request body parameters are nested under the `workspace` object.

<ParamField body="workspace.action" type="string" required>
  The action to perform on the workspace. Supported values: `"stop"`, `"resume"`, `"patch"`, `"add_to_ingress"`.
  See the [Supported Actions](#supported-actions) section below for details on each action and which parameters they support.
</ParamField>

<ParamField body="workspace.container_config" type="string">
  Optional. YAML configuration string for the container. Used with the `patch` action.\
  Allows you to update container-level settings such as environment variables, resource limits, and other container configurations.
  For example, updating environment variables:

  ```
  env:
    - name: ENV
      value: test
    - name: API_KEY
      value: secret-key
  ```
</ParamField>

<ParamField body="workspace.lifecycle_config" type="object">
  Optional. Dictionary/object containing lifecycle configuration. Used with the `patch` action.
  Defines lifecycle management policies including termination policies, pre-start scripts, and post-start hooks.
  Structure:

  ```json theme={"system"}
  {
    "termination_policy": {
      "enable_auto_termination": true,
      "max_idle_seconds": 1800
    },
    "pre_start_script_path": "/path/to/script.sh",
    "post_start": {
      "command": ["echo", "Workspace started"],
      "hook_path": "/path/to/hook.sh"
    }
  }
  <ParamField body="workspace.action" type="string" required>
  The action to perform. Use `"patch"` to apply partial updates to the workspace configuration.
  </ParamField>

  <ParamField body="workspace.container_config" type="string">
  Optional. Configuration string for the container.  
  For example, updating the workspace image tag and environment variables:
  ```

  image\_tag: 2026.06.16
  env:

  * name: ENV
    value: test

  ````
  </ParamField>

  <ParamField body="workspace.update_workspace_settings" type="boolean">
  Optional. Whether to update workspace settings with the current cluster's environment variables. Used with the `patch` action.
  Set to `true` to sync the workspace configuration with the cluster-level environment variables.
  When enabled, the workspace will inherit environment variables from the cluster configuration.
  </ParamField>

  ## Supported Actions

  The `action` field determines what operation will be performed on the workspace. Each action supports different parameters and cluster types.

  ### `stop`

  Stops a running workspace. The workspace metadata is preserved, but the cloud instance is stopped or paused.

  **Supported cluster types:** K8S, Docker

  **Required parameters:**
  - `workspace.action`: `"stop"`

  **Optional parameters:** None

  **Request body:**
  ```json
  {
  "workspace": {
    "action": "stop"
  }
  }
  ````

  **Example:**

  ```bash theme={"system"}
  curl --request PUT \
    -H 'Content-Type: application/json' \
    -H 'OAUTH-TOKEN: <your-oauth-token>' \
    -d '{
          "workspace": {
            "action": "stop"
          }
        }' \
    --url https://your-mage-instance.com/api/workspaces/my-workspace
  ```

  ### `resume`

  Resumes a stopped workspace, restarting the cloud instance.

  **Supported cluster types:** K8S, Docker

  **Required parameters:**

  * `workspace.action`: `"resume"`

  **Optional parameters:** None

  **Request body:**

  ```json theme={"system"}
  {
    "workspace": {
      "action": "resume"
    }
  }
  ```

  **Example:**

  ```bash theme={"system"}
  curl --request PUT \
    -H 'Content-Type: application/json' \
    -H 'OAUTH-TOKEN: <your-oauth-token>' \
    -d '{
          "workspace": {
            "action": "resume"
          }
        }' \
    --url https://your-mage-instance.com/api/workspaces/my-workspace
  ```

  ### `patch`

  Applies partial updates to the workspace configuration, such as updating environment variables, container settings, or lifecycle configurations.

  **Supported cluster types:** K8S, Docker

  **Required parameters:**

  * `workspace.action`: `"patch"`

  **Optional parameters:**

  * `workspace.container_config` (string) - YAML configuration string for the container
  * `workspace.lifecycle_config` (object) - Dictionary containing lifecycle configuration (termination policy, pre-start scripts, post-start hooks)
  * `workspace.update_workspace_settings` (boolean) - Whether to sync workspace settings with cluster-level environment variables

  **Request body:**

  ```json theme={"system"}
  {
    "workspace": {
      "action": "patch",
      "container_config": "env:\n  - name: ENV\n    value: test",
      "lifecycle_config": {
        "termination_policy": {
          "enable_auto_termination": true,
          "max_idle_seconds": 1800
        },
        "pre_start_script_path": "/path/to/script.sh"
      },
      "update_workspace_settings": true
    }
  }
  ```

  **Example:**

  ```bash theme={"system"}
  curl --request PUT \
    -H 'Content-Type: application/json' \
    -H 'OAUTH-TOKEN: <your-oauth-token>' \
    -d '{
          "workspace": {
            "action": "patch",
            "container_config": "env:\n  - name: ENV\n    value: test",
            "update_workspace_settings": true
          }
        }' \
    --url https://your-mage-instance.com/api/workspaces/my-workspace
  ```

  ### `add_to_ingress`

  Adds the workspace service to the Kubernetes ingress configuration, making it accessible via the ingress URL.

  **Supported cluster types:** Kubernetes (K8S) only

  **Required parameters:**

  * `workspace.action`: `"add_to_ingress"`

  **Optional parameters:** None

  **Request body:**

  ```json theme={"system"}
  {
    "workspace": {
      "action": "add_to_ingress"
    }
  }
  ```

  **Example:**

  ```bash theme={"system"}
  curl --request PUT \
    -H 'Content-Type: application/json' \
    -H 'OAUTH-TOKEN: <your-oauth-token>' \
    -d '{
          "workspace": {
            "action": "add_to_ingress"
          }
        }' \
    --url https://your-mage-instance.com/api/workspaces/my-workspace
  ```

  Optional. Whether to update workspace settings with the current cluster's environment variables.\
  Set to `true` to sync the workspace configuration with the cluster-level environment.
</ParamField>

<RequestExample>
  ```bash Request theme={"system"}
  curl --request PUT \
    -H 'Content-Type: application/json' \
    -H 'OAUTH-TOKEN: <your-oauth-token>' \
    -d '{
          "workspace": {
            "action": "patch",
            "container_config": "env:\n  - name: ENV\n    value: test",
            "container_config": "image_tag: 2026.06.16\nenv:\n  - name: ENV\n    value: test",
            "update_workspace_settings": true
          }
        }' \
    --url https://your-mage-instance.com/api/workspaces/my-workspace
  ```
</RequestExample>