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

# Create Agent Branch

> Create a branch off the agent's dev head.

### Overview

Cuts a new branch from the agent's newest dev version. Versions saved to the branch stay off the dev timeline until you land them with [Merge Agent Branch](https://docs.bland.ai/api-v2/post/agents-id-branches-branch-id-merge.md). Use [List Agent Branches](https://docs.bland.ai/api-v2/get/agents-id-branches.md) to see what is open.

Requires an admin, owner, operator, or prompter role.

### Headers

**authorization** `string` *required*

Your API key for authentication.

### Path Parameters

**agent\_id** `string` *required*

The agent's unique identifier.

### Body Parameters

**name** `string` *required*

The branch name. Trimmed, then must be 1 to 64 characters using only letters, numbers, dots, underscores, and dashes. The names `dev`, `latest`, `staging`, and `production` (any casing) and anything shaped like a version number (for example `1.2.0`) are reserved for version selectors. Any of these problems returns `400 INVALID_NAME` with a message naming the rule. Returns `409 BRANCH_EXISTS` when an open branch already has this name; names of merged or deleted branches can be reused.

### Response

Returns `201` on success.

**data** `object`

The new branch.

**branch object**

**id** `string`

Unique identifier for the branch. Pass it as `{branch_id}` on the other branch endpoints.

**agent\_id** `string`

The agent the branch belongs to.

**name** `string`

The trimmed branch name.

**base\_version\_id** `string | null`

The dev version the branch was cut from. `null` when the agent has no saved versions yet.

**created\_by** `string | null`

ID of the user who created the branch, or `null` when created with an org-level key.

**created\_at** `string`

ISO 8601 timestamp of creation.

**behind** `boolean`

Always `false` on a newly created branch.

**errors** `null | array`

`null` on success, or a list of error objects if the request failed.

```json Response theme={null}
{
  "data": {
    "id": "08aacbb3-6f83-4542-a7c0-1fd07b5b3d47",
    "agent_id": "f4f9fe3f-a996-49a6-934d-6b78b144d43b",
    "name": "billing-questions",
    "base_version_id": "0b6b3dba-0c8c-4ee2-a992-4a7bc2f35e25",
    "created_by": "0d5eee46-6f39-462b-b347-79ff13cf3cf2",
    "created_at": "2026-09-10T17:42:18.093Z",
    "behind": false
  },
  "errors": null
}
```

```json Invalid Name theme={null}
{
  "data": null,
  "errors": [
    {
      "error": "INVALID_NAME",
      "message": "\"staging\" is reserved for version selectors"
    }
  ]
}
```

```json Conflict theme={null}
{
  "data": null,
  "errors": [
    {
      "error": "BRANCH_EXISTS",
      "message": "An open branch with this name already exists"
    }
  ]
}
```

```json Not Found theme={null}
{
  "data": null,
  "errors": [
    {
      "error": "NOT_FOUND",
      "message": "Agent not found"
    }
  ]
}
```

***

Docs for agents: [llms.txt](https://docs.bland.ai/llms.txt)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.