v17

latestOpenAPI 3.0.1raw.githubusercontent.com2026-07-08165682.0 MB

Database branches

Create a branch

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

post/organizations/{organization}/databases/{database}/branches

Path parameters

organizationstring required

The name of the organization the branch belongs to

databasestring required

The name of the database the branch belongs to

Request body

namestring required

The name of the branch to create

parent_branchstring

The name of the parent branch. Defaults to the database's default branch if not provided.

backup_idstring

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.

regionstring

The region to create the branch in. If not provided, the branch will be created in the default region for its database.

restore_pointstring

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_sizestring

The database cluster size. Required if a backup_id is provided, optional otherwise. Options: PS_10, PS_20, PS_40, ..., PS_2800

major_versionstring

For PostgreSQL databases, the PostgreSQL major version to use for the branch. Defaults to the major version of the parent branch if it exists or the database's default branch major version. Ignored for branches restored from backups.

create_database_if_missingboolean

Create a new database for the branch if the database does not exist. Defaults to false.

kind'mysql' | 'postgresql'

The kind of branch to create. Required when create_database_if_missing is set.

Response

Returns the created branch

idstring required

The ID of the branch

namestring required

The name of the branch

created_atstring required

When the branch was created

updated_atstring required

When the branch was last updated

deleted_atstring nullable required

When the branch was deleted

restore_checklist_completed_atstring nullable required

When a user last marked a backup restore checklist as completed

schema_last_updated_atstring nullable required

When the schema for the branch was last updated

kind'mysql' | 'postgresql' required

The kind of branch

mysql_addressstring required

The MySQL address for the branch

mysql_edge_addressstring 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_vtgateboolean required

True if the branch allows passwords to connect directly to a vtgate, bypassing load balancers

vtgate_sizestring required

The size of the vtgate cluster for the branch

vtgate_countinteger required

The number of vtgate instances in the branch

cluster_namestring required

The SKU representing the branch's cluster size

cluster_iopsinteger nullable required

IOPS for the cluster

readyboolean required

Whether or not the branch is ready to serve queries

schema_readyboolean required

Whether or not the schema is ready for queries

metalboolean required

Whether or not this is a metal database

productionboolean required

Whether or not the branch is a production branch

safe_migrationsboolean required

Whether or not the branch has safe migrations enabled

shardedboolean required

Whether or not the branch is sharded

shard_countinteger required

The number of shards in the branch

keyspace_countinteger required

The number of keyspaces in the branch

stale_schemaboolean required

Whether or not the branch has a stale schema

private_edge_connectivityboolean required

True if private connections are enabled

has_replicasboolean required

True if the branch has replica servers

has_read_only_replicasboolean required

True if the branch has read-only replica servers

html_urlstring required

Planetscale app URL for the branch

urlstring required

Planetscale API URL for the branch

parent_branchstring nullable required

The name of the parent branch from which the branch was created

vtgate_optionsobject required

VTGate configuration options