POST/documents/{documentId}/purge
Purge a document
Operation documents.purge
Description
Permanently removes a document through a signed document.purge event that cites its exact current authorizing container path. Requires write access, a document linked to exactly one container, and a document that is not a container's metadata document. The server keeps the signed proof, and blobs only this document referenced enter the attachment-retention grace period; a 202 asks the client to retry the identical request after policy history is prepared.
Authentication
Requires a signed-in session: the client sends its session token as a bearer token in the Authorization header.
Parameters
| Name | In | Type | Details |
|---|---|---|---|
documentId | path | string | required |
Request body
application/jsonDocumentPurgeRequest
A signed document.purge citing the exact current path that authorizes it.
3 fields
- 1 to 100 items
Root-to-container path of the document's only linked container.
bodyany JSON valuerequiredeventobject with any fieldsrequired
Other fields are allowed.
Responses
200 OK
application/jsonDocumentPurgeResponse
The purge proof. Blobs only this document referenced are soft-deleted and reclaimed later by garbage collection.
10 fields
- at least 1 item
documentIdstringrequired- not empty
purgedAtstringrequired- not empty
reclaimedBlobStorageKeyslist of stringrequiredObject-store keys reclaimed during the request; currently always empty, because reclamation is deferred.
Other fields are allowed.
202 The attempted operation rolled back. Retry the identical request to continue verification preparation.
application/jsonPrincipalHistoryPreparationResponse
A 202: the operation rolled back while the server prepares principal history. Retry the identical request.
3 fields
codestringrequired- always
principal_history_preparation_pending
- always
committedbooleanrequired- always
false
- always
progressTokenstringrequired- exactly 64 characters
- lowercase hexadecimal
Changes when preparation advances; clients stop after three identical tokens in a row.
Other responses
| Status | Meaning | Body |
|---|---|---|
| 400 | Bad Request |
|
| 401 | Unauthorized |
|
| 402 | Payment Required |
|
| 403 | Forbidden |
|
| 404 | Not Found |
|
| 409 | Conflict |
|
| 500 | Internal Server Error |
|
| 503 | Service Unavailable |
|
Additional rules
The server also enforces these rules, which the schema above cannot express.
A 503 with code principal_history_preparation_unavailable requires committed:false; other 503 responses do not guarantee rollback.