From ae4ea05a37bb482872130f564894f6cff59ad22d Mon Sep 17 00:00:00 2001 From: Kris Zyp Date: Wed, 22 Jul 2026 08:58:53 -0600 Subject: [PATCH] Document get_deployment_payload / delete_deployment_payload response contracts MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Companion to HarperFast/harper#1898 (which implements the two operations — they were documented but returned "Operation not found", harper#1893): raw-bytes response for get_deployment_payload, and the terminal-status requirement, idempotency, response shape, and audit event for delete_deployment_payload. Co-Authored-By: Claude Opus 4.8 --- reference/operations-api/operations.md | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) 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.