Skip to main content

Deleting Assets

Konifer removes asset metadata and variant references during the DELETE request, then schedules object-store content for cleanup. You can no longer fetch the deleted asset through Konifer APIs.

warning

Deletion is permanent. Konifer has no soft-delete or restore operation.

Request​

Select one of these operations:

OperationRequestLabel filters
Delete one entryDELETE /assets/{path}/-/entry/{entryId}Use the path and entry ID
Delete all at an exact pathDELETE /assets/{path}?limit=-1Supported
Delete a path and descendantsDELETE /assets/{path}/-/recursiveSupported

A DELETE without one of these selections returns 400 Bad Request. Ordering selectors and positive DELETE limits also return 400.

Only limit and query parameters prefixed with label: are accepted. Unknown parameters return 400 Bad Request with code INVALID_REQUEST before any assets are deleted.

Delete Specific Asset​

Use the entryId returned by an upload or fetch response. Omit limit, including limit=1.

DELETE /assets/users/123/-/entry/0

Example: delete a specific entry​

Replace 0 in the URL with the entry ID you want to delete.

curl --fail-with-body \
--request DELETE \
'http://localhost:8080/assets/user/123/profile-picture/-/entry/0'

Ordering​

Use new or modified on an entries fetch to choose a bounded set, then delete the returned entry IDs. Konifer rejects these selectors on DELETE requests.

Limit​

DELETE selectionAllowed limit
Exact path, without selectorsRequired: limit=-1
entry/{entryId}Omit limit
recursiveOmit limit

Supply limit once. Konifer returns 400 Bad Request for repeated parameters, blank or malformed values, values outside the signed 32-bit integer range, zero, or values below -1. Positive limits also return 400 on DELETE. Even a limit of 1 or -1 is invalid alongside an entry or recursive selector.

Example: delete the most recently modified entries​

Fetch up to two entries in modification order, then delete those entry IDs. Fetch the list once and retain the IDs if you need to retry. This is a sequence of requests: some deletions may succeed before a later request fails.

# Read entryId values from the response's entries array.
curl --fail-with-body \
'http://localhost:8080/assets/user/123/profile-picture/-/modified/entries?limit=2'

# Replace 42 and 41 with the IDs from that response.
curl --fail-with-body \
--request DELETE \
'http://localhost:8080/assets/user/123/profile-picture/-/entry/42'
curl --fail-with-body \
--request DELETE \
'http://localhost:8080/assets/user/123/profile-picture/-/entry/41'

Example: delete all entries at this path​

A limit of -1 deletes matching entries at the exact path and leaves descendants intact. The clients expose this operation as deleteAll().

curl --fail-with-body \
--request DELETE \
'http://localhost:8080/assets/user/123/profile-picture?limit=-1'

Label filters​

Filter bulk deletion with labels, using the same label syntax as fetch requests:

DELETE /assets/users/123/profile?limit=-1&label:phone=iphone
DELETE /assets/users/123/-/recursive?label:phone=iphone

For the clients, apply matchingLabels(...) before deleteAll() or deleteRecursively(). Supply ordinary label keys, such as phone; the client adds label: to the query parameters. Ordering does not affect either bulk operation.

Deleting Recursively​

Use the recursive selector without a limit to delete entries at a path and its descendants.

DELETE /assets/users/123/-/recursive

Example​

curl --fail-with-body \
--request DELETE \
'http://localhost:8080/assets/user/123/profile-picture/-/recursive'

Response​

A valid request returns 204 No Content with no response body, including when no entries match. Invalid selections or limits return 400 Bad Request; Konifer leaves the assets intact.

Retries​

An entry-specific DELETE targets the same entry on each attempt. Konifer does not reuse a deleted entry ID, so a retry cannot delete a replacement upload at the same path.

Exact-path and recursive bulk requests evaluate matching assets when you execute each request. Repeating a bulk request after new matching uploads arrive can delete those uploads. Use a list of entry IDs for a fixed selection.

Error codes​

API failures return JSON with a stable code and an optional message. See Error Responses for the codes, HTTP statuses, and client compatibility behavior.