<span id="更新工作区沙箱配额"></span>

# Update workspace sandbox quota

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

Update sandbox quotas and automatic temporary allocation policy for a workspace you may manage. Setting a limit does not delete existing resources.

```text
PATCH https://api.moi.matrixorigin.cn/v5/agent-sandboxes/quota
```

<span id="调用前准备"></span>

## Before you call this API

Prepare a personal access token and operation permissions for the target workspace. Keep environment, token, workspace, and sandbox ID consistent. [Common objects and result confirmation](objects.md) describes resource identity, fields, and states. Replace example resource values with actual values.

<span id="请求"></span>

## Request

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

```bash
curl -X PATCH "https://api.moi.matrixorigin.cn/v5/agent-sandboxes/quota" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  --data-binary '{"max_managed_count":0,"auto_ephemeral":"inherit"}'
```

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `max_managed_count` | integer | No | 0–100. 0 can stop further hosted sandbox allocation. |
| `max_ephemeral_count` | integer | No | 0–100; temporary sandbox allocation limit. |
| `auto_ephemeral` | string | No | inherit, enabled, or disabled: inherit deployment settings, enable automatic temporary allocation, or disable it. |

Submit at least one valid field. Omission/null retains values; explicit 0 must be preserved. Request string policy and response numeric override use different representations; see the field table. Limits affect subsequent admission, without terminating or deleting current sandboxes.

:::::
::::::
:::::::

<span id="成功响应"></span>

## Successful response

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

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "workspace_id": "workspace-example",
    "max_managed_count": 0,
    "max_ephemeral_count": 10,
    "auto_ephemeral_override": 0,
    "updated_by": "user-example",
    "updated_at": "2026-11-11T08:00:00Z"
  }
}
```

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

HTTP 200 data has the following meaning; example values are not defaults.

| Field | Type | Description |
| --- | --- | --- |
| `code` | string | OK on success. |
| `msg` | string | Response description. |
| `data.workspace_id` | string | Current Workspace ID. |
| `data.max_managed_count` | integer | Saved hosted limit. |
| `data.max_ephemeral_count` | integer | Saved temporary limit. |
| `data.auto_ephemeral_override` | integer | 0 inherit, 1 explicitly enabled, 2 explicitly disabled. |
| `data.updated_by` | string | Last updater ID. |
| `data.updated_at` | string | Update time in RFC 3339 format. |

:::::
::::::
:::::::

<span id="结果确认"></span>

## Confirm the result

Check returned configuration and [current hosted usage](get-quota.md). override:0 only means inheritance and does not establish the deployment's effective default automatic policy.

<span id="错误处理"></span>

## Error handling

Use HTTP status and response code. [Common errors and recovery](objects.md#错误与恢复) distinguishes parameters, permissions, quotas, providers, and unknown outcomes. An error does not prove no resource was created or that retries/cleanup have completed.
