---
title: "Create a branch"
method: POST
path: "/agent/{id}/branches"
tags: ["Agent Versioning - Branches"]
---

# Create a branch

`POST /agent/{id}/branches`

Fork a new branch from an existing branch. The source branch must have at least one committed revision. Branch names are unique per agent; the name `Main` is reserved for the default branch. Creating from a branch whose latest draft is still `scanning` returns `409 source_scanning`.

## Path parameters

- `id` string, required

## Request body

- CreateBranchRequest
  - `sourceBranchId` string, required — Branch to fork from. Its head revision must exist.
  - `name` string, required — New branch name. Unique per agent among active branches. `main` is reserved.

## Response `201`

Branch created.

- object
  - `status` boolean
  - `data` Branch — An `AgentBranch` document. An editable copy of an agent with its own draft slot and revision chain.
    - `_id` string — Branch ID (24-character ObjectId).
    - `agent` string — ID of the agent this branch belongs to.
    - `name` string — Branch name (unique per agent among active branches). `main` is reserved for the default branch.
    - `isDefault` boolean — True for the seeded `main` branch. The default branch cannot be renamed or archived.
    - `sourceBranchId` string, nullable — Head of the source branch at fork time. `null` for `main`.
    - `sourceRevisionId` string, nullable — Revision the branch was forked from. `null` for `main`.
    - `headRevisionId` string, nullable — ID of the branch's latest committed revision. `null` until the first commit.
    - `openDraftId` string, nullable — ID of the branch's single open draft. `null` when no draft is open.
    - `status` 'active' | 'archived' — Archived branches are hidden from list views and cannot receive draft edits or be made live.
    - `createdBy` string
    - `updatedBy` string
    - `createdAt` string, date-time
    - `updatedAt` string, date-time

## Other responses

- `400` — Invalid input
- `401` — Unauthorized access
- `403` — Forbidden access
- `404` — Resource not found. The referenced ID does not exist or does not belong to the caller's organization.
- `409` — Conflict. The request cannot be completed because of the current state of the resource (name already exists, another publish or restore is in progress, the source draft failed its security scan, or a similar in-flight collision).
- `423` — Locked. A configuration freeze is active on this agent, or the resource is temporarily locked for another write. Retry after the freeze window ends.
- `500` — Internal server error

---

[API](https://skmtc.net/smallest-inc/apis/agent-management-api.md) · [All operations](https://skmtc.net/smallest-inc/apis/agent-management-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/smallest-inc/agent-management-api/revisions/c2d0eb64b01a/schema)