Delete Revision

There is one DELETE route. What it does depends on the revision: deleting a committed, non-default revision is exactly that, but deleting the draft (which is always the default) discards it instead — the draft itself disappears and the blob’s default pointer moves back to its parent, or to the newest other revision that is usable. The web labels these two outcomes Delete and Discard; the wire call is identical.

DELETE `/revisions/:id`

Requires Admin access to the revision’s blob — the one lifecycle operation with a higher bar than Write.

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	The unique ID of the revision.

The matrix

The revision is	`DELETE` does	Error if refused
`managed` (a scheduler blob’s single revision)	refused	`revision_not_writable`
status `creating`, `committing` or `deleting` (a worker is already operating on it)	refused	`revision_not_ready`
committed, ready, not the default	deletes it; the default pointer does not move	—
the draft (always the default), ready, with a `parent_id`	discards it; the pointer moves to the parent if it is usable, else to the newest usable revision	—
failed, not the default	deletes it as cleanup, whatever phase it failed in	—
the committed default, status ready	refused — there is nothing wrong with it, and deleting it would leave the blob with no usable content	`cant_delete_default_revision`
the draft with no `parent_id` (a blob’s initial revision)	refused — there is nothing to discard back to	`cant_discard_initial_revision`
the draft, has a `parent_id`, but nothing else on the blob is committed and ready	refused — there is nothing usable left to point at	`cant_discard_last_revision`

“Usable” means committed and ready. Resolving where the pointer goes on a discard walks the blob’s revisions newest-first, skipping unusable ones, so one usable revision behind a page of unusable ones is still found.

What is deleted with it

Deleting or discarding a revision deletes everything that belongs to it — its sessions, executions, objects and threads. A blob’s other revisions are untouched.

Response

Returns {"status": "success"} — no body beyond the status. The revision moves to deleting synchronously and the row itself disappears once the async worker finishes.

Errors

Status	Error	Cause
404	`revision_not_found`	The id is unknown, or the caller cannot reach its blob.
403	`forbidden`	The revision’s blob is not visible to this key, or the key lacks Admin access.
409	`blob_not_ready`	The blob is being created or deleted.
409	`revision_not_writable`	The revision’s phase is `managed`.
409	`revision_not_ready`	The revision’s status is mid-flight (not `ready` or `failed`), or it changed between the read and the write.
409	`cant_delete_default_revision`	Row 6 of the matrix above.
409	`cant_discard_initial_revision`	Row 7 of the matrix above.
409	`cant_discard_last_revision`	Row 8 of the matrix above.

Example

curl -X DELETE https://api.blobhub.io/v1/revisions/rev_old \
  -H "X-API-Key: $ADMIN_API_KEY"

{
  "status": "success"
}

`failed_operation`: which operation left a revision `failed`

Three flows land a revision at status: failed: a failed create, a failed commit (whose rollback moves phase back to draft), and a failed discard or delete. All three can leave phase: draft / status: failed with nothing on the row to say which one happened — so failed_operation records it.

`failed_operation`	Written by	`phase` left behind	Recovery
`create`	a failed Create Revision	`draft`	Reset or Delete — there is no Retry, since the create that failed left nothing to re-issue.
`commit`	a failed Commit Revision	`draft`	Reset, then Commit again.
`delete`	a failed Delete or Discard	`draft` (discard) or `commit` (delete)	Reset, then Delete/Discard again.

failed_operation is absent on every revision written before this field existed, and on every revision that never failed — treat an absent value on a failed revision as “failed, cause unknown”, and offer Reset and Delete without a labelled retry. It is cleared automatically the moment status returns to ready (through Reset), so a recovered revision never carries a stale cause.

REST API

WebSocket API

Delete Revision

DELETE `/revisions/:id`

Path Parameters

The matrix

What is deleted with it

Response

Errors

Example

`failed_operation`: which operation left a revision `failed`

See also

​DELETE /revisions/:id

​Path Parameters

​The matrix

​What is deleted with it

​Response

​Errors

​Example

​failed_operation: which operation left a revision failed

​See also

DELETE `/revisions/:id`

Path Parameters

The matrix

What is deleted with it

Response

Errors

Example

`failed_operation`: which operation left a revision `failed`

See also