Skip to main content
A branch is a second working draft of an agent, cut from its main draft (what the App calls Development), so a change can be prepared apart and landed in one step. Merging is a fast-forward only: a branch lands while main has not moved since the branch was cut or last rebased, and otherwise it must be rebased first. Nothing here publishes; after a merge, main’s draft is published the usual way (Agents). These are /v2 compatibility routes (API overview). {agent_id} is the Sempera agent id, and a branch id is a UUID. Writes need the operator or owner role. A branch reads id, agent_id, name, base_version_id, created_by, created_at and behind, which is true once main has moved past the point the branch was cut from or last rebased onto. A branch name is 1 to 64 letters, digits, dots, underscores or dashes, unique among the agent’s open branches. dev, latest, staging, production and version-like names such as 1.2.3 are reserved.

​
Rebase and merge

Branches are compared one draft setting at a time, with the instructions document counting as one setting. The preview answers {"dev_head_version_id", "up_to_date", "auto_merged", "changes", "conflicts"}: changes are settings only main changed, taken automatically; conflicts are settings both sides changed differently. Each item carries id (setting:<key>), key, label, base and theirs (main’s value); a conflict adds ours (the branch’s value).
Every conflict needs a resolution: "ours", "theirs" or {"value": ...}, a new value that passes the same checks a draft edit does. The merged result becomes the branch’s draft and its base moves to main’s head. The answer is {"version", "auto_merged", "resolved"}. If main moved since the preview, the rebase is refused and you preview again. A merge takes no body and answers {"version", "merged_fields"}, the settings the branch changed.

​
Refusals

Answers use the compatibility envelope {"data": ..., "errors": null}; a refusal these routes make is {"data": null, "errors": [{"error", "message"}]}. A missing credential, scope or role, and a request body that is not a JSON object, get the standard error envelope (Errors and limits). Editing a branch’s own draft is done in the Sempera App today; PATCH /v1/agents/{id}/draft edits main.