# Update sandbox quotas for a target Workspace

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

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

```text
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](../../../../../developer/api/ai-studio/index.md).

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

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} Request example

```bash
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"}'
```

:::::
:::::{tab-item} Parameters

| 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

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} Response example

```json
{
  "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"
  }
}
```

:::::
:::::{tab-item} Fields

| 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](objects.md) for all public nested object fields and separate explanations of omission and null.
:::::
::::::
:::::::

## Error responses

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} Response example

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

:::::
:::::{tab-item} Fields

| 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](errors-recovery.md) for recovery stages.
:::::
::::::
:::::::
