Clear the Drive for a specified Identity.
Drive is currently in Beta. API definitions, response structures, and behavior may change. Follow documentation updates and verify compatibility before production use.
DELETE /api/v1/forward/drives
Request Headers
| Header | Required | Description |
|---|---|---|
| Authorization | Yes | Bearer <PAT or SAT> |
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| identity_id | string | Yes | Identity ID within the current authentication scope; supply exactly once. An Identity-level SAT can select only its bound Identity. |
Example Request
Example Response
HTTP 200 OK
Response Fields
| Field | Type | Description |
|---|---|---|
| deleted_count | integer | Number of storage objects confirmed deleted in this request; 0 if Drive was already empty. |
Errors
| HTTP | Code | Condition |
|---|---|---|
| 400 | — | The request body contains unsupported fields or is malformed. |
| 400 | invalid_drive_path | The Identity identifier format is invalid. |
| 400 | invalid_identity_id | identity_id is missing, empty, or supplied more than once. |
| 401 | — | Credentials are missing or invalid. Exchange a Service Account Key for a SAT first. |
| 403 | identity_mismatch | An Identity-level SAT selected another Identity. |
| 404 | identity_not_found | The Identity was not found within the current authentication scope. |
| 413 | — | The request body exceeds the service limit. |
| 500 | — | Internal server error. |
| 503 | drive_delete_partial | Clearing is incomplete. error.deleted_count gives the number confirmed deleted in this request. Retry the original request. |
| 503 | drive_unavailable | Drive storage, signing, or a dependency is temporarily unavailable. |
HTTP Error Response
Response Fields
| Field | Type | Description |
|---|---|---|
| type | string | Always error. |
| request_id | string | Request trace ID, returned when available. |
| error.type | string | Error category, such as invalid_request_error, authentication_error, permission_error, not_found_error, conflict_error, or api_error. |
| error.code | string | Business error code; omitted for some common errors. |
| error.message | string | Error description. |
| error.deleted_count | integer | Returned only for drive_delete_partial: the number of objects confirmed deleted in this request, which may be 0. |
drive_delete_partial means deletion is incomplete. Deleted files are not restored; retries process only the remaining files.
Gateway authentication errors may use a different response structure.