Skip to content

Delete an asset

DELETE
/assets/{id}

Moves an asset to the trash. It leaves ordinary lists and reads at once and can be restored with POST /admin/assets/{id}/restore. After the retention period (30 days by default), a scheduled cleanup can remove it for good.

The owner, assets.admin (global, or for the asset’s team or a team above it) or system.admin can delete it; anyone else gets 403. You’re recorded as the deleter, which is what lets you restore it later. After the delete, the server tries to write an admin.asset.soft_deleted audit event and to drop the asset’s hold on its stored file; a failure in either is only logged. A deleted or unknown id gets 404.

Deleting doesn’t remove the stored file. It stays in storage, and GET /storage/objects/{hash} still serves it to any signed-in account with the hash. system.admin can still list the deleted asset with GET /assets?include_deleted=true. The cleanup runs in daily batches, so it can come well after the retention period, and it deletes the asset record and what’s attached to it, but not the stored bytes.

id
required
string format: uuid

Optional body for a delete. Send nothing, or {}, to delete without a reason.

object
reason

Why it was deleted, stored as deleted_reason. Surrounding spaces are trimmed, an empty reason counts as none, and more than 500 bytes after trimming gets 400.

string
<= 500 characters

Moved to the trash.

Malformed request

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Authentication required, missing, or invalid

object
error
required

Human-readable error summary

string
Example
the request could not be completed
Example
{
"error": "authentication required: sign in and retry with a valid session or API token"
}

Authenticated but missing required capabilities

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Resource not found

object
error
required

Human-readable error summary

string
Example
the request could not be completed