Branches and events

Fork session branches and append events with optimistic concurrency. Compare-and-swap on branch version and head event id prevents silent history rewrites.

Branches are explicit and append-only. Every event append uses optimistic concurrency: you state the expected_version and expected_head_event_id you are writing against, and a mismatch returns 409 branch_version_conflict rather than silently rewriting history. Branches are prefixed br_ and events evt_. See branches and the sessions and branching guide.

All requests require a bearer API key. See authentication.

Fork a branch

POST /v2/sessions/{session_id}/branches

Creates a new branch off an existing one, optionally pinned to a specific event so the fork inherits exactly the history up to that point.

session_idstringpathrequired

The session the branch belongs to.

fork_from_branch_idstringrequired

The br_... branch to fork from. Must belong to this session.

fork_from_event_idstring

Optional evt_... event on the source branch to fork at. When set, it must belong to the fork-source branch, and the new branch's head is pinned there. When omitted, the new branch inherits the source branch's current head.

curl https://api.zumik.ai/v2/sessions/ses_01jy7n7w2z9pcu7a5q2gh8askm/branches \
  -H "Authorization: Bearer $ZUMIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fork_from_branch_id": "br_01jy7n7w30ardv8b6r3jk9btln",
    "fork_from_event_id": "evt_01jy7naa12b3c4d5e6f7g8h9jk"
  }'

{
  "id": "br_01jy7nbb45c6d7e8f9g0h1j2km",
  "object": "session_branch",
  "session_id": "ses_01jy7n7w2z9pcu7a5q2gh8askm",
  "parent_branch_id": "br_01jy7n7w30ardv8b6r3jk9btln",
  "forked_from_event_id": "evt_01jy7naa12b3c4d5e6f7g8h9jk",
  "head_event_id": "evt_01jy7naa12b3c4d5e6f7g8h9jk",
  "version": 3
}

idstring

Opaque branch id, prefixed br_.

objectstring

Always session_branch.

session_idstring

The owning session.

parent_branch_idstring

The branch this one was forked from, or null for a root branch.

forked_from_event_idstring

The event the fork was pinned at, or null.

head_event_idstring

The current head event, or null on an empty branch.

versioninteger

The branch's monotonic version. Inherited from the parent at fork time.

Retrieve a branch

GET /v2/sessions/{session_id}/branches/{branch_id}

session_idstringpathrequired

The session the branch belongs to.

branch_idstringpathrequired

The branch to fetch.

curl https://api.zumik.ai/v2/sessions/ses_01jy7n7w2z9pcu7a5q2gh8askm/branches/br_01jy7n7w30ardv8b6r3jk9btln \
  -H "Authorization: Bearer $ZUMIK_API_KEY"

Returns the same branch object as fork. Read it first to learn the current version and head_event_id before appending.

Append an event

POST /v2/sessions/{session_id}/branches/{branch_id}/events

Appends one immutable event. The append succeeds only if your stated expected_version and expected_head_event_id match the branch's current state; otherwise it fails with 409 branch_version_conflict and the branch is left untouched. On success the branch version increments by one and its head advances to the new event.

session_idstringpathrequired

The session the branch belongs to.

branch_idstringpathrequired

The branch to append to.

expected_versionintegerrequired

The branch version you are writing against. Use the version from a recent retrieve. A root branch starts at 0.

expected_head_event_idstring

The evt_... you expect to be the current head, or null when the branch is empty. Must match the branch's actual head.

eventobjectrequired

The event to append.

event

event_typestringrequired

One of user_message, assistant_message, tool_result, retrieval_result, checkpoint, note.

payload_refstring

Optional art_... artifact holding the event payload. Must exist in this project.

curl https://api.zumik.ai/v2/sessions/ses_01jy7n7w2z9pcu7a5q2gh8askm/branches/br_01jy7n7w30ardv8b6r3jk9btln/events \
  -H "Authorization: Bearer $ZUMIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "expected_version": 0,
    "expected_head_event_id": null,
    "event": {
      "event_type": "user_message",
      "payload_ref": "art_01jy7n3q8v6kzr4w2m9bd5xpfh"
    }
  }'

{
  "id": "evt_01jy7naa12b3c4d5e6f7g8h9jk",
  "object": "session_event",
  "session_id": "ses_01jy7n7w2z9pcu7a5q2gh8askm",
  "branch_id": "br_01jy7n7w30ardv8b6r3jk9btln",
  "sequence": 1,
  "event_type": "user_message",
  "parent_event_id": null,
  "payload_ref": "art_01jy7n3q8v6kzr4w2m9bd5xpfh",
  "created_at": "2026-06-15T16:08:33Z"
}

idstring

Opaque event id, prefixed evt_.

objectstring

Always session_event.

session_idstring

The owning session.

branch_idstring

The branch the event was appended to.

sequenceinteger

The event's position on the branch (the new branch version).

event_typestring

The event type, echoed back.

parent_event_idstring

The prior head event, or null for the first event.

payload_refstring

The referenced artifact, or null.

created_atstring

RFC 3339 creation timestamp.

Handling a conflict

When another writer advanced the branch first, the append fails:

{
  "error": {
    "message": "Branch 'br_01jy7n7w30ardv8b6r3jk9btln' is at version 1 with head Some(\"evt_...\"), not the expected version/head.",
    "type": "invalid_request_error",
    "code": "branch_version_conflict"
  }
}

Re-read the branch to learn the new version and head_event_id, rebase your intended event onto that head, and retry.

Errors

Status	Code	When
400	`invalid_request_error`	The fork source branch or event does not belong to the session, or `event.payload_ref` does not exist in this project.
401	`invalid_api_key`	Missing or invalid API key.
404	`invalid_request_error`	The session or branch does not exist in this project.
409	`branch_version_conflict`	`expected_version` or `expected_head_event_id` did not match the branch's current state.

See the full table on errors.

Branches and events

Fork a branch

Retrieve a branch

Append an event

Handling a conflict

Errors

On this page