> ## Documentation Index
> Fetch the complete documentation index at: https://planetscale.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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; 2026 PlanetScale, Inc.
  version: v1
  x-copyright: '&copy; 2026 PlanetScale, Inc.'
servers:
  - url: https://api.planetscale.com/v1
security:
  - oauth2: []
tags:
  - name: BackupPolicies
    description: |2
                Resources for managing database backup policies.
  - name: Backups
    description: |2
                Resources for managing database branch backups.
  - name: Branch changes
    description: |2
                Resources for managing cluster changes.
  - name: Branch config changes
    description: |2
                Resources for managing branch-level configuration change requests.
  - 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 config changes
    description: |2
                Resources for managing keyspace-level configuration change requests.
  - name: Keyspace VSchemas
    description: |2
                Resources for managing VSchemas within a keyspace.
  - name: MaintenanceSchedules
    description: |2
                Resources for viewing database maintenance schedules for Vitess databases (Enterprise only).
  - name: MaintenanceWindows
    description: |2
                Resources for viewing maintenance windows for a Vitess database (Enterprise only).
  - 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: Schema recommendations
    description: |2
                Resources for managing schema recommendations within a database.
  - name: Service tokens
    description: |2
                API endpoints for managing service tokens within an organization.
  - name: Shard config changes
    description: |2
                Resources for managing shard-level configuration change requests.
                Only available for custom-sharded keyspaces.
  - name: Traffic budgets
    description: |2
                Resources for managing traffic budgets.
  - name: Traffic rules
    description: |2
                Resources for managing traffic rules for a traffic budget.
  - 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: Team members
    description: |2
                  Resources for managing team memberships within an organization. Team members inherit access to databases assigned to their team.

                  Note: Teams managed through SSO/directory services cannot have members added or removed via API.
  - 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: >-
                    The name of the parent branch. Defaults to the database's
                    default branch if not provided.
                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. Required if a backup_id is
                    provided, optional otherwise. Options: PS_10, PS_20, PS_40,
                    ..., PS_2800
                storage:
                  type: object
                  properties:
                    minimum_storage_bytes:
                      type: integer
                      description: The minimum storage size in bytes.
                    maximum_storage_bytes:
                      type: integer
                      description: The maximum storage size in bytes for autoscaling.
                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.
              required:
                - name
      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
                    nullable: true
                  restore_checklist_completed_at:
                    type: string
                    description: >-
                      When a user last marked a backup restore checklist as
                      completed
                    nullable: true
                  schema_last_updated_at:
                    type: string
                    description: When the schema for the branch was last updated
                    nullable: true
                  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
                    nullable: true
                  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
                    required:
                      - id
                      - display_name
                      - avatar_url
                    nullable: true
                  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
                        nullable: true
                    required:
                      - id
                      - name
                      - created_at
                      - updated_at
                      - deleted_at
                    nullable: true
                  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
                      mysql_supported:
                        type: boolean
                        description: Whether the region supports MySQL/Vitess databases
                      postgresql_supported:
                        type: boolean
                        description: Whether the region supports PostgreSQL databases
                    required:
                      - id
                      - provider
                      - enabled
                      - public_ip_addresses
                      - display_name
                      - location
                      - slug
                      - current_default
                      - mysql_supported
                      - postgresql_supported
                  parent_branch:
                    type: string
                    description: >-
                      The name of the parent branch from which the branch was
                      created
                    nullable: true
                  vtgate_options:
                    type: object
                    additionalProperties: true
                    description: VTGate configuration options
                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
                  - vtgate_options
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
        '500':
          description: Internal Server Error
components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://auth.planetscale.com/oauth/authorize
          tokenUrl: https://auth.planetscale.com/oauth/token
          scopes:
            email: Read user email
            openid: OpenID Connect scope
            profile: Read user profile
            read_databases: Read organization databases
            read_user: Read user
            read_organization: Read organization
            write_databases: Write organization databases
            write_user: Write user
            write_organization: Write organization
            branch:delete_backups: Delete backups
            branch:delete_branch: Delete a database branch
            branch:manage_passwords: Read, write, and delete branch passwords
            branch:manage_read_only_passwords: Read, write, and delete read only branch passwords
            branch:read_backups: Read backups
            branch:read_branch: Read a database branch
            branch:restore_backups: Restore this branch's backups to new branches
            branch:write_backups: Create and update backups
            branch:write_branch: Write a database branch
            database:approve_deploy_requests: Approve deploy requests in a database
            database:delete_backups: Delete backups
            database:delete_branches: Delete database branches
            database:delete_database: Delete a database
            database:delete_members: Delete members
            database:delete_production_branch_backups: Delete production backups
            database:delete_production_branches: Delete a production database branch
            database:demote_branches: Demote production database branches
            database:deploy_deploy_requests: Deploy deploy requests in a database
            database:manage_passwords: Read, write, and delete database branch passwords
            database:manage_production_branch_passwords: Read, write, and delete production branch passwords
            database:manage_production_read_only_passwords: >-
              Read, write, and delete production read only branch passwords in
              an organization
            database:manage_read_only_passwords: >-
              Read, write, and delete read only branch passwords in an
              organization
            database:promote_branches: Promote database branches
            database:read_backups: Read backups
            database:read_branches: Read database branches
            database:read_comments: Read deploy request comments in a database
            database:read_database: Read database information
            database:read_deploy_requests: Read deploy requests in a database
            database:read_members: Read members
            database:restore_backups: Restore backups to new branches
            database:restore_production_branch_backups: Restore production branch backups to new branches
            database:write_backups: Create and update backups
            database:write_branches: Write database branches
            database:write_comments: Create deploy request comments in a database
            database:write_database: Write database
            database:write_deploy_requests: Create and update deploy requests in a database
            database:write_members: Write members
            organization:approve_deploy_requests: Approve deploy requests in an organization
            organization:create_databases: Create organization databases
            organization:delete_backups: Delete backups in an organization
            organization:delete_branches: Delete branches in an organization
            organization:delete_databases: Delete organization databases
            organization:delete_members: Delete members in an organization
            organization:delete_organization: Delete organization
            organization:delete_production_branch_backups: Delete production backups in an organization
            organization:delete_production_branches: Delete a production branch in an organization
            organization:deploy_deploy_requests: Deploy deploy requests in an organization
            organization:manage_passwords: Read, write, and delete branch passwords in an organization
            organization:manage_production_branch_passwords: >-
              Read, write, and delete production branch passwords in an
              organization
            organization:manage_production_read_only_passwords: >-
              Read, write, and delete production read only branch passwords in
              an organization
            organization:manage_read_only_passwords: >-
              Read, write, and delete read only branch passwords in an
              organization
            organization:promote_branches: Promote branches in an organization
            organization:read_backups: Read backups in an organization
            organization:read_branches: Read branches in an organization
            organization:read_comments: Read deploy request comments in an organization
            organization:read_databases: Read organization databases
            organization:read_deploy_requests: Read deploy requests in an organization
            organization:read_invoices: Read organization invoices
            organization:read_members: Read members in an organization
            organization:read_organization: Read organization
            organization:restore_backups: Restore backups to new branches in an organization
            organization:restore_production_branch_backups: >-
              Restore production branch backups to new branches in an
              organization
            organization:write_backups: Create and update backups in an organization
            organization:write_branches: Write branches in an organization
            organization:write_comments: Create deploy request comments in an organization
            organization:write_databases: Write organization databases
            organization:write_deploy_requests: Create and update deploy requests in an organization
            organization:write_members: Write members in an organization
            organization:write_organization: Write organization
            user:read_organizations: Read a user's organizations
            user:read_user: Read user
            user:write_user: Write user

````