Create Revision

Create a new draft revision for a blob. The blob’s default revision moves to it immediately.

POST /blobs/:org_id/:blob_id/revisions

Requires Write access to the blob. The default revision must be in commit phase — a blob with a draft already default has nothing to branch from, since a blob has at most one draft.

Path Parameters

Parameter	Type	Required	Description
org_id	string	Yes	The unique ID of the organization.
blob_id	string	Yes	The unique ID or alias of the blob.

Request Body

Parameter	Type	Required	Description
comment	string	Yes	1–200 characters. No other field is accepted.

Response

Parameter	Type	Description
revision_id	string	The unique ID of the new revision.

The revision takes its slot in the blob’s platform.revisions_per_blob in the same step that creates its record, so a refused request takes none. If handing the record to the async worker that provisions its content fails, the revision is marked failed. A failed revision keeps its slot until it is deleted.

Errors

Status	Error	Cause
400	invalid_request_body	comment is missing, empty, over 200 characters, or an extra field was sent.
403	forbidden	The blob is absent, not visible to this key, or the key lacks Write access.
409	blob_not_ready	The blob is being created or deleted.
409	default_revision_not_committed	The default revision is not in commit phase — most often because it is already the draft.
400	limit_exceeded	The blob already holds as many revisions as platform.revisions_per_blob allows, a failed one included. See When a limit is reached.

Example

Request

curl -X POST https://api.blobhub.io/v1/blobs/org_123/blob_789/revisions \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"comment": "add the refund branch"}'

See also

• The lifecycle — phase and status as two axes.
• Commit Revision — how this draft is sealed.