PlanetScale API
© 2026 PlanetScale, Inc. version: v1 x-copyright: '© 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: Branch Vitess parameters description: |2 Returns all editable Vitess parameter definitions with their current effective values for a branch. - 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: InsightsAgentRuns description: |2 Resources for running and viewing Insights agent analyses. - name: Insights Agent schedules description: Resources for managing Insights Agent schedules. - name: Keyspace config changes description: |2 Resources for managing keyspace-level configuration change requests. - name: Keyspace resizes description: |2 Resources for managing keyspace resize 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: Metrics description: |2 Resources for retrieving database metrics. - name: MoveTables description: |2 API endpoints for creating and managing Vitess MoveTables workflows on a branch. - name: OAuth applications description: |2 Resources for managing OAuth applications. - name: OAuth tokens description: |2 Resources for managing OAuth tokens. - name: Organization invitations description: |2 Resources for inviting people to an organization. Service tokens with `write_members` can list, send, and cancel invitations, but can only invite people as members. Only organization administrators can invite people as administrators or analysts. - 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: Switchovers description: |2 Resources for moving the primary of a Postgres branch. - name: Query Insights reports description: |2 Resources for downloading query insights data. - name: Dedicated read replicas description: |2 Resources for managing Postgres dedicated read replicas. - name: Roles description: |2 Resources for managing role credentials. - 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: VtctldOperations description: |2 API endpoints for checking the result of asynchronous vtctld operations, such as MoveTables commands. - 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: AuthAttemptExports description: |2 Resources for creating and downloading organization auth attempt exports. - name: Billing payment method setup description: |2 Resources for adding an organization's payment method through hosted checkout. - name: Billing payment method description: |2 Resources for managing an organization's payment method. - name: Invoices description: |2 Resources for managing invoices. - name: Organization SSO domains description: |2 Resources for listing and verifying organization email domains used for SSO. - name: Organization SSO description: |2 Resources for enabling SSO, verifying email domains, and configuring an identity provider. - 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/{branch}/dedicated-read-replicas: post: tags: - Dedicated read replicas summary: Create a dedicated read replica 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** `write_database` **OAuth Scopes** | Resource | Scopes | | :------- | :---------- | | Organization | `write_databases` | | Database | `write_database` | operationId: create_dedicated_read_replica parameters: - name: organization in: path required: true description: 'Organization name slug from `list_organizations`. Example: `acme`.' schema: type: string - name: database in: path required: true description: 'Database name slug from `list_databases`. Example: `app-db`.' schema: type: string - name: branch in: path required: true description: 'Branch name from `list_branches`. Example: `main`.' schema: type: string requestBody: content: application/json: schema: type: object properties: name: type: string description: The dedicated read replica name region: type: string description: The region slug for the dedicated read replica replicas: type: integer description: The number of instances serving reads. Defaults to 1. cluster_size: type: string description: >- The cluster size SKU name. Defaults to the primary cluster size. 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. storage_autoscaling: type: boolean description: Whether storage autoscaling is enabled. storage_iops: type: integer description: The storage IOPS. storage_throughput_mibs: type: integer description: The storage throughput in MiB/s. required: - name - region responses: '200': description: Returns the new dedicated read replica headers: {} content: application/json: schema: type: object properties: id: type: string description: The ID of the dedicated read replica name: type: string description: The name of the dedicated read replica state: type: string description: >- The state of the dedicated read replica: pending, ready, or deleting replicas: type: integer description: >- The number of instances serving reads in this dedicated read replica cluster_name: type: string description: >- The SKU representing the cluster size of the dedicated read replica cluster_display_name: type: string description: >- The SKU representing the cluster size of the dedicated read replica, for display access_host_url: type: string description: >- The database connection host for the dedicated read replica private_access_host_url: type: string description: >- The private database connection host for the dedicated read replica private_connection_service_name: type: string description: >- The service name to set up private connectivity for the dedicated read replica nullable: true minimum_storage_bytes: type: integer description: The minimum storage size in bytes nullable: true maximum_storage_bytes: type: integer description: The maximum storage size in bytes nullable: true storage_autoscaling: type: boolean description: Whether storage autoscaling is enabled nullable: true storage_type: type: string enum: - gp3 - io2 - pd_ssd - hyperdisk_balanced - premium_v2_lrs description: The storage type nullable: true storage_iops: type: integer description: The storage IOPS nullable: true storage_throughput_mibs: type: integer description: The storage throughput in MiB/s nullable: true volume_modifications_blocked_until: type: string description: When volume modifications will be allowed again nullable: true created_at: type: string description: When the dedicated read replica was created updated_at: type: string description: When the dedicated read replica was last updated ready_at: type: string description: When the dedicated read replica was ready to serve queries nullable: true ready: type: boolean description: >- Whether or not the dedicated read replica is ready to serve queries 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 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 neki_supported: type: boolean description: Whether the region supports Neki databases required: - id - provider - enabled - public_ip_addresses - display_name - location - slug - current_default - mysql_supported - postgresql_supported - neki_supported parameters: type: array items: type: object properties: id: type: string description: The ID of the parameter namespace: type: string enum: - pgconf description: The namespace of the parameter name: type: string description: The name of the parameter display_name: type: string description: The display name of the parameter category: type: string description: The category of the parameter description: type: string description: The description of the parameter immutable: type: boolean description: Whether the parameter can be changed parameter_type: type: string enum: - integer - time description: The type of the parameter default_value: type: string description: >- The default value of the parameter, which is the primary's current value disabled_reason: type: string description: Why the parameter cannot be changed nullable: true value: type: string description: The configured value of the parameter required: type: boolean description: Whether the parameter is required created_at: type: string description: When the parameter was created nullable: true updated_at: type: string description: When the parameter was last updated nullable: true restart: type: boolean description: True if processes require a server restart on change max: type: number description: The maximum value of the parameter min: type: number description: >- The minimum value of the parameter, floored at the primary's current value url: type: string description: The URL of the parameter options: items: type: string type: array description: Valid options for the parameter value units: items: type: string type: array description: Display units for the parameter value 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 required: - id - namespace - name - display_name - category - description - immutable - parameter_type - default_value - value - required - created_at - updated_at - restart - max - min - url - options - units - actor required: - id - name - state - replicas - cluster_name - cluster_display_name - access_host_url - private_access_host_url - private_connection_service_name - minimum_storage_bytes - maximum_storage_bytes - storage_autoscaling - storage_type - storage_iops - storage_throughput_mibs - volume_modifications_blocked_until - created_at - updated_at - ready_at - ready - actor - region - parameters '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found '422': description: Unprocessable Entity '429': description: >- Too Many Requests. Reduce the frequency of requests and try again soon. '500': description: Internal Server Error components: securitySchemes: oauth2: type: oauth2 flows: authorizationCode: authorizationUrl: https://app.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:manage_topology: Manage shard primaries and tablet serving for this branch 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_branch_topologies: >- Manage shard primaries and tablet serving for development branches 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_branch_topologies: >- Manage shard primaries and tablet serving for production branches in a database 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:read_workflows: Read database workflows 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 database:write_workflows: Create and manage database workflows 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_branch_topologies: >- Manage shard primaries and tablet serving for development branches 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_branch_topologies: >- Manage shard primaries and tablet serving for production branches 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:manage_sso: Enable, configure, and disable organization SSO organization:promote_branches: Promote branches in an organization organization:read_audit_logs: Read organization audit logs 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:read_payment_method: Read organization payment method organization:read_workflows: Read workflows in an 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 organization:write_payment_method: Update and delete the organization payment method organization:write_workflows: Create and manage workflows in an organization user:read_organizations: Read a user's organizations user:read_user: Read user user:write_user: Write user ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.