# Create branch

`POST https://api.instacloud.com/projects/{projectId}/branches`

**Token scope:** `account` · `org` · `project` — read-only tokens refused (not a GET).

Create a branch (database branch + Tigris fork + cloned compute groups, or empty)

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `projectId` | path | `string` | yes |  |

## Request body (application/json)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | yes | lower-kebab: a-z, 0-9, hyphen (max 39) |
| `from` | `string` | no | parent branch name |
| `empty` | `boolean` | no | create the branch and nothing else: none of the parent's services are forked and none of its branch-scoped secrets are copied (project-scoped secrets still apply). `from` only sets the parent link. |

## Response 201

Default Response

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `branch` | `object` | no |  |
| `branch.id` | `string` | no |  |
| `branch.project_id` | `string` | no |  |
| `branch.name` | `string` | no |  |
| `branch.parent_branch_id` | `string \| null` | no |  |
| `branch.is_default` | `boolean` | no |  |
| `branch.status` | `"creating" \| "active" \| "error" \| "deleting"` | no |  |
| `branch.created_at` | `string` | no |  |
| `nextActions` | `object[]` | no |  |
| `nextActions.op` | `string` | yes | Neutral logical action id, e.g. "service.add" — NOT an operationId or a CLI/MCP tool name; each client maps it to its own surface. |
| `nextActions.reason` | `string` | yes | Natural-language, human/LLM-facing "why do this now". |
| `nextActions.args` | `object` | no | Suggested, flat named arguments; "<placeholder>"s where a value is unknown. |
| `nextActions.gated` | `boolean` | no | True if the action passes a governance gate. |

## Response 202

Default Response

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | `string` | yes |  |
| `approvalId` | `string` | yes |  |
| `action` | `string` | yes |  |
| `actions` | `string[]` | yes |  |
| `message` | `string` | yes |  |
| `url` | `string` | yes |  |

## Response 400

Default Response

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | `string` | yes |  |

## Response 403

Default Response

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | `string` | yes |  |

## Response 409

Default Response

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | `string` | yes |  |

## Response 429

Default Response

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | `string` | yes |  |