# Clean orphaned Workspace files and deleted volumes

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

Manually process orphaned Catalog files and soft-deleted volumes meeting retention conditions. Deletes actual file objects and metadata; not a dry run.

```text
POST https://api.moi.matrixorigin.cn/v5/workspaces/{workspace_id}/garbage-collection
```

## Before you call this API

Set `MOI_ENDPOINT` to the product API prefix `https://api.moi.matrixorigin.cn/v5`. For private deployments, use the corresponding product API URL.

Only maintenance operators who confirmed the target environment and cleanup scope should execute this. Requires Workspace catalog.orphan_cleanup permission. Ordinary file-deletion privileges or a platform-administrator title do not establish authorization.

## Request parameters

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

```bash
curl --request POST "$MOI_ENDPOINT/workspaces/$WORKSPACE_ID/garbage-collection" \
  --header "X-API-Key: $AI_STUDIO_API_KEY" --header "X-Workspace-ID: $WORKSPACE_ID" \
  --header "Content-Type: application/json" \
  --data '{"orphan_file_threshold_hours":720,"batch_size":100}'
```

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

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| orphan_file_threshold_hours | integer | No | Minimum file age in hours after creation. Omitted/nonpositive values default to 720 hours (30 days). Positive values may shorten retention; 30 days is not an enforced minimum. Values decodable as int64 but exceeding time.Duration's hour range are rejected. Values outside int64 or with invalid types may trigger default cleanup. |
| batch_size | integer | No | Omitted/nonpositive values default to 100. Orphan-file candidates and deleted volumes each use this batch limit; it is not an overall Workspace deletion limit. |

Compatibility behavior: empty/invalid JSON resets the entire request to defaults and continues cleanup. Unknown fields are unsupported and do not provide a dry run. Do not probe using invalid bodies, a zero threshold, or zero batch size. See [Cleanup semantics](cleanup-semantics.md) for complete effects/recovery.

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

## Successful response

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

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "orphan_files_cleaned": 1,
    "deleted_volumes_cleaned": 2,
    "message": "Garbage collection completed successfully"
  }
}
```

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

| Field | Type | Description |
| --- | --- | --- |
| code | string | OK on success. |
| msg | string | OK on success. |
| data.orphan_files_cleaned | integer | |
| data.deleted_volumes_cleaned | integer | |
| data.message | string | |

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

## Error responses

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

```json
{
  "code": "ErrServer",
  "msg": "Internal Server Error"
}
```

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

| Field | Type | Description |
| --- | --- | --- |
| code | string | Invalid parameter range returns ErrParamInvalid. Permission/dependency/internal failures use standard errors. |
| msg | string | Error information. Some deletions may have completed before failure, without an overall transactional rollback guarantee. Responses do not include completed counts. |

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