Create a file deletion request
Request asynchronous deletion of one file or a batch
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"}. Getfile_idfrom the file list. - Clear the account's existing files: send
{"scope":"all"}withoutfile_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
AuthorizationstringheaderrequiredUse 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
scopestringbodyrequiredRequired. Choose the deletion scope:
single: delete one specified file;file_idis required.all: clear the current account's existing registered files; omitfile_id. Files created after the request are unaffected.
file_idstring | nullbodyID 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.idstringDeletion request ID used to query progress.
data.scopestringsingle deletes one specified file; all clears the current account's existing files.
data.file_idstring | nullFile ID for scope=single; null for scope=all.
data.created_before_atstring | nullInclusive creation-time cutoff for scope=all; null for scope=single.
data.statestringpending: accepted; running: in progress; processed: current scope complete; blocked: blocked files or a failed progress refresh.
data.discovered_countintegerCurrently discovered files in scope; late registrations can increase it.
data.deleted_countintegerCumulative deleted files. The count remains after files disappear from the list.
data.blocked_countintegerCurrently blocked files. A failed progress refresh can also mark the request blocked while retaining the last successful counters.
data.created_atstringRequest creation time.
data.updated_atstringLast 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.