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",
          "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"
  }
}
​
workspace.update_workspace_settings
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.

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

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