# Source: https://planetscale.com/docs/api/reference/create_branch.md

# 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` |



## OpenAPI

````yaml post /organizations/{organization}/databases/{database}/branches
openapi: 3.0.1
info:
  title: PlanetScale API
  description: |-

    <p>PlanetScale API</p>
    &copy; 2025 PlanetScale, Inc.
  version: v1
  x-copyright: '&copy; 2025 PlanetScale, Inc.'
servers:
  - url: https://api.planetscale.com/v1
security:
  - ApiKeyHeader:
      - Authorization
tags:
  - name: Backups
    description: |2
                Resources for managing database branch backups.
  - name: Branch changes
    description: |2
                Resources for managing cluster changes.
  - name: Cluster extensions
    description: |2
                Resources for managing cluster extension configuration.
  - name: Branch log signatures
    description: |2
                Resources for retrieving branch log access signatures.
  - name: Cluster parameters
    description: |2
                Resources for managing cluster configuration parameters.
  - name: Database branch keyspaces
    description: |2
                Resources for managing keyspaces.
  - name: Database branch passwords
    description: |2
                Resources for managing database branch passwords.
  - name: Database Postgres IP restrictions
    description: |2
                Resources for managing Postgres IP restriction entries for databases.

                Note: This endpoint is only available for PostgreSQL databases. For MySQL databases, use the Database Branch Passwords endpoint.
  - name: Databases
    description: |2
                  Resources for managing databases within an organization.
  - name: Keyspace VSchemas
    description: |2
                Resources for managing VSchemas within a keyspace.
  - name: OAuth applications
    description: |2
                Resources for managing OAuth applications.
  - name: OAuth tokens
    description: |2
                Resources for managing OAuth tokens.
  - name: Organization members
    description: |2
                Resources for managing organization members and their roles.
  - name: Organizations
    description: |2
                  Resources for managing organizations.
  - name: Bouncer resizes
    description: |2
                Resources for managing Postgres bouncer resize requests.
  - name: Bouncers
    description: |2
                Resources for managing postgres bouncers.
  - name: Roles
    description: |2
                Resources for managing role credentials.
  - name: Query Insights reports
    description: |2
                Resources for downloading query insights data.
  - name: Service tokens
    description: |2
                API endpoints for managing service tokens within an organization.
  - name: Users
    description: |2
                Resources for managing users.
  - name: Workflows
    description: |2
                API endpoints for managing workflows.
  - name: Deploy requests
    description: |2
                  Resources for managing deploy requests.
  - name: Webhooks
    description: |2
                  Resources for managing database webhooks.
  - name: Invoices
    description: |2
                  Resources for managing invoices.
  - name: Organization teams
    description: |2
                  Resources for managing teams within an organization. Teams allow you to group members and grant them access to specific databases.

                  Note: Teams managed through SSO/directory services cannot be modified via API.
paths:
  /organizations/{organization}/databases/{database}/branches:
    post:
      tags:
        - Database branches
      summary: Create a branch
      description: >-

        ### 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` |
      operationId: create_branch
      parameters:
        - name: organization
          in: path
          required: true
          description: The name of the organization the branch belongs to
          schema:
            type: string
        - name: database
          in: path
          required: true
          description: The name of the database the branch belongs to
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: The name of the branch to create
                parent_branch:
                  type: string
                  description: Parent branch
                backup_id:
                  type: string
                  description: >-
                    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:
                  type: string
                  description: >-
                    The region to create the branch in. If not provided, the
                    branch will be created in the default region for its
                    database.
                restore_point:
                  type: string
                  description: >-
                    Restore from a point-in-time recovery timestamp (e.g.
                    2023-01-01T00:00:00Z). Available only for PostgreSQL
                    databases.
                seed_data:
                  type: string
                  enum:
                    - last_successful_backup
                  description: >-
                    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:
                  type: string
                  description: >-
                    The database cluster size is required if a backup_id is
                    provided. Options: PS_10, PS_20, PS_40, ..., PS_2800
                major_version:
                  type: string
                  description: >-
                    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.
              additionalProperties: false
              required:
                - name
                - parent_branch
      responses:
        '201':
          description: Returns the created branch
          headers: {}
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: The ID of the branch
                  name:
                    type: string
                    description: The name of the branch
                  created_at:
                    type: string
                    description: When the branch was created
                  updated_at:
                    type: string
                    description: When the branch was last updated
                  deleted_at:
                    type: string
                    description: When the branch was deleted
                  restore_checklist_completed_at:
                    type: string
                    description: >-
                      When a user last marked a backup restore checklist as
                      completed
                  schema_last_updated_at:
                    type: string
                    description: When the schema for the branch was last updated
                  kind:
                    type: string
                    enum:
                      - mysql
                      - postgresql
                    description: The kind of branch
                  mysql_address:
                    type: string
                    description: The MySQL address for the branch
                  mysql_edge_address:
                    type: string
                    description: The address of the MySQL provider for the branch
                  state:
                    type: string
                    enum:
                      - pending
                      - sleep_in_progress
                      - sleeping
                      - awakening
                      - ready
                    description: The current state of the branch
                  direct_vtgate:
                    type: boolean
                    description: >-
                      True if the branch allows passwords to connect directly to
                      a vtgate, bypassing load balancers
                  vtgate_size:
                    type: string
                    description: The size of the vtgate cluster for the branch
                  vtgate_count:
                    type: integer
                    description: The number of vtgate instances in the branch
                  cluster_name:
                    type: string
                    description: The SKU representing the branch's cluster size
                  cluster_iops:
                    type: integer
                    description: IOPS for the cluster
                  ready:
                    type: boolean
                    description: Whether or not the branch is ready to serve queries
                  schema_ready:
                    type: boolean
                    description: Whether or not the schema is ready for queries
                  metal:
                    type: boolean
                    description: Whether or not this is a metal database
                  production:
                    type: boolean
                    description: Whether or not the branch is a production branch
                  safe_migrations:
                    type: boolean
                    description: Whether or not the branch has safe migrations enabled
                  sharded:
                    type: boolean
                    description: Whether or not the branch is sharded
                  shard_count:
                    type: integer
                    description: The number of shards in the branch
                  stale_schema:
                    type: boolean
                    description: Whether or not the branch has a stale schema
                  actor:
                    type: object
                    properties:
                      id:
                        type: string
                        description: The ID of the actor
                      display_name:
                        type: string
                        description: The name of the actor
                      avatar_url:
                        type: string
                        description: The URL of the actor's avatar
                    additionalProperties: false
                    required:
                      - id
                      - display_name
                      - avatar_url
                  restored_from_branch:
                    type: object
                    properties:
                      id:
                        type: string
                        description: The ID for the resource
                      name:
                        type: string
                        description: The name for the resource
                      created_at:
                        type: string
                        description: When the resource was created
                      updated_at:
                        type: string
                        description: When the resource was last updated
                      deleted_at:
                        type: string
                        description: When the resource was deleted, if deleted
                    additionalProperties: false
                    required:
                      - id
                      - name
                      - created_at
                      - updated_at
                      - deleted_at
                  private_edge_connectivity:
                    type: boolean
                    description: True if private connections are enabled
                  has_replicas:
                    type: boolean
                    description: True if the branch has replica servers
                  has_read_only_replicas:
                    type: boolean
                    description: True if the branch has read-only replica servers
                  html_url:
                    type: string
                    description: Planetscale app URL for the branch
                  url:
                    type: string
                    description: Planetscale API URL for the branch
                  region:
                    type: object
                    properties:
                      id:
                        type: string
                        description: The ID of the region
                      provider:
                        type: string
                        description: Provider for the region (ex. AWS)
                      enabled:
                        type: boolean
                        description: Whether or not the region is currently active
                      public_ip_addresses:
                        items:
                          type: string
                        type: array
                        description: Public IP addresses for the region
                      display_name:
                        type: string
                        description: Name of the region
                      location:
                        type: string
                        description: Location of the region
                      slug:
                        type: string
                        description: The slug of the region
                      current_default:
                        type: boolean
                        description: >-
                          True if the region is the default for new branch
                          creation
                    additionalProperties: false
                    required:
                      - id
                      - provider
                      - enabled
                      - public_ip_addresses
                      - display_name
                      - location
                      - slug
                      - current_default
                  parent_branch:
                    type: string
                    description: >-
                      The name of the parent branch from which the branch was
                      created
                additionalProperties: false
                required:
                  - id
                  - name
                  - created_at
                  - updated_at
                  - deleted_at
                  - restore_checklist_completed_at
                  - schema_last_updated_at
                  - kind
                  - mysql_address
                  - mysql_edge_address
                  - state
                  - direct_vtgate
                  - vtgate_size
                  - vtgate_count
                  - cluster_name
                  - cluster_iops
                  - ready
                  - schema_ready
                  - metal
                  - production
                  - safe_migrations
                  - sharded
                  - shard_count
                  - stale_schema
                  - actor
                  - restored_from_branch
                  - private_edge_connectivity
                  - has_replicas
                  - has_read_only_replicas
                  - html_url
                  - url
                  - region
                  - parent_branch
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
        '500':
          description: Internal Server Error
components:
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: Authorization

````

---

> To find navigation and other pages in this documentation, fetch the llms.txt file at: https://planetscale.com/llms.txt