Document Engine provides three ways to remove assets: delete one document, delete multiple documents, or clean up leftover assets.
Removing a single file
Send a request to the delete endpoint with the document ID. Document Engine deletes the document and removes its associated assets.
A successful request returns 200 OK. If Document Engine can’t find or access the document, it returns an error.
In Document Engine 1.19.0 and later, POST /api/cleanup also removes orphaned annotation attachments that were uploaded before a layer synchronization but never linked to a record. Run cleanup once after upgrading to reclaim attachments orphaned before this release.
In Document Engine 1.18.1, concurrent individual deletions can leave assets in storage after Document Engine deletes their documents. Each request still returns 200 OK. To reclaim these assets, call POST /api/cleanup. The endpoint removes assets that no document or layer references. For details, refer to the removing leftover assets section.
Removing multiple files
To delete multiple documents, use the bulk deletion endpoint. You can filter documents by title, document ID, or creation date range.
Include at least one filter. Otherwise, Document Engine rejects the request with 400 Bad Request to prevent accidental mass deletion.
Removing leftover assets
After Document Engine deletes a document record, it removes the associated assets in the background. To run cleanup on demand, use the asset cleanup endpoint. The endpoint scans asset storage for assets that background cleanup didn’t remove.
Cleanup removes PDF assets that no document or layer references. However, a known issue in Document Engine 1.16–1.18 can cause cleanup to remove a shared S3 PDF asset when stored metadata omits the region. Before deleting documents or running cleanup on an affected version, refer to the shared S3 PDF asset known issue.
Run cleanup to reclaim leftover assets or free space before running VACUUM on a PostgreSQL database that stores assets. A release note may also ask you to run cleanup after an upgrade. You don’t need to run it after bulk deletion because the bulk deletion job runs cleanup when it finishes.
The endpoint requires your secret key and takes no parameters:
curl -X POST https://your-document-engine/api/cleanup \ -H "Authorization: Token token=<your secret key>"The request is synchronous. Document Engine returns a response when cleanup finishes:
{ "success": 81, "failure": 0 }success counts asset-removal attempts. If you enable fallback storage, Document Engine attempts to remove each asset from every backend. The count can exceed the number of assets removed.
failure counts assets that Document Engine checked but kept. A nonzero value doesn’t always indicate an error. Document Engine doesn’t check assets that it knows are still in use, so those assets appear in neither count. The count includes assets without a stored source-file checksum and assets whose backend rejected deletion. Document Engine tries to restore assets when a backend rejects deletion. Check the Document Engine log to identify the cause.
If cleanup has no assets to reclaim, both values are 0. You can call the endpoint again safely.
If cleanup fails, the endpoint returns 500 with a reason in the response body. For example, :failed_to_fetch_assets means the endpoint couldn’t read the asset table. Check the Document Engine log for the underlying database error. Resolve the error before retrying the request.
Keep in mind
- Use filters — Specify filters when deleting documents in bulk to target the intended documents.
- Back up important documents — Deletion is permanent and can’t be undone.
- Use ISO 8601 dates — Format date parameters as ISO 8601, such as
2025-05-13T17:00:00Z.