Update Workspace

Request

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

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

PUT /api/workspaces/{workspace_name}

Path Parameters

workspace_name · string · required

Name of the workspace to update. You can find the workspace name on your Mage Pro cluster’s /apps/workspaces page.

Request Body Parameters

All request body parameters are nested under the workspace object.

workspace.action · string · required

The action to perform on the workspace. Supported values: "stop", "resume", "patch", "add_to_ingress". See the Supported Actions section below for details on each action and which parameters they support.

workspace.container_config · 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

workspace.lifecycle_config · 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:

{
  "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:

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:

{
  "workspace": {
    "action": "resume"
  }
}

Example:

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:

{
  "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:

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:

{
  "workspace": {
    "action": "add_to_ingress"
  }
}

Example:

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.

Request

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