Open weight models are particularly fast in the Neon AI Gateway thanks to optimizations like prompt caching. Free to run during beta
Neon
    Docs
    Log inSign up
    /APIs & SDKs/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. RFC 3339 format.

    Protectedbranch.*
    protected
    booleandefault: false

    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.

    Archivedbranch.*
    archived
    boolean

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

    Init sourcebranch.*
    init_source
    string

    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.

    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