Skip to main content
DELETE
Permanently delete a file
Permanently deletes a file, along with its analysis, its reports, and every conversation that used it, including file comparisons. You can delete a file that is live or already archived. A successful call returns 204 No Content.
This endpoint requires the permanent file deletion feature to be enabled for your organisation. Without it, the API returns 403 with request.organisations.feature-flag.not-enabled. Learn more.
Deletion is irreversible; there is no restore endpoint. Confirm the action before calling this endpoint.

Permission

Requires organisation_files:purge, which the Owner role holds by default. A caller without it receives 403 with request.cases.case-file.action-not-permitted. To delete a file you did not upload, you also need organisation_files:read; otherwise the API returns 404. An API key never counts as the uploader of a file, so it always needs both permissions. A key granted organisation_files:purge is treated as also holding organisation_files:read, so purge alone is enough.

Archive or Delete

Archive a file to remove it from view and keep its data. Delete it when the data itself must be erased. If the same document was uploaded more than once, its uploads can share some analysis outputs, such as reports. A shared output is erased when the last file that uses it is deleted.

Best Practices

  1. Wait for processing to finish: A file can only be deleted once its analysis has finished. Deleting it earlier returns 409 Conflict with request.cases.case-file.not-ready-for-deletion; try again shortly.
  2. Call again after a 502: If the API cannot erase every stored copy, it returns 502 with request.cases.case-file.delete-failed. The file is already hidden and cannot be used again. Call the endpoint again to finish deleting it.
  3. Treat 404 after a retry as done: Once a deletion has completed, further calls return 404 Not Found.

Audit Log

Each deletion is recorded in your organisation’s audit log as file.deleted, with the file ID, the case, and the conversations that were deleted. The file name is not recorded.

Authorizations

x-api-key
string
header
required

Path Parameters

fileId
string
required

File ID

caseId
string
required

Case ID

Response

File permanently deleted