POST
/
organizations
/
{organization}
/
databases
/
{database}
/
branches
Create a branch
curl --request POST \
  --url https://api.planetscale.com/v1/organizations/{organization}/databases/{database}/branches \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "<string>",
  "parent_branch": "<string>",
  "backup_id": "<string>",
  "region": "<string>",
  "restore_point": "<string>",
  "seed_data": "last_successful_backup",
  "cluster_size": "<string>"
}'
{
  "id": "<string>",
  "name": "<string>",
  "created_at": "<string>",
  "updated_at": "<string>",
  "deleted_at": "<string>",
  "restore_checklist_completed_at": "<string>",
  "schema_last_updated_at": "<string>",
  "kind": "mysql",
  "mysql_address": "<string>",
  "mysql_edge_address": "<string>",
  "state": "pending",
  "vtgate_size": "<string>",
  "vtgate_count": 123,
  "cluster_name": "<string>",
  "cluster_iops": 123,
  "ready": true,
  "schema_ready": true,
  "metal": true,
  "production": true,
  "safe_migrations": true,
  "sharded": true,
  "shard_count": 123,
  "stale_schema": true,
  "actor": {
    "id": "<string>",
    "display_name": "<string>",
    "avatar_url": "<string>"
  },
  "restored_from_branch": {
    "id": "<string>",
    "name": "<string>",
    "created_at": "<string>",
    "updated_at": "<string>",
    "deleted_at": "<string>"
  },
  "private_edge_connectivity": true,
  "has_replicas": true,
  "has_read_only_replicas": true,
  "html_url": "<string>",
  "url": "<string>",
  "region": {
    "id": "<string>",
    "provider": "<string>",
    "enabled": true,
    "public_ip_addresses": [
      "<string>"
    ],
    "display_name": "<string>",
    "location": "<string>",
    "slug": "<string>",
    "current_default": true
  },
  "parent_branch": "<string>"
}

Authorizations

​
Authorization
string
header
required

Path Parameters

​
organization
string
required

The name of the organization the branch belongs to

​
database
string
required

The name of the database the branch belongs to

Body

application/json
​
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
enum<string>

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.

Available options:
last_successful_backup
​
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

Returns the created branch

​
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
enum<string>
required

The kind of branch

Available options:
mysql,
postgresql
​
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
enum<string>
required

The current state of the branch

Available options:
pending,
sleep_in_progress,
sleeping,
awakening,
ready
​
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
​
restored_from_branch
object
required
​
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
​
parent_branch
string
required

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