Skip to main content
Neon Docs

Search documentation

Type to search this documentation.

Create branch

POST/projects/{project_id}/branchesCreate branch

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.

Parameters

project_idstringpathrequired

The Neon project ID

pattern ^[a-z0-9-]{1,60}$

Request body

application/json
value
allOf · 2 options
Option 1objectBranchCreateRequest
branchobject

Optional configuration for the new branch, for example `name`, `parent_id` (fork from a branch), `parent_lsn` or `parent_timestamp` (point-in-time branching), and `protected`.

Show child attributes
archivedboolean

Whether to create the branch in the archived state. When omitted, the branch is created as a normal (non-archived) branch.

expires_atstring · 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.

init_sourcestring

Source of initialization for the branch. `parent-data` copies schema and data from the parent branch. `parent-schema` copies schema only from the parent branch. `schema-only` creates a new root branch containing schema only, using `parent_id` as the source; optionally, `parent_lsn` or `parent_timestamp` can narrow the source point. `import` initializes the branch from an external import.

namestring

The branch name

maxLength 256 · minLength 1

parent_idstring

The `branch_id` of the parent branch. If omitted or empty, the branch will be created from the project's default branch.

pattern ^[a-z0-9-]{1,60}$

parent_lsnstring

A Log Sequence Number (LSN) on the parent branch. The branch will be created with data from this LSN.

parent_timestampstring · 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. RFC 3339 format.

protectedboolean

Whether the branch is protected. Protected branches (and their computes) cannot be deleted, archived, or reset, and block deletion of the project. Can be gated by `protected_branches_only` in the IP allowlist. Paid plans only.

default false

endpointsarray of object

Compute endpoints to create together with the branch. If omitted, the branch is created without any compute endpoint. Endpoints can be added to the branch separately after creation.

Show child attributes
Show array items
autoscaling_limit_max_cunumber

minimum 0.25

autoscaling_limit_min_cunumber

minimum 0.25

provisionerstring
settingsobject

A collection of settings for a compute endpoint

Show child attributes
pg_settingsobject

A raw representation of Postgres settings

pgbouncer_settingsobject

Deprecated. A raw representation of PgBouncer settings. Removal scheduled for June 20, 2026.

preload_librariesobject

The shared libraries to preload into the project's compute instances.

Show child attributes
enabled_librariesarray of string

Names of shared preload libraries to enable for the project.

Show child attributes
use_defaultsboolean

When true, the project's preload libraries include the platform default set in addition to any libraries listed in `enabled_libraries`.

suspend_timeout_secondsinteger · 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).

maximum 604800 · minimum -1

typestringrequired

Compute endpoint type. `read_write`: the primary read-write endpoint (one per branch). `read_only`: a read replica endpoint (multiple allowed per branch).

one of "read_only", "read_write"

Option 2objectAnnotationCreateValueRequest
annotation_valueobject

A free-form map of string key-value pairs for attaching metadata to a resource (for example, a git commit reference). Maximum 50 entries.

maxProperties 50

Example request
{
  "branch": {
    "name": "mybranch",
    "parent_id": "br-aged-salad-637688"
  }
}

Responses

201Created a branch. An endpoint is only created if it was specified in the request.application/json
value
allOf · 6 options
Option 1objectBranchResponse
branchobjectrequired
Show child attributes
active_time_secondsinteger · int64required

Total time this branch's compute has been active during the current billing period, in seconds (not weighted by compute size). Distinct from `compute_time_seconds`, which is CU-weighted.

compute_time_secondsinteger · int64required

Total Postgres compute time consumed by this branch during the current billing period, in CU-seconds (weighted by compute size). Divide by 3600 for CU-hours.

cpu_used_secinteger · int64required

Deprecated. Use `compute_time_seconds` instead. CPU seconds used by all of the branch's compute endpoints, including deleted ones. This value is reset at the beginning of each billing period.

created_atstring · date-timerequired

A timestamp indicating when the branch was created

created_byobject

The resolved user model that contains details of the user/org/integration/api_key used for branch creation. This field is filled only in listing/get/create/get/update/delete methods, if it is empty when calling other handlers, it does not mean that it is empty in the system.

Show child attributes
imagestring

The URL to the user's avatar image.

namestring

Display name of the user who created the branch.

creation_sourcestringrequired

The branch creation source

current_statestringrequired

The branch’s state, indicating if it is initializing, ready for use, or archived. * 'init' - the branch is being created but is not available for querying. * 'resetting' - the branch is being reset to a specific point in time or LSN and is not yet available for querying. * 'ready' - the branch is fully operational and ready for querying. Expect normal query response times. * 'archived' - the branch is stored in cost-effective archival Postgres storage. Expect slow query response times.

data_transfer_bytesinteger · int64required

Total data transferred out of the branch, in bytes. Used as a consumption metric.

defaultbooleanrequired

Whether the branch is the project's default branch

expires_atstring · 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.

idstringrequired

The branch ID. This value is generated when a branch is created. A `branch_id` value has a `br` prefix. For example: `br-small-term-683261`.

pattern ^[a-z0-9-]{1,60}$

init_sourcestring

Source of initialization for the branch. `parent-data` (default) copies schema and data from the parent. `parent-schema` copies schema only from the parent. `schema-only` creates a root branch with schema only. `import` initializes from an external import.

last_reset_atstring · date-time

A timestamp indicating when the branch was last reset

logical_sizeinteger · int64

The logical size of the branch, in bytes

namestringrequired

The branch name

parent_idstring

The `branch_id` of the parent branch

pattern ^[a-z0-9-]{1,60}$

parent_lsnstring

The Log Sequence Number (LSN) on the parent branch from which this branch was created. When restoring a branch using the `POST /projects/{project_id}/branches/{branch_id}/restore` endpoint, this value isn’t finalized until all operations related to the restore have completed successfully.

parent_timestampstring · date-time

The point in time on the parent branch from which this branch was created. When restoring a branch using the `POST /projects/{project_id}/branches/{branch_id}/restore` endpoint, this value isn’t finalized until all operations related to the restore have completed successfully. After all the operations completed, this value might stay empty.

pending_statestring

The branch’s state, indicating if it is initializing, ready for use, or archived. * 'init' - the branch is being created but is not available for querying. * 'resetting' - the branch is being reset to a specific point in time or LSN and is not yet available for querying. * 'ready' - the branch is fully operational and ready for querying. Expect normal query response times. * 'archived' - the branch is stored in cost-effective archival Postgres storage. Expect slow query response times.

primaryboolean

Deprecated. Use the `default` field. Whether the branch is the project's primary branch.

project_idstringrequired

The ID of the project this branch belongs to.

pattern ^[a-z0-9-]{1,60}$

protectedbooleanrequired

Whether the branch is protected. Protected branches (and their computes) cannot be deleted, archived, or reset, and block deletion of the project.

recoveryobject

Recovery information for a deleted branch. Only present when listing deleted branches with `include_deleted=true`. This is part of the Branch Recovery feature, which is in preview and not available to all users.

Show child attributes
deleted_atstring · date-timerequired

Timestamp when the branch was deleted

deletion_methodstringrequired

How the branch was deleted: 'user' for manual deletion, 'ttl' for TTL expiration

one of "user", "ttl"

recoverable_untilstring · date-timerequired

Timestamp when the recovery window expires and the branch will be permanently deleted

restore_statusstring

Could be `restored`, `finalized` or `detaching`. A `restored` branch becomes permanently `finalized` when you call `finalizeRestoreBranch` A `restored` or `finalized` branch may begin `detaching` as a one-time performance optimisation, after which it will continue in its original state

restored_asstring

ID of the target branch which was replaced when this branch was restored

restored_fromstring

ID of the snapshot that was the restore source for this branch

restricted_actionsarray of object

A list of actions that are currently restricted for this branch and the reason why.

Show child attributes
Show array items

An action that is currently restricted for the branch and the reason why.

namestringrequired

The name of a restricted action on a branch. `restore`: the branch cannot be used as a restore target. `delete-rw-endpoint`: the read-write endpoint for the branch cannot be deleted.

reasonstringrequired

A human-readable explanation of why the action is restricted.

state_changed_atstring · date-timerequired

A UTC timestamp indicating when the `current_state` began

ttl_interval_secondsinteger

The time-to-live (TTL) duration originally configured for the branch, in seconds. This read-only value represents the interval between the time `expires_at` was set and the expiration timestamp itself. It is preserved to ensure the same TTL duration is reapplied when resetting the branch from its parent, and only updates when a new `expires_at` value is set. Access to this feature is currently limited to participants in the Early Access Program.

updated_atstring · date-timerequired

A timestamp indicating when the branch was last updated

written_data_bytesinteger · int64required

Data written by this branch during the current billing period, in bytes.

Option 2objectEndpointsResponse
endpointsarray of objectrequired

Compute endpoints in the project. Each includes `id`, `branch_id`, `host`, and `type`.

Show child attributes
Show array items
autoscaling_limit_max_cunumberrequired

minimum 0.25

autoscaling_limit_min_cunumberrequired

minimum 0.25

branch_idstringrequired

The ID of the branch this compute endpoint belongs to.

pattern ^[a-z0-9-]{1,60}$

compute_release_versionstring

Attached compute's release version number.

created_atstring · date-timerequired

A timestamp indicating when the compute endpoint was created

creation_sourcestringrequired

The compute endpoint creation source

current_statestringrequired

Lifecycle state of the compute endpoint. `init`: being initialized. `active`: running and accepting connections. `idle`: suspended (scaled to zero).

one of "init", "active", "idle"

disabledbooleanrequired

Whether to restrict connections to the compute endpoint. Enabling this option schedules a suspend compute operation. A disabled compute endpoint cannot be enabled by a connection or console action.

hoststringrequired

The hostname of the compute endpoint. This is the hostname specified when connecting to a Neon database.

idstringrequired

The compute endpoint ID. Compute endpoint IDs have an `ep-` prefix. For example: `ep-little-smoke-851426`

pattern ^[a-z0-9-]{1,60}$

last_activestring · date-time

A timestamp indicating when the compute endpoint was last active

namestring

Optional name of the compute endpoint

passwordless_accessbooleanrequired

Whether to permit passwordless access to the compute endpoint

pending_statestring

Lifecycle state of the compute endpoint. `init`: being initialized. `active`: running and accepting connections. `idle`: suspended (scaled to zero).

one of "init", "active", "idle"

pooler_enabledbooleanrequired

Deprecated. To use connection pooling, append `-pooler` to the endpoint ID in the connection string.

pooler_modestringrequired

Deprecated. The connection pooler mode. Neon supports PgBouncer in `transaction` mode only. Removal scheduled for June 20, 2026.

one of "transaction"

project_idstringrequired

The ID of the project this compute endpoint belongs to.

pattern ^[a-z0-9-]{1,60}$

provisionerstringrequired
proxy_hoststringrequired

Deprecated. Use the `host` property instead.

region_idstringrequired

Cloud region where the resource's Postgres compute and storage reside (for example, `aws-us-east-1`). Valid values are returned by `GET /regions`.

settingsobjectrequiredEndpointSettingsData ↑

A collection of settings for a compute endpoint

started_atstring · date-time

A timestamp indicating when the compute endpoint was last started

suspend_timeout_secondsinteger · int64required

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).

maximum 604800 · minimum -1

suspended_atstring · date-time

A timestamp indicating when the compute endpoint was last suspended

typestringrequired

Compute endpoint type. `read_write`: the primary read-write endpoint (one per branch). `read_only`: a read replica endpoint (multiple allowed per branch).

one of "read_only", "read_write"

updated_atstring · date-timerequired

A timestamp indicating when the compute endpoint was last updated

Option 3objectOperationsResponse
operationsarray of objectrequired
Show child attributes
Show array items

An asynchronous action Neon performs on your resources (for example, starting a compute or creating a branch). Fields such as `action`, `status`, and `total_duration_ms` describe the operation and its progress.

actionstringrequired

The action performed by the operation

one of "create_compute", "create_timeline", "start_compute", "suspend_compute", "apply_config", "check_availability", "delete_timeline", "create_branch", "import_data", "tenant_ignore", "tenant_attach", "tenant_detach", "tenant_detach_safekeepers", "tenant_attach_safekeepers", "tenant_reattach", "replace_safekeeper", "disable_maintenance", "apply_storage_config", "prepare_secondary_pageserver", "switch_pageserver", "detach_parent_branch", "timeline_archive", "timeline_unarchive", "start_reserved_compute", "sync_dbs_and_roles_from_compute", "apply_schema_from_branch", "timeline_mark_invisible", "timeline_update_protected_config", "prewarm_replica", "promote_replica", "set_storage_non_dirty", "swap_binding_id", "finalize_migration", "mark_migration_prepared", "update_catalog", "epc_sync"

branch_idstring

The ID of the branch this operation ran on.

pattern ^[a-z0-9-]{1,60}$

created_atstring · date-timerequired

A timestamp indicating when the operation was created

endpoint_idstring

The ID of the compute endpoint this operation ran on.

pattern ^[a-z0-9-]{1,60}$

errorstring

Human-readable message describing why the operation failed.

failures_countinteger · int32required

The number of times the operation failed

idstring · uuidrequired

The operation ID

project_idstringrequired

The ID of the project this operation ran on.

pattern ^[a-z0-9-]{1,60}$

retry_atstring · date-time

A timestamp indicating when the operation was last retried

statusstringrequired

Lifecycle state of the operation. `scheduling`: queued, not yet started. `running`: actively executing. `finished`: completed successfully. `failed`: ended with a failure. `error`: ended with a terminal error. `cancelling`: cancellation requested but not yet complete. `cancelled`: stopped before completion. `skipped`: bypassed without executing.

one of "scheduling", "running", "finished", "failed", "error", "cancelling", "cancelled", "skipped"

total_duration_msinteger · int32required

The total duration of the operation in milliseconds

updated_atstring · date-timerequired

A timestamp indicating when the operation status was last updated

Option 4objectRolesResponse
rolesarray of objectrequired

Roles belonging to the branch. Each role includes fields such as `branch_id`, `name`, `protected`, `created_at`, and `updated_at`.

Show child attributes
Show array items
authentication_methodstring

Authentication method configured for this role: `password`, `oauth`, or `no_login`.

branch_idstringrequired

The ID of the branch this role belongs to.

pattern ^[a-z0-9-]{1,60}$

created_atstring · date-timerequired

A timestamp indicating when the role was created

namestringrequired

Postgres role name within the branch.

passwordstring

The role password

protectedboolean

Whether or not the role is system-protected

updated_atstring · date-timerequired

A timestamp indicating when the role was last updated

Option 5objectDatabasesResponse
databasesarray of objectrequired

Databases on the branch. Each includes `id`, `name`, `owner_name`, and `created_at`.

Show child attributes
Show array items
branch_idstringrequired

The ID of the branch this database belongs to.

pattern ^[a-z0-9-]{1,60}$

created_atstring · date-timerequired

A timestamp indicating when the database was created

idinteger · int64required

The database ID

namestringrequired

The database name

owner_namestringrequired

The name of role that owns the database

updated_atstring · date-timerequired

A timestamp indicating when the database was last updated

Option 6objectConnectionURIsOptionalResponse
connection_urisarray of object

Connection URIs for the compute endpoint, including credentials.

Show child attributes
Show array items
connection_parametersobjectrequired
Show child attributes
databasestringrequired

Name of the Postgres database used in the connection URI.

hoststringrequired

Hostname of the compute endpoint. Use `pooler_host` for the pooled connection hostname.

passwordstringrequired

Authentication password for the role, used in the connection URI.

pooler_hoststringrequired

PgBouncer (transaction mode) pooled host, the `-pooler` variant of `host`. Connect through it to work around the Postgres `max_connections` limit for serverless or connection-per-request workloads.

rolestringrequired

Postgres role used to authenticate the database connection.

connection_uristringrequired

The connection URI is defined as specified here: [Connection URIs](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING-URIS) The connection URI can be used to connect to a Postgres database with psql or defined in a DATABASE_URL environment variable. When creating a branch from a parent with more than one role or database, the response body does not include a connection URI.

Example response
{
  "branch": {
    "active_time_seconds": 922200,
    "compute_time_seconds": 823880990,
    "cpu_used_sec": 461100,
    "created_at": "2022-11-30T19:09:48Z",
    "creation_source": "console",
    "current_state": "ready",
    "data_transfer_bytes": 72911987,
    "default": true,
    "id": "br-wispy-meadow-118737",
    "init_source": "parent-data",
    "name": "dev2",
    "parent_id": "br-aged-salad-637688",
    "parent_lsn": "0/1DE2850",
    "project_id": "spring-example-302709",
    "protected": false,
    "state_changed_at": "2022-11-30T20:09:48Z",
    "updated_at": "2022-12-01T19:53:05Z",
    "written_data_bytes": 542998300
  },
  "connection_uris": [
    {
      "connection_parameters": {
        "database": "string",
        "host": "string",
        "password": "",
        "pooler_host": "string",
        "role": "string"
      },
      "connection_uri": "string"
    }
  ],
  "databases": [
    {
      "branch_id": "br-wispy-meadow-118737",
      "created_at": "2022-11-30T18:25:15Z",
      "id": 834686,
      "name": "neondb",
      "owner_name": "casey",
      "updated_at": "2022-11-30T18:25:15Z"
    }
  ],
  "endpoints": [
    {
      "autoscaling_limit_max_cu": 1,
      "autoscaling_limit_min_cu": 1,
      "branch_id": "br-wispy-meadow-118737",
      "created_at": "2022-12-03T15:37:07Z",
      "creation_source": "console",
      "current_state": "init",
      "disabled": false,
      "host": "ep-silent-smoke-806639.us-east-2.aws.neon.tech",
      "id": "ep-silent-smoke-806639",
      "name": "My cool compute",
      "passwordless_access": true,
      "pending_state": "active",
      "pooler_enabled": false,
      "pooler_mode": "transaction",
      "project_id": "spring-example-302709",
      "provisioner": "k8s-neonvm",
      "proxy_host": "us-east-2.aws.neon.tech",
      "region_id": "aws-us-east-2",
      "settings": {
        "pg_settings": {}
      },
      "suspend_timeout_seconds": 0,
      "type": "read_write",
      "updated_at": "2022-12-03T15:37:07Z"
    }
  ],
  "operations": [
    {
      "action": "start_compute",
      "branch_id": "br-wispy-meadow-118737",
      "created_at": "2022-11-15T20:02:00Z",
      "endpoint_id": "ep-silent-smoke-806639",
      "failures_count": 0,
      "id": "d8ac46eb-a757-42b1-9907-f78322ee394e",
      "project_id": "spring-example-302709",
      "status": "finished",
      "total_duration_ms": 200,
      "updated_at": "2022-11-15T20:02:02Z"
    }
  ],
  "roles": [
    {
      "branch_id": "br-wispy-meadow-118737",
      "created_at": "2022-11-23T17:42:25Z",
      "name": "casey",
      "protected": false,
      "updated_at": "2022-11-23T17:42:25Z"
    }
  ]
}
defaultGeneral 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. application/json
objectGeneralError
codestringrequired

default ""

messagestringrequired

Error message

request_idstring

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.

Example response
{
  "code": "",
  "message": "string",
  "request_id": "string"
}
Documentation menu