Expiry, trash and deletion
An upload may set variants: { ttl: 3600 } for a lifetime in seconds, or variants.expireAt for an absolute Unix timestamp (seconds or milliseconds). The API owns the expiry date and schedules the same physical deletion operation used by normal file management. A worker restart cannot forget the expiry. Processing and cleanup can take time; the file record exposes the current state.
Trash and restore
DELETE /cdn/files/:id requests trash. A 202 response means the operation is queued, not that disk space has already been freed. The origin blocks removed files, and the node moves their objects out of the public tree. Originals and variants move together through a durable operation. Trash still uses storage and credits.
POST /cdn/files/:id/restore requests restoration. The API rechecks account and namespace access and the retained-storage ceiling before restoring; a restore cannot bypass the current byte or credit policy. The dashboard displays pending operations and refreshes their result.
Trash is retained for the number of days in the provider policy, initially seven. Expired trash is queued for permanent removal. Do not use CDN trash as your only backup.
Files brought forward from the earlier image service receive this retention window from their inventory date. The migration does not immediately purge old trash or expired legacy files.
Permanent deletion
DELETE /cdn/files/:id?permanent=true requests irreversible removal of every retained object. The owning node must confirm removal before the API records purged_at and stops storage billing. Retrying the request or its acknowledgement does not produce a duplicate operation or charge. Purged files cannot be restored.
A scheduled upload expiry also uses permanent removal. It does not refund prior storage, delivered traffic, or the current month's published-upload quota. Physical storage is released only after confirmed cleanup.
Reading status
Read GET /cdn/files/:id to inspect storage_state, is_deleted, purged_at and pending_operation. File operations are scoped to the account and, for namespace credentials, to that exact namespace. Other tenants' identifiers return not found.
Public caches may retain previously downloaded files until their own expiry. Deletion blocks future authorized origin access; it cannot revoke copies already downloaded or held by an external cache. CDN media URLs are public, not a private-document authorization system.