---
title: "Create a branch"
method: POST
path: "/organizations/{organization}/databases/{database}/branches"
tags: ["Database branches"]
---

# Create a branch

`POST /organizations/{organization}/databases/{database}/branches`

### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:

**Service Token Accesses**
 `create_branch`, `restore_production_branch_backup`, `restore_backup`

**OAuth Scopes**

 | Resource | Scopes |
| :------- | :---------- |
| Organization | `write_branches`, `restore_production_branch_backups`, `restore_backups` |
| Database | `write_branches`, `restore_production_branch_backups`, `restore_backups` |
| Branch | `restore_backups` |

## Path parameters

- `organization` string, required
- `database` string, required

## Request body

- object
  - `name` string, required — The name of the branch
  - `parent_branch` string, required — Parent branch
  - `backup_id` string — If provided, restores the backup's schema and data to the new branch. Must have `restore_production_branch_backup(s)` or `restore_backup(s)` access to do this.
  - `region` string — The region to create the branch in. If not provided, the branch will be created in the default region for its database.
  - `restore_point` string — Restore from a point-in-time recovery timestamp (e.g. 2023-01-01T00:00:00Z). Available only for PostgreSQL databases.
  - `seed_data` 'last_successful_backup' — If provided, restores the last successful backup's schema and data to the new branch. Must have `restore_production_branch_backup(s)` or `restore_backup(s)` access to do this, in addition to Data Branching™ being enabled for the branch.
  - `cluster_size` string — The database cluster size is required if a backup_id is provided. Options: PS_10, PS_20, PS_40, ..., PS_2800

## Response `201`

Returns the created branch

- object
  - `id` string, required — The ID of the branch
  - `name` string, required — The name of the branch
  - `created_at` string, required — When the branch was created
  - `updated_at` string, required — When the branch was last updated
  - `deleted_at` string, required — When the branch was deleted
  - `restore_checklist_completed_at` string, required — When a user last marked a backup restore checklist as completed
  - `schema_last_updated_at` string, required — When the schema for the branch was last updated
  - `kind` 'mysql' | 'postgresql', required — The kind of branch
  - `mysql_address` string, required — The MySQL address for the branch
  - `mysql_edge_address` string, required — The address of the MySQL provider for the branch
  - `state` 'pending' | 'sleep_in_progress' | 'sleeping' | 'awakening' | 'ready', required — The current state of the branch
  - `direct_vtgate` boolean, required — True if the branch allows passwords to connect directly to a vtgate, bypassing load balancers
  - `vtgate_size` string, required — The size of the vtgate cluster for the branch
  - `vtgate_count` number, required — The number of vtgate instances in the branch
  - `cluster_name` string, required — The SKU representing the branch's cluster size
  - `cluster_iops` number, required — IOPS for the cluster
  - `ready` boolean, required — Whether or not the branch is ready to serve queries
  - `schema_ready` boolean, required — Whether or not the schema is ready for queries
  - `metal` boolean, required — Whether or not this is a metal database
  - `production` boolean, required — Whether or not the branch is a production branch
  - `safe_migrations` boolean, required — Whether or not the branch has safe migrations enabled
  - `sharded` boolean, required — Whether or not the branch is sharded
  - `shard_count` number, required — The number of shards in the branch
  - `stale_schema` boolean, required — Whether or not the branch has a stale schema
  - `actor` object, required
    - `id` string, required — The ID of the actor
    - `display_name` string, required — The name of the actor
    - `avatar_url` string, required — The URL of the actor's avatar
  - `restored_from_branch` object, required
    - `id` string, required — The ID for the resource
    - `name` string, required — The name for the resource
    - `created_at` string, required — When the resource was created
    - `updated_at` string, required — When the resource was last updated
    - `deleted_at` string, required — When the resource was deleted, if deleted
  - `private_edge_connectivity` boolean, required — True if private connections are enabled
  - `has_replicas` boolean, required — True if the branch has replica servers
  - `has_read_only_replicas` boolean, required — True if the branch has read-only replica servers
  - `html_url` string, required — Planetscale app URL for the branch
  - `url` string, required — Planetscale API URL for the branch
  - `region` object, required
    - `id` string, required — The ID of the region
    - `provider` string, required — Provider for the region (ex. AWS)
    - `enabled` boolean, required — Whether or not the region is currently active
    - `public_ip_addresses` string[], required — Public IP addresses for the region
    - `display_name` string, required — Name of the region
    - `location` string, required — Location of the region
    - `slug` string, required — The slug of the region
    - `current_default` boolean, required — True if the region is the default for new branch creation
  - `parent_branch` string, required — The name of the parent branch from which the branch was created

## Other responses

- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `500` — Internal Server Error

---

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