--- 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 to create - `deletion_protected` boolean — Whether deletion protection is enabled for the branch - `parent_branch` string — The name of the parent branch. Defaults to the database's default branch if not provided. - `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. Required if a backup_id is provided (unless keyspace_cluster_sizes covers every keyspace), optional otherwise. Options: PS_10, PS_20, PS_40, ..., PS_2800 - `keyspace_cluster_sizes` string[] — For MySQL backup restores, per-keyspace cluster sizes. Each entry is { "keyspace_name": "main", "cluster_size": "PS_40" }. When provided, each restored keyspace must have a size here or via cluster_size. - `storage` object - `minimum_storage_bytes` integer — The minimum storage size in bytes. - `maximum_storage_bytes` integer — The maximum storage size in bytes for autoscaling. - `major_version` string — 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_missing` boolean — 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 `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, nullable, required — When the branch was deleted - `restore_checklist_completed_at` string, nullable, required — When a user last marked a backup restore checklist as completed - `schema_last_updated_at` string, nullable, 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_name` string, nullable, required — The public SKU representing the VTGate size - `vtgate_count` integer, required — The number of vtgate instances in the branch - `vtgate_autoscaling` boolean, required — Whether VTGate autoscaling is enabled - `vtgate_max_count` integer, nullable, required — The maximum number of VTGate instances when autoscaling is enabled - `vtgate_target_cpu_utilization` integer, nullable, required — The target CPU utilization for VTGate autoscaling - `cluster_name` string, required — The SKU representing the branch's cluster size - `cluster_iops` integer, nullable, 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 - `deletion_protected` boolean, required — Whether deletion protection is enabled for the branch - `sharded` boolean, required — Whether or not the branch is sharded - `shard_count` integer, required — The number of shards in the branch - `keyspace_count` integer, required — The number of keyspaces in the branch - `stale_schema` boolean, required — Whether or not the branch has a stale schema - `actor` object, nullable, 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, nullable, 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, nullable, 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 - `mysql_supported` boolean, required — Whether the region supports MySQL/Vitess databases - `postgresql_supported` boolean, required — Whether the region supports PostgreSQL databases - `parent_branch` string, nullable, required — The name of the parent branch from which the branch was created - `vtgate_options` object, required — VTGate configuration options ## Other responses - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found - `500` — Internal Server Error ## Changes - **2026-08-13** `69bdece4890a` — 1 breaking - removed the required property `deletion_protection_managed` from the response with the `201` status - **2026-08-12** `fd4480152110` — 3 info - added the new optional request property `deletion_protected` - added the required property `deletion_protected` to the response with the `201` status - added the required property `deletion_protection_managed` to the response with the `201` status - **2026-08-11** `4b2e4f05bda2` — 5 info - added the new optional request property `keyspace_cluster_sizes` - added the required property `vtgate_autoscaling` to the response with the `201` status - added the required property `vtgate_max_count` to the response with the `201` status - added the required property `vtgate_name` to the response with the `201` status - …1 more - **2026-07-08** `fa19f3305241` — 1 info - added the required property `keyspace_count` to the response with the `201` status - **2026-06-01** `72506953f367` — 8 breaking, 5 info - the response property `actor` became nullable for the status `201` - the response property `cluster_iops` became nullable for the status `201` - the response property `deleted_at` became nullable for the status `201` - the response property `parent_branch` became nullable for the status `201` - …9 more [Full history](https://skmtc.dev/planetscale/apis/planetscale-api/changes/organizations/:organization/databases/:database/branches/post.md) --- [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/6d28c038c4fd/schema)