Autoscaling Report: Production databases on Neon use 2.4x less compute and 50% less cost than if they were running on a provisioned platform.
Neon
    Docs
    Log inSign up
    /API reference/Branches/Create branch
    POST/projects/{project_id}/branches

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

    Markdown for AI context

    Quick start

    REST API - curl
    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"}}'

    Every field below is optional. An empty body works too.

    Also available in
    neon branches create --name my-feature-branch

    Parameters

    Project ID
    project_id
    string

    The Neon project ID

    Request body

    Branch

    branch.*
    8 fields

    Where the branch starts from and how it's identified.

    Branch namebranch.*
    name
    string

    The branch name

    ≥1 chars, ≤256 chars

    Parent branchbranch.*
    parent_id
    string

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

    Parent LSNbranch.*
    parent_lsn
    string

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

    Parent timestampbranch.*
    parent_timestamp
    string

    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.

    Protectedbranch.*
    protected
    boolean

    Whether the branch is protected

    Archivedbranch.*
    archived
    boolean

    Whether to create the branch as archived

    Init sourcebranch.*
    init_source
    string

    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 atbranch.*
    expires_at
    string

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

    Compute endpoint

    1 field

    Compute endpoint(s) created on the new branch.

    Annotations

    1 field

    Optional key-value metadata stored on the branch.

    Response

    201

    Created a branch. An endpoint is only created if it was specified in the request.

    Depth

    Errors

    default

    General error

    This endpoint can return the standard Neon API error response.

    Response fields

    • message Required. Human-readable error message.
    • code Required. Machine-readable error code.
    • request_id Optional. Request identifier for debugging. You can provide one with the X-Request-ID header.

    Retry guidance

    If no response is returned, the request may still have reached the server. This is why retry safety depends on the method and status code.

    Idempotent methods (GET, HEAD, OPTIONS) are generally safe to retry after a network error or timeout. Non-idempotent methods (POST, PATCH, DELETE, PUT) can change state, so avoid automatic retries unless your workflow can tolerate duplicate effects.

    Responses with 423 Locked or 503 Service Unavailable are safe to retry. 423 Locked means the resource is temporarily locked, usually because another operation is in progress.

    Was this page helpful?
    Previous List branchesNext Create anonymized branch

    On this page

    Copy neon init command