--- operationId: "createProjectBranch" method: "POST" path: "/projects/{project_id}/branches" tag: "branches" interfaces: ["api", "sdk", "cli", "mcp", "console"] --- > API Reference / Branches / Create branch ## POST /projects/{project_id}/branches Creates a branch in the specified project. No request body is required, but you can specify one to create a compute endpoint or select a non-default parent branch. By default, the branch is created from the project's default branch with no compute endpoint, and the branch name is auto-generated. To access the branch, add a `read_write` endpoint. Each branch supports one read-write endpoint and multiple read-only endpoints. For related information, see [Manage branches](https://neon.com/docs/manage/branches/). ### Parameters - `project_id` (string, path, required) The Neon project ID ### Request body - `endpoints` (array, optional) - `type` (string, required) The compute endpoint type. Either `read_write` or `read_only`. Possible values: `read_only`, `read_write` - `settings` (object, optional) A collection of settings for a compute endpoint - `pg_settings` (object, optional) A raw representation of Postgres settings - `pgbouncer_settings` (object, optional, deprecated) DEPRECATED. PgBouncer settings for the compute endpoint. This field is deprecated and will be removed after 2026-06-20. - `preload_libraries` (object, optional) The shared libraries to preload into the project's compute instances. - `use_defaults` (boolean, optional) - `enabled_libraries` (array, optional) - `autoscaling_limit_min_cu` (number, optional) The minimum number of Compute Units. The minimum value is `0.25`. See [Compute size and Autoscaling configuration](https://neon.com/docs/manage/endpoints#compute-size-and-autoscaling-configuration) for more information. - `autoscaling_limit_max_cu` (number, optional) The maximum number of Compute Units. See [Compute size and Autoscaling configuration](https://neon.com/docs/manage/endpoints#compute-size-and-autoscaling-configuration) for more information. - `provisioner` (string, optional) The Neon compute provisioner. Specify the `k8s-neonvm` provisioner to create a compute endpoint that supports Autoscaling. Provisioner can be one of the following values: * k8s-pod * k8s-neonvm * serverless-platform Clients must expect, that any string value that is not documented in the description above should be treated as a error. UNKNOWN value if safe to treat as an error too. - `suspend_timeout_seconds` (integer, optional, format: int64) Duration of inactivity in seconds after which the compute endpoint is automatically suspended. The value `0` means use the default value. The value `-1` means never suspend. The default value is `300` seconds (5 minutes). The minimum value is `60` seconds (1 minute). The maximum value is `604800` seconds (1 week). For more information, see [Scale to zero configuration](https://neon.com/docs/manage/endpoints#scale-to-zero-configuration). - `branch` (object, optional) - `parent_id` (string, optional) The `branch_id` of the parent branch. If omitted or empty, the branch will be created from the project's default branch. - `name` (string, optional) The branch name - `parent_lsn` (string, optional) A Log Sequence Number (LSN) on the parent branch. The branch will be created with data from this LSN. - `parent_timestamp` (string, optional, format: date-time) A timestamp identifying a point in time on the parent branch. The branch will be created with data starting from this point in time. The timestamp must be provided in ISO 8601 format; for example: `2024-02-26T12:00:00Z`. - `protected` (boolean, optional) Whether the branch is protected - `archived` (boolean, optional) Whether to create the branch as archived - `init_source` (string, optional) The source of initialization for the branch. Valid values are `schema-only` and `parent-data` (default). * `schema-only` - creates a new root branch containing only the schema. Use `parent_id` to specify the source branch. Optionally, you can provide `parent_lsn` or `parent_timestamp` to branch from a specific point in time or LSN. These fields define which branch to copy the schema from and at what point—they do not establish a parent-child relationship between the `parent_id` branch and the new schema-only branch. * `parent-data` - creates the branch with both schema and data from the parent. - `expires_at` (string, optional, format: date-time) The timestamp when the branch is scheduled to expire and be automatically deleted. Must be set by the client following the [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6) format with precision up to seconds (such as 2025-06-09T18:02:16Z). Deletion is performed by a background job and may not occur exactly at the specified time. Access to this feature is currently limited to participants in the Early Access Program. - `annotation_value` (object, optional) Annotation properties. ```json { "branch": { "name": "my-feature-branch" } } ``` ### Response (201) ```json { "branch": { "id": "br-young-forest-a5b6c7d8", "project_id": "aged-wildflower-123456", "parent_id": "br-young-forest-a5b6c7d8", "parent_lsn": "0/1964220", "name": "my-branch-2", "slug": "br-young-forest-a5b6c7d8", "project_slug": "aged-wildflower-123456", "current_state": "init", "pending_state": "ready", "state_changed_at": "2025-01-15T10:30:00Z", "creation_source": "console", "primary": false, "default": false, "protected": false, "cpu_used_sec": 0, "compute_time_seconds": 0, "active_time_seconds": 0, "written_data_bytes": 0, "data_transfer_bytes": 0, "created_at": "2025-01-15T10:30:00Z", "updated_at": "2025-01-15T10:30:00Z", "init_source": "parent-data" }, "endpoints": [], "operations": [ { "id": "00000000-0000-0000-0000-000000000000", "project_id": "aged-wildflower-123456", "branch_id": "br-young-forest-a5b6c7d8", "action": "create_branch", "status": "running", "failures_count": 0, "created_at": "2025-01-15T10:30:00Z", "updated_at": "2025-01-15T10:30:00Z", "total_duration_ms": 0 }, { "id": "00000000-0000-0000-0000-000000000000", "project_id": "aged-wildflower-123456", "branch_id": "br-young-forest-a5b6c7d8", "action": "timeline_update_protected_config", "status": "scheduling", "failures_count": 0, "created_at": "2025-01-15T10:30:00Z", "updated_at": "2025-01-15T10:30:00Z", "total_duration_ms": 0 } ], "roles": [ { "branch_id": "br-young-forest-a5b6c7d8", "name": "neondb_owner", "protected": false, "authentication_method": "password", "created_at": "2025-01-15T10:30:00Z", "updated_at": "2025-01-15T10:30:00Z" }, { "branch_id": "br-young-forest-a5b6c7d8", "name": "authenticator", "protected": false, "authentication_method": "password", "created_at": "2025-01-15T10:30:00Z", "updated_at": "2025-01-15T10:30:00Z" }, { "branch_id": "br-young-forest-a5b6c7d8", "name": "anonymous", "protected": false, "authentication_method": "no_login", "created_at": "2025-01-15T10:30:00Z", "updated_at": "2025-01-15T10:30:00Z" }, { "branch_id": "br-young-forest-a5b6c7d8", "name": "authenticated", "protected": false, "authentication_method": "no_login", "created_at": "2025-01-15T10:30:00Z", "updated_at": "2025-01-15T10:30:00Z" } ], "databases": [ { "id": 1636596, "branch_id": "br-young-forest-a5b6c7d8", "name": "neondb", "owner_name": "neondb_owner", "created_at": "2025-01-15T10:30:00Z", "updated_at": "2025-01-15T10:30:00Z" } ] } ``` ### Code examples ```bash curl "https://console.neon.tech/api/v2/projects/$PROJECT_ID/branches" \ -X POST \ -H "Authorization: Bearer $NEON_API_KEY" \ -H "Content-Type: application/json" \ -d '{"branch":{"name":"my-feature-branch"}}' ``` ```typescript import { createNeonClient, raw } from '@neon/sdk'; const neon = createNeonClient({ apiKey: process.env.NEON_API_KEY }); const { data } = await raw.createProjectBranch({ client: neon.client, path: { project_id: process.env.PROJECT_ID }, body: { branch: { name: "my-feature-branch" } } }); ``` ```bash # neonctl neon branches create ``` ### MCP Tool: `create_branch` Create a branch in a Neon project for isolated development or testing. By default the branch is created from the project's default branch; pass `parentId` to fork an existing non-default branch instead (e.g. to make a disposable copy of a dev/staging branch). - `projectId` (string, required) The ID of the project to create the branch in - `branchName` (string, optional) An optional name for the branch - `parentId` (string, optional) An optional branch ID (e.g. 'br-...') to branch from. If omitted, the branch is created from the project's default branch. Use this to fork an existing non-default branch — for example, to make an isolated copy of a dev/staging branch for experimentation. ### Console Console path: Projects → Branches → New branch ### Errors **default** General Error. The request may or may not be safe to retry, depending on the HTTP method, response status code, and whether a response was received. - If no response is returned from the API, a network error or timeout likely occurred. - In some cases, the request may have reached the server and been successfully processed, but the response failed to reach the client. As a result, retrying non-idempotent requests can lead to unintended results. The following HTTP methods are considered non-idempotent: `POST`, `PATCH`, `DELETE`, and `PUT`. Retrying these methods is generally **not safe**. The following methods are considered idempotent: `GET`, `HEAD`, and `OPTIONS`. Retrying these methods is **safe** in the event of a network error or timeout. Any request that returns a `503 Service Unavailable` response is always safe to retry. Any request that returns a `423 Locked` response is safe to retry. `423 Locked` indicates that the resource is temporarily locked, for example, due to another operation in progress. - `request_id` (string, optional) Unique identifier for the request, useful for debugging. You can set this value manually by including an `X-Request-ID` header in the request. If not provided, the value will be generated automatically. - `code` (string, required) Default: `` - `message` (string, required) Error message