Set file retention
Set or clear the current account's file retention
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
Set the current account's file retention in days. For example, 7 retains files for 7 days from creation. Send null to clear the custom setting and use platform retention rules.
The platform default is 30 days; the current platform configuration determines the limit. A custom value must not exceed that limit: with a 30-day limit, 30 is accepted and 31 returns 400. User retention applies to existing and newly created ordinary files while platform automatic cleanup is enabled.
Cleanup is asynchronous. Shortening retention can make existing files eligible for the next cleanup. Extending or clearing it does not cancel deletion already in progress or previously submitted manual deletion requests.
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
retention_daysintegerbodyrequiredRequired JSON positive integer or null. The integer must not exceed the current platform limit, which defaults to 30 days. 7 means 7 days; null clears the custom setting and uses platform rules. Omission, zero, negative numbers, fractions, and numeric strings are invalid.
requestExample
curl --request PUT \
--url 'https://api.toapis.com/api/v1/user/file/retention' \
--header 'Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{"retention_days":7}'import requests
response = requests.put(
"https://api.toapis.com/api/v1/user/file/retention",
headers={"Authorization": "Bearer YOUR_SYSTEM_ACCESS_TOKEN"},
json={"retention_days": 7},
timeout=30,
)
response.raise_for_status()
print(response.json())const response = await fetch("https://api.toapis.com/api/v1/user/file/retention", {
method: "PUT",
headers: { Authorization: "Bearer YOUR_SYSTEM_ACCESS_TOKEN", "Content-Type": "application/json" },
body: JSON.stringify({"retention_days": 7}),
signal: AbortSignal.timeout(30_000),
});
if (!response.ok) {
throw new Error(`HTTP ${response.status}: ${await response.text()}`);
}
console.log(await response.json());Clear the user-defined retention:
curl --request PUT \
--url 'https://api.toapis.com/api/v1/user/file/retention' \
--header 'Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{"retention_days":null}'Response fields
Examples use fictional data. See Access for the shared response format.
data.retention_daysinteger | nullUser-defined retention in days. null means no custom setting; platform rules apply, with a default of 30 days.
responseExample
{
"code": 0,
"message": "",
"data": {
"retention_days": 7
}
}Errors
Exceeding the current platform limit returns 400 (code=17052) without saving the setting. The error message is localized using Accept-Language and states the allowed integer range; data.params.max contains the current maximum days.
Missing or invalid retention_days, malformed JSON, or query parameters return 400. Temporary service unavailability returns 503 (code=13035).
See Access for shared authentication, rate limits, and error handling.