openapi: 3.1.0
info:
title: PlanetScale Platform API
description: >-
The PlanetScale Platform API provides programmatic access to manage
PlanetScale serverless MySQL-compatible databases. It allows developers
to create and manage databases, branches, deploy requests, passwords,
backups, service tokens, organization members, teams, bouncers, and
billing data. The API supports authentication via service tokens and
OAuth, enabling integration into CI/CD pipelines and
infrastructure-as-code workflows.
version: '1.0.0'
contact:
name: PlanetScale Support
url: https://support.planetscale.com
termsOfService: https://planetscale.com/legal/tos
license:
name: Proprietary
url: https://planetscale.com/legal/tos
externalDocs:
description: PlanetScale API Documentation
url: https://planetscale.com/docs/api/reference/getting-started-with-planetscale-api
servers:
- url: https://api.planetscale.com/v1
description: PlanetScale Production API
tags:
- name: Backups
description: >-
Manage database branch backups, including listing, creating, and
retrieving backup details.
- name: Billing
description: >-
Access organization billing data and invoices programmatically.
- name: Bouncers
description: >-
Manage PgBouncer connection pooling instances for database branches,
including creating, listing, resizing, and deleting bouncers.
- name: Branches
description: >-
Manage database branches for schema development and safe migrations,
including creating, listing, updating, and deleting branches.
- name: Cluster Sizes
description: >-
Retrieve available cluster size SKUs for Vitess and Postgres
database branches.
- name: Databases
description: >-
Manage PlanetScale databases, including creating, listing, updating
settings, and deleting databases.
- name: Deploy Requests
description: >-
Manage deploy requests for applying schema changes from development
branches to production, including creating, reviewing, queueing,
and completing deployments.
- name: IP Restrictions
description: >-
Manage IP restriction entries for controlling database access
by IP address.
- name: Organization Members
description: >-
Manage members within an organization, including listing, retrieving,
updating roles, and removing members.
- name: Organizations
description: >-
Manage PlanetScale organizations, including listing organizations
and retrieving organization details.
- name: Passwords
description: >-
Manage branch passwords and connection credentials for connecting
applications to database branches.
- name: Query Patterns
description: >-
Analyze and report on query patterns for database branches.
- name: Roles
description: >-
Manage role-based credentials for database access.
- name: Schema Recommendations
description: >-
View and manage schema recommendations for optimizing database
performance and structure.
- name: Service Tokens
description: >-
Manage service tokens for API authentication, including creating,
listing, and deleting tokens and their access grants.
- name: Teams
description: >-
Manage teams within an organization, including creating teams, adding
members, and controlling database access.
- name: Webhooks
description: >-
Manage webhook configurations for database event notifications.
security:
- serviceToken: []
paths:
/organizations:
get:
operationId: listOrganizations
summary: List organizations
description: >-
Returns a list of all organizations the authenticated user or
service token has access to.
tags:
- Organizations
responses:
'200':
description: Successful response with list of organizations
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Organization'
'401':
$ref: '#/components/responses/Unauthorized'
/organizations/{organization}:
get:
operationId: getOrganization
summary: Get an organization
description: >-
Returns details about a specific organization by name.
tags:
- Organizations
parameters:
- $ref: '#/components/parameters/OrganizationParam'
responses:
'200':
description: Successful response with organization details
content:
application/json:
schema:
$ref: '#/components/schemas/Organization'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/organizations/{organization}/members:
get:
operationId: listOrganizationMembers
summary: List organization members
description: >-
Returns a list of all members in the specified organization.
Requires the read_organization permission on the service token.
tags:
- Organization Members
parameters:
- $ref: '#/components/parameters/OrganizationParam'
- $ref: '#/components/parameters/PageParam'
- $ref: '#/components/parameters/PerPageParam'
responses:
'200':
description: Successful response with list of organization members
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/OrganizationMember'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/organizations/{organization}/members/{member_id}:
get:
operationId: getOrganizationMember
summary: Get an organization member
description: >-
Returns details about a specific member in the organization.
Requires the read_organization permission.
tags:
- Organization Members
parameters:
- $ref: '#/components/parameters/OrganizationParam'
- $ref: '#/components/parameters/MemberIdParam'
responses:
'200':
description: Successful response with member details
content:
application/json:
schema:
$ref: '#/components/schemas/OrganizationMember'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
patch:
operationId: updateOrganizationMember
summary: Update an organization member
description: >-
Updates the role or properties of a specific member in the
organization. Requires the write_organization permission.
tags:
- Organization Members
parameters:
- $ref: '#/components/parameters/OrganizationParam'
- $ref: '#/components/parameters/MemberIdParam'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
role:
type: string
description: >-
The role to assign to the member.
enum:
- admin
- member
- database_admin
responses:
'200':
description: Member updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/OrganizationMember'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
delete:
operationId: deleteOrganizationMember
summary: Remove an organization member
description: >-
Removes a member from the organization. Requires the
write_organization permission.
tags:
- Organization Members
parameters:
- $ref: '#/components/parameters/OrganizationParam'
- $ref: '#/components/parameters/MemberIdParam'
responses:
'204':
description: Member removed successfully
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/organizations/{organization}/teams:
get:
operationId: listTeams
summary: List teams
description: >-
Returns a list of all teams in the specified organization.
tags:
- Teams
parameters:
- $ref: '#/components/parameters/OrganizationParam'
- $ref: '#/components/parameters/PageParam'
- $ref: '#/components/parameters/PerPageParam'
responses:
'200':
description: Successful response with list of teams
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Team'
'401':
$ref: '#/components/responses/Unauthorized'
post:
operationId: createTeam
summary: Create a team
description: >-
Creates a new team in the specified organization.
tags:
- Teams
parameters:
- $ref: '#/components/parameters/OrganizationParam'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- name
properties:
name:
type: string
description: >-
The name of the team.
description:
type: string
description: >-
A description of the team.
responses:
'201':
description: Team created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Team'
'401':
$ref: '#/components/responses/Unauthorized'
'422':
$ref: '#/components/responses/UnprocessableEntity'
/organizations/{organization}/teams/{team_slug}:
get:
operationId: getTeam
summary: Get a team
description: >-
Returns details about a specific team in the organization.
tags:
- Teams
parameters:
- $ref: '#/components/parameters/OrganizationParam'
- $ref: '#/components/parameters/TeamSlugParam'
responses:
'200':
description: Successful response with team details
content:
application/json:
schema:
$ref: '#/components/schemas/Team'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
patch:
operationId: updateTeam
summary: Update a team
description: >-
Updates the name or description of a specific team.
tags:
- Teams
parameters:
- $ref: '#/components/parameters/OrganizationParam'
- $ref: '#/components/parameters/TeamSlugParam'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: >-
The updated name of the team.
description:
type: string
description: >-
The updated description of the team.
responses:
'200':
description: Team updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Team'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
delete:
operationId: deleteTeam
summary: Delete a team
description: >-
Deletes a team from the organization.
tags:
- Teams
parameters:
- $ref: '#/components/parameters/OrganizationParam'
- $ref: '#/components/parameters/TeamSlugParam'
responses:
'204':
description: Team deleted successfully
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/organizations/{organization}/databases:
get:
operationId: listDatabases
summary: List databases
description: >-
Returns a list of all databases in the specified organization.
tags:
- Databases
parameters:
- $ref: '#/components/parameters/OrganizationParam'
- $ref: '#/components/parameters/PageParam'
- $ref: '#/components/parameters/PerPageParam'
responses:
'200':
description: Successful response with list of databases
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Database'
'401':
$ref: '#/components/responses/Unauthorized'
post:
operationId: createDatabase
summary: Create a database
description: >-
Creates a new database in the specified organization.
tags:
- Databases
parameters:
- $ref: '#/components/parameters/OrganizationParam'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- name
properties:
name:
type: string
description: >-
The name of the database.
plan:
type: string
description: >-
The billing plan for the database.
enum:
- hobby
- scaler
- scaler_pro
cluster_size:
type: string
description: >-
The cluster size for the production branch.
region:
type: string
description: >-
The region slug where the database will be created.
responses:
'201':
description: Database created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Database'
'401':
$ref: '#/components/responses/Unauthorized'
'422':
$ref: '#/components/responses/UnprocessableEntity'
/organizations/{organization}/databases/{database}:
get:
operationId: getDatabase
summary: Get a database
description: >-
Returns details about a specific database, including its
configuration, state, and production branch information.
tags:
- Databases
parameters:
- $ref: '#/components/parameters/OrganizationParam'
- $ref: '#/components/parameters/DatabaseParam'
responses:
'200':
description: Successful response with database details
content:
application/json:
schema:
$ref: '#/components/schemas/Database'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
patch:
operationId: updateDatabaseSettings
summary: Update database settings
description: >-
Updates settings for a specific database, such as production
branch protection, insights, and default branch.
tags:
- Databases
parameters:
- $ref: '#/components/parameters/OrganizationParam'
- $ref: '#/components/parameters/DatabaseParam'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
default_branch:
type: string
description: >-
The name of the default branch.
production_branch_web_console:
type: boolean
description: >-
Whether the web console is enabled for production branches.
insights_enabled:
type: boolean
description: >-
Whether PlanetScale Insights is enabled.
migration_framework:
type: string
description: >-
The migration framework used for schema changes.
migration_table_name:
type: string
description: >-
The name of the migration tracking table.
require_approval_for_deploy:
type: boolean
description: >-
Whether deploy requests require approval before deployment.
allow_data_branching:
type: boolean
description: >-
Whether data branching is enabled.
responses:
'200':
description: Database settings updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Database'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
delete:
operationId: deleteDatabase
summary: Delete a database
description: >-
Deletes a database and all of its branches. This action is
irreversible.
tags:
- Databases
parameters:
- $ref: '#/components/parameters/OrganizationParam'
- $ref: '#/components/parameters/DatabaseParam'
responses:
'204':
description: Database deleted successfully
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/organizations/{organization}/databases/{database}/branches:
get:
operationId: listBranches
summary: List branches
description: >-
Returns a list of all branches for a specific database.
tags:
- Branches
parameters:
- $ref: '#/components/parameters/OrganizationParam'
- $ref: '#/components/parameters/DatabaseParam'
- $ref: '#/components/parameters/PageParam'
- $ref: '#/components/parameters/PerPageParam'
responses:
'200':
description: Successful response with list of branches
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Branch'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
post:
operationId: createBranch
summary: Create a branch
description: >-
Creates a new branch for the specified database. Branches are
isolated copies of the database schema used for development
and testing.
tags:
- Branches
parameters:
- $ref: '#/components/parameters/OrganizationParam'
- $ref: '#/components/parameters/DatabaseParam'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- name
properties:
name:
type: string
description: >-
The name of the branch.
parent_branch:
type: string
description: >-
The name of the parent branch to fork from.
backup_id:
type: string
description: >-
The ID of a backup to restore the branch from.
seed_data:
type: string
description: >-
The seed data configuration for the branch.
cluster_size:
type: string
description: >-
The cluster size for the branch.
region:
type: string
description: >-
The region where the branch will be created.
responses:
'201':
description: Branch created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Branch'
'401':
$ref: '#/components/responses/Unauthorized'
'422':
$ref: '#/components/responses/UnprocessableEntity'
/organizations/{organization}/databases/{database}/branches/{branch}:
get:
operationId: getBranch
summary: Get a branch
description: >-
Returns details about a specific branch, including its schema
status, cluster configuration, and readiness state.
tags:
- Branches
parameters:
- $ref: '#/components/parameters/OrganizationParam'
- $ref: '#/components/parameters/DatabaseParam'
- $ref: '#/components/parameters/BranchParam'
responses:
'200':
description: Successful response with branch details
content:
application/json:
schema:
$ref: '#/components/schemas/Branch'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
patch:
operationId: updateBranch
summary: Update a branch
description: >-
Updates properties of a specific branch, such as its cluster
configuration.
tags:
- Branches
parameters:
- $ref: '#/components/parameters/OrganizationParam'
- $ref: '#/components/parameters/DatabaseParam'
- $ref: '#/components/parameters/BranchParam'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
cluster_size:
type: string
description: >-
The new cluster size for the branch.
responses:
'200':
description: Branch updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Branch'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
delete:
operationId: deleteBranch
summary: Delete a branch
description: >-
Deletes a database branch. Production branches cannot be deleted.
tags:
- Branches
parameters:
- $ref: '#/components/parameters/OrganizationParam'
- $ref: '#/components/parameters/DatabaseParam'
- $ref: '#/components/parameters/BranchParam'
responses:
'204':
description: Branch deleted successfully
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/organizations/{organization}/databases/{database}/branches/{branch}/schema-lint:
get:
operationId: lintBranchSchema
summary: Lint a branch schema
description: >-
Returns schema lint results for the specified branch, identifying
potential issues and recommendations.
tags:
- Branches
parameters:
- $ref: '#/components/parameters/OrganizationParam'
- $ref: '#/components/parameters/DatabaseParam'
- $ref: '#/components/parameters/BranchParam'
responses:
'200':
description: Successful response with lint results
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/SchemaLintError'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/organizations/{organization}/databases/{database}/deploy-requests:
get:
operationId: listDeployRequests
summary: List deploy requests
description: >-
Returns a list of all deploy requests for a specific database.
tags:
- Deploy Requests
parameters:
- $ref: '#/components/parameters/OrganizationParam'
- $ref: '#/components/parameters/DatabaseParam'
- $ref: '#/components/parameters/PageParam'
- $ref: '#/components/parameters/PerPageParam'
responses:
'200':
description: Successful response with list of deploy requests
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/DeployRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
post:
operationId: createDeployRequest
summary: Create a deploy request
description: >-
Creates a new deploy request to merge schema changes from a
development branch into the target branch.
tags:
- Deploy Requests
parameters:
- $ref: '#/components/parameters/OrganizationParam'
- $ref: '#/components/parameters/DatabaseParam'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- branch
properties:
branch:
type: string
description: >-
The name of the source branch containing schema changes.
into_branch:
type: string
description: >-
The name of the target branch to deploy into. Defaults
to the production branch.
notes:
type: string
description: >-
Notes or description for the deploy request.
responses:
'201':
description: Deploy request created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/DeployRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'422':
$ref: '#/components/responses/UnprocessableEntity'
/organizations/{organization}/databases/{database}/deploy-requests/{deploy_request_number}:
get:
operationId: getDeployRequest
summary: Get a deploy request
description: >-
Returns details about a specific deploy request, including its
status, schema changes, and deployment history.
tags:
- Deploy Requests
parameters:
- $ref: '#/components/parameters/OrganizationParam'
- $ref: '#/components/parameters/DatabaseParam'
- $ref: '#/components/parameters/DeployRequestNumberParam'
responses:
'200':
description: Successful response with deploy request details
content:
application/json:
schema:
$ref: '#/components/schemas/DeployRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
patch:
operationId: closeDeployRequest
summary: Close a deploy request
description: >-
Closes an open deploy request without deploying the changes.
tags:
- Deploy Requests
parameters:
- $ref: '#/components/parameters/OrganizationParam'
- $ref: '#/components/parameters/DatabaseParam'
- $ref: '#/components/parameters/DeployRequestNumberParam'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
state:
type: string
description: >-
The desired state of the deploy request.
enum:
- closed
responses:
'200':
description: Deploy request closed successfully
content:
application/json:
schema:
$ref: '#/components/schemas/DeployRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/organizations/{organization}/databases/{database}/deploy-requests/{deploy_request_number}/deploy:
post:
operationId: queueDeployRequest
summary: Queue a deploy request
description: >-
Queues a deploy request for deployment, applying the schema
changes to the target branch.
tags:
- Deploy Requests
parameters:
- $ref: '#/components/parameters/OrganizationParam'
- $ref: '#/components/parameters/DatabaseParam'
- $ref: '#/components/parameters/DeployRequestNumberParam'
responses:
'200':
description: Deploy request queued successfully
content:
application/json:
schema:
$ref: '#/components/schemas/DeployRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'422':
$ref: '#/components/responses/UnprocessableEntity'
/organizations/{organization}/databases/{database}/deploy-requests/{deploy_request_number}/reviews:
get:
operationId: listDeployRequestReviews
summary: List deploy request reviews
description: >-
Returns a list of reviews for a specific deploy request.
tags:
- Deploy Requests
parameters:
- $ref: '#/components/parameters/OrganizationParam'
- $ref: '#/components/parameters/DatabaseParam'
- $ref: '#/components/parameters/DeployRequestNumberParam'
responses:
'200':
description: Successful response with list of reviews
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/DeployRequestReview'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
post:
operationId: reviewDeployRequest
summary: Review a deploy request
description: >-
Submits a review for a deploy request, approving or requesting
changes.
tags:
- Deploy Requests
parameters:
- $ref: '#/components/parameters/OrganizationParam'
- $ref: '#/components/parameters/DatabaseParam'
- $ref: '#/components/parameters/DeployRequestNumberParam'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- state
properties:
state:
type: string
description: >-
The review state.
enum:
- approved
- changes_requested
- comment
# --- truncated at 32 KB (90 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/planetscale/refs/heads/main/openapi/planetscale-platform-api-openapi.yml