diff --git a/reference/operations-api/operations.md b/reference/operations-api/operations.md
index e958e881..a0f30a23 100644
--- a/reference/operations-api/operations.md
+++ b/reference/operations-api/operations.md
@@ -697,9 +697,11 @@ Returns the raw tarball for a deployment. Useful for inspecting or re-deploying
 }
 ```
 
+The response is the raw tarball bytes (`Content-Type: application/octet-stream`, with a `Content-Disposition` download filename) - not JSON and not base64-encoded, so payloads of any size stream without inflation. Returns `404` if the deployment does not exist or its payload has already been reclaimed (by payload retention or `delete_deployment_payload`).
+
 ### `delete_deployment_payload`
 
-Removes the tarball blob from a deployment record. The deployment record itself is retained; only the binary payload is deleted. Use this to reclaim storage after confirming a deployment is stable.
+Removes the tarball blob from a deployment record. The deployment record itself is retained; only the binary payload is deleted. Use this to reclaim storage after confirming a deployment is stable. The deletion replicates, so one call frees the payload's storage on every node in the cluster.
 
 ```json
 {
@@ -708,6 +710,18 @@ Removes the tarball blob from a deployment record. The deployment record itself
 }
 ```
 
+Response:
+
+```json
+{
+	"message": "Deleted payload for deployment 'a3f8c2d1...'",
+	"deployment_id": "a3f8c2d1...",
+	"freed_bytes": 52428800
+}
+```
+
+The deployment must be in a terminal status (`success`, `failed`, or `rolled_back`); deleting the payload of an in-progress deployment fails with `409`, since its payload may still be replicating to peers. Deleting an already-reclaimed payload succeeds with `freed_bytes: 0` (the operation is idempotent). A `payload_dropped` entry recording the deleting user is appended to the deployment's `event_log`.
+
 ### `add_ssh_key`
 
 Adds an SSH key (must be ed25519) for authenticating deployments from private repositories.