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

# Rename a branch

`PATCH /agent/{id}/branches/{branchId}`

Rename a non-default, non-archived branch. `Main` cannot be renamed; a name that is already in use on this agent returns `409 branch_name_exists`.

## Path parameters

- `id` string, required
- `branchId` string, required

## Request body

- RenameBranchRequest
  - `name` string, required

## Response `200`

Renamed.

- 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. Attempting to rename `Main`, or the caller lacks write 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)