--- 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 - `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 - `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. ## 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 ## Changes - **2025-12-04** `64acae2158c7` — 1 breaking, 1 warning - added the new required request property `name` - removed the request property `branch` - **2025-12-04** `5e881928d77a` — 1 breaking, 1 warning, 1 info - added the new required request property `branch` - removed the request property `name` - added the new optional request property `major_version` [Change 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/64acae2158c7/schema)