Create (fork) a branch

POST

/v1/branches

curl --request POST \
  --url https://api.aerandil.com/v1/branches \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "example" }'

• Production API

Fork a new open branch at the head of the caller-tenant’s event stream. Sibling delta tables carry copy-on-first-write overlay rows; the base plane pays zero tax. At most one open branch per name per tenant — a merged or discarded branch frees its name. Accepts Idempotency-Key. Requires objects:write.

Authorizations

• aerandil_oauth

Parameters

Header Parameters

Idempotency-Key

string

>= 1 characters

Opaque idempotency token (Stripe-shape). Repeated POSTs with the same key replay the original response within the cache TTL rather than creating a duplicate object.

Request Body^required

Media typeapplication/json

object

name

required

Unique among the tenant’s open branches.

string

>= 1 characters <= 200 characters

Example^generated

{
  "name": "example"
}

Responses

201

Branch forked.

Media typeapplication/json

object

created_at

required

string format: date-time

forked_at_seq

required

The caller-tenant’s event-stream head seq at fork (fork-from-head only).

integer

id

required

string format: uuid

last_write_at

string format: date-time

merge_correlation_id

Present on a merged branch: the correlation id stamped on the branch.merged event and shared by every replayed main-log write, tying the merge record to the replayed events.

string format: uuid

merged_at

string format: date-time

name

required

string

status

required

string

Allowed values: open merged

Example

{
  "status": "open"
}

409

A branch with this name is already open.

422

Invalid branch name.