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 |
|---|---|---|---|
|
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. |
|
string |
Yes |
One nonempty authentication Workspace header; not a target filter or target quota Workspace. |
|
string |
Yes |
Target Workspace ID in the path; supply it separately from the authentication header. |
|
integer / null |
At least one valid field |
0–100; explicit 0 is valid. Omission/null preserves the previous value. |
|
integer / null |
At least one valid field |
0–100. The ephemeral limit is independent of the managed limit; omission/null preserves the previous value. |
|
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 |
|---|---|---|
|
string |
OK on success. |
|
string |
OK on success. |
|
object |
Success data. |
|
string |
Workspace that owns the resource; not the Workspace in the authentication header. |
|
integer |
Managed sandbox limit, 0–100. Zero can be persisted and does not immediately delete existing resources. |
|
integer |
Independent ephemeral sandbox limit, 0–100; not the managed sandbox limit. |
|
integer |
Numeric 0 inherits the deployment default, 1 enables, and 2 disables. Requests use the auto_ephemeral string. |
|
string |
Principal that last updated the resource. |
|
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 |
|---|---|---|
|
string |
Error code for the current stage. |
|
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.