Update sandbox quotas for a target Workspace

Partially update managed/ephemeral limits and the automatic ephemeral sandbox override for a target Workspace.

PATCH https://api.moi.matrixorigin.cn/v5/admin/workspaces/{id}/sandbox-quota

Before you call this API

Prepare a valid identity for this environment, configured administrator privileges, and an accessible authentication Workspace. Workspace Owner status or Genesis taas:admin does not automatically grant these administrator privileges. The example uses a personal access token and one X-Workspace-ID. See AI Studio.

Updating a quota does not delete existing sandboxes or establish that the Provider is enabled. These APIs provide no complete administrator quota GET. Ordinary quota reads omit max_ephemeral_count/auto_ephemeral_override and cannot serve as a complete recovery backup. Before modifying values, the operator must confirm the original stored values or a saved, complete, trusted configuration. Do not send a write merely to discover the previous values.

Request parameters

curl -X PATCH "https://api.moi.matrixorigin.cn/v5/admin/workspaces/target-workspace/sandbox-quota" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $AUTH_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  --data '{"max_managed_count":0,"auto_ephemeral":"inherit"}'

Parameter

Type

Required

Description

X-API-Key

string

Yes in this example

A valid personal access token for this environment, belonging to a configured administrator principal. Confirm other standard authentication methods, such as Bearer, for the environment.

X-Workspace-ID

string

Yes

One nonempty authentication Workspace header; not a target filter or target quota Workspace.

id

string

Yes

Target Workspace ID in the path; supply it separately from the authentication header.

max_managed_count

integer / null

At least one valid field

0–100; explicit 0 is valid. Omission/null preserves the previous value.

max_ephemeral_count

integer / null

At least one valid field

0–100. The ephemeral limit is independent of the managed limit; omission/null preserves the previous value.

auto_ephemeral

string / null

At least one valid field

inherit, enabled, or disabled. Omission/null preserves the previous value; an empty string is invalid.

Successful response

{
  "code": "OK",
  "msg": "OK",
  "data": {
    "workspace_id": "target-workspace",
    "max_managed_count": 0,
    "max_ephemeral_count": 10,
    "auto_ephemeral_override": 0,
    "updated_by": "admin-example",
    "updated_at": "2026-11-12T06:00:00Z"
  }
}

Field

Type

Description

code

string

OK on success.

msg

string

OK on success.

data

object

Success data.

data.workspace_id

string

Workspace that owns the resource; not the Workspace in the authentication header.

data.max_managed_count

integer

Managed sandbox limit, 0–100. Zero can be persisted and does not immediately delete existing resources.

data.max_ephemeral_count

integer

Independent ephemeral sandbox limit, 0–100; not the managed sandbox limit.

data.auto_ephemeral_override

integer

Numeric 0 inherits the deployment default, 1 enables, and 2 disables. Requests use the auto_ephemeral string.

data.updated_by

string

Principal that last updated the resource.

data.updated_at

string

Update time in RFC3339; not guaranteed to support concurrency version control.

See Shared objects for all public nested object fields and separate explanations of omission and null.

Error responses

{"code":"ErrParamInvalid","msg":"Bad Request"}

Field

Type

Description

code

string

Error code for the current stage.

msg

string

Error text; service-classified errors are usually localized.

HTTP / code

Conditions and handling

400 / ErrParamInvalid

Missing authentication Workspace, request decoding/integer parsing failure, or invalid quota fields.

400 / SANDBOX_INVALID_SPEC

A service validation failure, such as an invalid list window or network tool. A name containing SPEC does not limit it to specification creation.

403 / COMPUTE_RESOURCE_SPEC_FORBIDDEN

The current principal is not a configured administrator, or its identity does not match the authorization boundary.

503 / COMPUTE_RESOURCE_SPEC_ADMIN_UNAVAILABLE

Classified administrator directory/authorization facts are unavailable.

404 / SANDBOX_NOT_FOUND

The resource is unmanaged, ephemeral, pooled, missing, or in a hidden creation/deletion stage.

503 / SANDBOX_IAM_UNAVAILABLE or SANDBOX_NETWORK_STORAGE_UNAVAILABLE

Lifecycle identity or network persistence dependencies are unavailable.

500 / SANDBOX_ERROR or ErrServer

An unclassified Provider or other failure, or localization failure; these do not always return 503.

See Errors and recovery for recovery stages.

Last updated on