Skip to main content
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, DockerRequired parameters:
  • workspace.action: "resume"
Optional parameters: NoneRequest 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, DockerRequired 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) onlyRequired parameters:
  • workspace.action: "add_to_ingress"
Optional parameters: NoneRequest 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.
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