---
title: "Create a new branch"
method: POST
path: "/organizations/{organizationID}/projects/{projectID}/branches"
tags: ["Branches"]
---

# Create a new branch

`POST /organizations/{organizationID}/projects/{projectID}/branches`

Creates a new branch within the specified project. Branches can be created from scratch or derived from an existing parent branch.

## Path parameters

- `organizationID` string, required
- `projectID` string, required

## Request body

- union — Details required when creating a new branch
  - object
    - `name` string, required — Human-readable name for the new branch
    - `description` string — Optional description for the branch purpose or contents (max 50 characters)
    - `scaleToZero` ScaleToZeroConfiguration — Configuration for scaling branches to zero when not in use
      - `enabled` boolean, required — Whether scale to zero is enabled
      - `inactivityPeriodMinutes` integer, required — Duration in minutes after which branches will be hibernated if not accessed
    - `backupConfiguration` BackupConfiguration — Details about the branch continuous backup configuration
      - `retentionPeriod` integer — how long are we keeping the backups around for
      - `backupTime` string — time of day/week when we are taking a full backup
    - `mode` 'inherit', required — The mode used to discriminate between types of branches.
    - `parentID` string, required — If present, the branch will inherit the parent branch configuration and data
  - object
    - `name` string, required — Human-readable name for the new branch
    - `description` string — Optional description for the branch purpose or contents (max 50 characters)
    - `scaleToZero` ScaleToZeroConfiguration — Configuration for scaling branches to zero when not in use
      - `enabled` boolean, required — Whether scale to zero is enabled
      - `inactivityPeriodMinutes` integer, required — Duration in minutes after which branches will be hibernated if not accessed
    - `backupConfiguration` BackupConfiguration — Details about the branch continuous backup configuration
      - `retentionPeriod` integer — how long are we keeping the backups around for
      - `backupTime` string — time of day/week when we are taking a full backup
    - `mode` 'custom', required — The mode used to discriminate between types of branches.
    - `configuration` ClusterConfiguration, required — Configuration details for a database cluster backing a branch
      - `region` string, required — Geographic region where the cluster will be deployed
      - `storage` integer — Branch storage in GiB (gigabytes)
      - `instanceType` string, required — The instance type according to the xata instance types available
      - `image` string, required — PostgreSQL image to use for the database instances
      - `replicas` integer, required — Number of replicas in the branch. Every child branch is created with no replicas. This can be updated.
      - `postgresConfigurationParameters` object — Arbitrary PostgreSQL configuration parameters for the cluster
      - `preloadLibraries` string[] — List of PostgreSQL extensions and libraries to preload

## Response `201`

Branch successfully created

- BranchShortMetadata — Basic metadata about a branch, used in response to create/update operations
  - `id` string, required — Unique identifier for the branch
  - `name` string, required — Human-readable name of the branch
  - `description` string — Optional description of the branch purpose or contents
  - `createdAt` string, date-time, required — Timestamp when the branch was created
  - `updatedAt` string, date-time, required — Timestamp when the branch was last updated
  - `parentID` string, nullable — Identifier of the parent branch if this is a derived branch, null otherwise
  - `connectionString` string, nullable — Deprecated: retrieve the connection string from the branch credentials endpoint (GET .../branches/{branchID}/credentials) instead.
  - `region` string, required — Geographic region where the branch is deployed
  - `publicAccess` boolean, required — Whether the branch allows public access without authentication

## Other responses

- `400` — Generic error response for most error conditions
- `401` — Error response when authentication or authorization fails
- `404` — Generic error response for most error conditions
- `412` — Error response when a precondition for the request is not met
- `5XX` — Unexpected Error
- `default` — Unexpected Error

---

[API](https://skmtc.net/xataio/apis/xata-api.md) · [All operations](https://skmtc.net/xataio/apis/xata-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/xataio/xata-api/versions/bbeb83bf32d6/schema)