> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeptar.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Branches overview

> Branches let you fork an agent, iterate independently, and merge back into Main.

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

```mermaid theme={null}
flowchart LR
  Fork([POST /v1/agents/:agentId/branches]) --> Draft[(Edit drafts on the branch)]
  Draft --> Publish([POST /v1/agents/:agentId/branches/:branchId/publish])
  Publish --> Merge([POST /v1/agents/:agentId/branches/:branchId/merge])
  Publish --> Archive([PATCH /v1/agents/:agentId/branches/:branchId])
  Merge --> Main[(Main updated)]
```

## 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.

## Related guides

* [Drafts](/api-reference/drafts/overview) — per-user, per-branch in-progress edits and the publish path.
* [Versions](/api-reference/versions/overview) — the immutable history each branch accumulates.