ToAPIsToAPIs
User files

Create a file deletion request

Request asynchronous deletion of one file or a batch

POST
/api/v1/user/file/deletion-requests

Note for users in mainland China: Please use https://api.toapis.cn as the API endpoint (Base URL). Replace https://api.toapis.com with https://api.toapis.cn in the examples in this document.

Behavior

Request deletion of one file or all existing files in the current account. Deletion is asynchronous: HTTP 202 means accepted. Use the returned id to check deletion progress.

  • Delete one file: send {"scope":"single","file_id":"123"}. Get file_id from the file list.
  • Clear the account's existing files: send {"scope":"all"} without file_id. Files created after the request are unaffected.

all covers registered files owned by the current account and created before this request. Older files registered later can still be included; the server determines the cutoff. Manual deletion does not require automatic cleanup to be enabled. Every POST creates a new request, so do not blindly resend after a timeout. There is no cancellation operation.

Query parameters are not accepted. The body must be a JSON object of at most 4096 bytes; unknown and duplicate fields are rejected. Body reading has a 10-second deadline. Writes share the public account limit of 10 requests per user per minute. Temporary service unavailability returns 503.

Authentication

Authorizationstringheaderrequired

Use a system access token: Bearer YOUR_SYSTEM_ACCESS_TOKEN. Model API keys are not accepted and X-User-Id is not needed. Access is limited to the authenticated account's files and policy, without subaccount aggregation.

Request parameters

scopestringbodyrequired

Required. Choose the deletion scope:

  • single: delete one specified file; file_id is required.
  • all: clear the current account's existing registered files; omit file_id. Files created after the request are unaffected.
file_idstring | nullbody

ID of the file to delete, from data.items[].id in the file list, for example "123". A valid ID string is required for scope=single. For scope=all, omit the field or send null. A null value is treated as omitted.

requestExample

curl --request POST \
  --url 'https://api.toapis.com/api/v1/user/file/deletion-requests' \
  --header 'Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"scope":"single","file_id":"123"}'
import requests

response = requests.post(
    "https://api.toapis.com/api/v1/user/file/deletion-requests",
    headers={"Authorization": "Bearer YOUR_SYSTEM_ACCESS_TOKEN"},
    json={"scope": "single", "file_id": "123"},
    timeout=30,
)
response.raise_for_status()
print(response.json())
const response = await fetch("https://api.toapis.com/api/v1/user/file/deletion-requests", {
  method: "POST",
  headers: { Authorization: "Bearer YOUR_SYSTEM_ACCESS_TOKEN", "Content-Type": "application/json" },
  body: JSON.stringify({"scope": "single", "file_id": "123"}),
  signal: AbortSignal.timeout(30_000),
});
if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${await response.text()}`);
}
console.log(await response.json());

Delete files created at or before this request's acceptance time:

curl --request POST \
  --url 'https://api.toapis.com/api/v1/user/file/deletion-requests' \
  --header 'Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"scope":"all"}'

Response fields

Examples use fictional data. See Access for the shared response format.

data.idstring

Deletion request ID used to query progress.

data.scopestring

single deletes one specified file; all clears the current account's existing files.

data.file_idstring | null

File ID for scope=single; null for scope=all.

data.created_before_atstring | null

Inclusive creation-time cutoff for scope=all; null for scope=single.

data.statestring

pending: accepted; running: in progress; processed: current scope complete; blocked: blocked files or a failed progress refresh.

data.discovered_countinteger

Currently discovered files in scope; late registrations can increase it.

data.deleted_countinteger

Cumulative deleted files. The count remains after files disappear from the list.

data.blocked_countinteger

Currently blocked files. A failed progress refresh can also mark the request blocked while retaining the last successful counters.

data.created_atstring

Request creation time.

data.updated_atstring

Last progress update time.

responseExample

{
  "code": 0,
  "message": "",
  "data": {
    "id": "456",
    "scope": "single",
    "file_id": "123",
    "created_before_at": null,
    "state": "pending",
    "discovered_count": 0,
    "deleted_count": 0,
    "blocked_count": 0,
    "created_at": "2026-11-16T08:00:00Z",
    "updated_at": "2026-11-16T08:00:00Z"
  }
}

Errors

Invalid scope, file_id, JSON, or query parameters return 400. A missing or foreign single-file target returns 404. Temporary service unavailability returns 503 (code=13035).

See Access for shared authentication, rate limits, and error handling.