Skip to main content
A branch is a forkable timeline of an agent’s configuration. Every agent has one branch by default — Main — which is the published surface that serves production traffic. From any version on any branch you can create a new branch, edit its draft, publish new versions onto it, and eventually merge the result back into Main. A branch owns:
  • A name unique to the agent while it’s not archived.
  • A head version that points at the most recently published version on the branch.
  • A parent version that records the version the branch was forked from (null for Main).
  • An archived state that hides the branch from listings without deleting it.
  • A creator — the user who first created it.
Branches don’t carry per-branch traffic splits yet — only the default branch (Main) is live (is_live: true, traffic_percentage: 100). Non-default branches always report is_live: false and traffic_percentage: 0 until a future spec adds deployments.

​
Lifecycle

​
Naming rules

  • 1–140 characters of letters, numbers, spaces, underscores, hyphens, dots, slashes, and ()[]{}.
  • The literal name main (any casing) is reserved for the default branch.
  • A name conflict with an existing active branch on the same agent returns 400 branch_name_in_use. Archived branches don’t count, so you can re-use a name after archiving the previous owner.

​
Authorization

All branch endpoints are organization-scoped. They read the requester’s active organization from the session and only return branches whose parent agent belongs to it. Cross-tenant lookups return 404 agent_not_found — there is no enumeration distinction between “wrong org” and “doesn’t exist.” Sessions without an active organization return 404 no_active_organization. Mutating endpoints (PATCH, POST .../merge) additionally require organization-admin permission and return 403 not_admin for non-admins.
  • Drafts — per-user, per-branch in-progress edits and the publish path.
  • Versions — the immutable history each branch accumulates.