Merge a branch (merge-by-replay)

POST

/v1/branches/{id}/merge

curl --request POST \
  --url https://api.aerandil.com/v1/branches/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/merge \
  --header 'Authorization: Bearer <token>'

• Production API

Merge an open branch into main by replaying its action journal through the engine against the current main state — validators and all — in one atomic transaction. A fast-fail staleness check runs first: any copy-on-first-write row whose base has moved (or been deleted) since the fork aborts the merge with a structured conflict (409), never a row-level three-way merge. On success the branch is marked merged (recording the umbrella merge_correlation_id), its delta rows are deleted, and a branch.merged event lands on the main log. Accepts Idempotency-Key. Because the replay may fire any journaled action, this requires the actions:apply catch-all scope.

Authorizations

• aerandil_oauth

Parameters

Path Parameters

id

required

string format: uuid

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.

Responses

200

Merged. replayed lists each journal entry’s fresh main-log correlation id.

Media typeapplication/json

object

branch_id

required

string format: uuid

merge_correlation_id

required

string format: uuid

name

required

string

replayed

required

Array<object>

object

action

required

string

correlation_id

required

string format: uuid

ordinal

required

integer

warnings

Array<object>

object

Example^generated

{
  "branch_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "merge_correlation_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "name": "example",
  "replayed": [
    {
      "action": "example",
      "correlation_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
      "ordinal": 1
    }
  ],
  "warnings": [
    {}
  ]
}

404

No such branch under this tenant.

409

Branch is not open, or the staleness check found conflicts against main.