---
title: "Create a database branch"
method: POST
path: "/v1/projects/{ref}/branches"
tags: ["Environments"]
---

# Create a database branch

`POST /v1/projects/{ref}/branches`

Creates a database branch from the specified project.

## Path parameters

- `ref` string, required

## Request body

- CreateBranchBody
  - `branch_name` string, required
  - `git_branch` string
  - `is_default` boolean
  - `persistent` boolean
  - `region` string
  - `desired_instance_size` 'pico' | 'nano' | 'micro' | 'small' | 'medium' | 'large' | 'xlarge' | '2xlarge' | '4xlarge' | '8xlarge' | '12xlarge' | '16xlarge' | '24xlarge' | '24xlarge_optimized_memory' | '24xlarge_optimized_cpu' | '24xlarge_high_memory' | '48xlarge' | '48xlarge_optimized_memory' | '48xlarge_optimized_cpu' | '48xlarge_high_memory'
  - `release_channel` 'internal' | 'alpha' | 'beta' | 'ga' | 'withdrawn' | 'preview' — Release channel. If not provided, GA will be used.
  - `postgres_engine` '15' | '17' | '17-oriole' — Postgres engine version. If not provided, the latest version will be used.
  - `secrets` object
  - `with_data` boolean
  - `notify_url` string, uri — HTTP endpoint to receive branch status updates.

## Response `201`

- BranchResponse
  - `id` string, uuid, required
  - `name` string, required
  - `project_ref` string, required
  - `parent_project_ref` string, required
  - `is_default` boolean, required
  - `git_branch` string
  - `pr_number` integer
  - `latest_check_run_id` number — This field is deprecated and will not be populated.
  - `persistent` boolean, required
  - `status` 'CREATING_PROJECT' | 'RUNNING_MIGRATIONS' | 'MIGRATIONS_PASSED' | 'MIGRATIONS_FAILED' | 'FUNCTIONS_DEPLOYED' | 'FUNCTIONS_FAILED', required — This field is deprecated. List action runs to get branch status instead.
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required
  - `review_requested_at` string, date-time
  - `with_data` boolean, required
  - `notify_url` string, uri
  - `deletion_scheduled_at` string, date-time
  - `preview_project_status` 'INACTIVE' | 'ACTIVE_HEALTHY' | 'ACTIVE_UNHEALTHY' | 'COMING_UP' | 'UNKNOWN' | 'GOING_DOWN' | 'INIT_FAILED' | 'REMOVED' | 'RESTORING' | 'UPGRADING' | 'PAUSING' | 'RESTORE_FAILED' | 'RESTARTING' | 'PAUSE_FAILED' | 'RESIZING'

## Other responses

- `500` — Failed to create database branch

---

[API](https://skmtc.dev/supabase/apis/management-api.md) · [All operations](https://skmtc.dev/supabase/apis/management-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/supabase/management-api/revisions/a7cb39418064/schema)