Update 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

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",
          "update_workspace_settings": true
        }
      }' \
  --url https://your-mage-instance.com/api/workspaces/my-workspace